Source for file module_chat.php

Documentation is available at module_chat.php

  1. <?php
  2.     // This file is part of the Sloodle project (www.sloodle.org)
  3.     
  4.     /**
  5.     * This file defines a chat module for Sloodle.
  6.     *
  7.     * @package sloodle
  8.     * @copyright Copyright (c) 2008 Sloodle (various contributors)
  9.     * @license http://www.gnu.org/licenses/gpl-3.0.html GNU GPL v3
  10.     *
  11.     * @contributor Peter R. Bloomfield
  12.     */
  13.     
  14.     /** The Sloodle module base. */
  15.     require_once(SLOODLE_LIBROOT.'/modules/module_base.php');
  16.     /** General Sloodle functions. */
  17.     require_once(SLOODLE_LIBROOT.'/general.php');
  18.     
  19.     /**
  20.     * The Sloodle chat module class.
  21.     * @package sloodle
  22.     */
  23.     class SloodleModuleChat extends SloodleModule
  24.     {
  25.     // DATA //
  26.     
  27.         /**
  28.         * Internal for Moodle only - course module instance.
  29.         * Corresponds to one record from the Moodle 'course_modules' table.
  30.         * @var object 
  31.         * @access private
  32.         */
  33.         var $cm = null;
  34.     
  35.         /**
  36.         * Internal only - Moodle chat module instance database object.
  37.         * Corresponds to one record from the Moodle 'chat' table.
  38.         * @var object 
  39.         * @access private
  40.         */
  41.         var $moodle_chat_instance = null;
  42.  
  43.                 
  44.         
  45.     // FUNCTIONS //
  46.     
  47.         /**
  48.         * Constructor
  49.         */
  50.         function SloodleModuleChat(&$_session)
  51.         {
  52.             $constructor = get_parent_class($this);
  53.             parent::$constructor($_session);
  54.         }
  55.         
  56.         /**
  57.         * Loads data from the database.
  58.         * Note: even if the function fails, it may still have overwritten some or all existing data in the object.
  59.         * @param mixed $id The site-wide unique identifier for all modules. Type depends on VLE. On Moodle, it is an integer course module identifier ('id' field of 'course_modules' table)
  60.         * @return bool True if successful, or false otherwise
  61.         */
  62.         function load($id)
  63.         {
  64.             // Make sure the ID is valid
  65.             $id = (int)$id;
  66.             if ($id <= 0) return false;
  67.             
  68.             // Fetch the course module data
  69.             if (!($this->cm = get_coursemodule_from_id('chat', $id))) {
  70.                 sloodle_debug("Failed to load course module instance #$id.<br/>");
  71.                 return false;
  72.             }
  73.             // Make sure the module is visible
  74.             if ($this->cm->visible == 0) {
  75.                 sloodle_debug("Error: course module instance #$id not visible.<br/>");
  76.                 return false;
  77.             }
  78.             
  79.             // Load from the primary table: chat instance
  80.             if (!($this->moodle_chat_instance = get_record('chat', 'id', $this->cm->instance))) {
  81.                 sloodle_debug("Failed to load chatroom with instance ID #{$cm->instance}.<br/>");
  82.                 return false;
  83.             }
  84.             
  85.             return true;
  86.         }
  87.         
  88.         
  89.         /**
  90.         * Gets a recent history of messages from the chatroom.
  91.         * @param int $time How far back to search the database (in seconds) (default: 1 minute)
  92.         * @return array A numeric array of {@link SloodleChatMessage} object, in order of oldest to newest
  93.         */
  94.         function get_chat_history($time = 60)
  95.         {
  96.             // Calculate the earliest acceptable timestamp
  97.             $earliest = time() - $time;
  98.             // Get all message records for this chatroom
  99.             $recs = get_records_select('chat_messages', "chatid = {$this->moodle_chat_instance->id} AND timestamp >= $earliest", 'timestamp ASC');
  100.             if (!$recs) return array();
  101.             
  102.             // We'll need to lookup all the user data.
  103.             // Cache the user records so we don't need to duplicate searches.
  104.             // This will be an associative array of user ID's to SloodleUser objects.
  105.             $usercache = array();
  106.             
  107.             // Prepare an array of chat message objects
  108.             $chatmessages = array();
  109.             // Go through each result
  110.             foreach ($recs as $r) {
  111.                 // Do we already have the current user cached?
  112.                 if (!isset($usercache[$r->userid])) {
  113.                     // No - query the database
  114.                     $usercache[$r->userid] = new SloodleUser($this->_session);
  115.                     if ($usercache[$r->userid]->load_user($r->userid)) {
  116.                         // Attempt to load any linked avatar data too
  117.                         $usercache[$r->userid]->load_linked_avatar();
  118.                     }
  119.                 }
  120.                 
  121.                 // Construct and add a message object
  122.                 $chatmessages[] = new SloodleChatMessage($r->id, $r->message, $usercache[$r->userid], $r->timestamp);
  123.             }
  124.             
  125.             return $chatmessages;
  126.         }
  127.         
  128.         
  129.         /**
  130.         * Adds a new chat message.
  131.         * <b>Note:</b> if the $author parameter is omitted or invalid, then the function will attempt to use the {@link SloodleUser} member
  132.         * of the current {@link SloodleSession} object;
  133.         * If that is unavailable, then it will try to use the user currently 'logged-in' to the VLE (i.e. the $USER variable in Moodle).
  134.         * If all else fails, it will attempt to attribute the message to the guest user.
  135.         * @param string $message The text of the message.
  136.         * @param mixed $user The user who wrote the message -- either a VLE user ID or (preferably) a {@link SloodleUser} object. If null, then the user in the current SloodleSession object will be used. At that fails, then the guest user is used if possible.
  137.         * @param int $timestamp Timestamp of the message. If omitted or <= 0 then the current timestamp is used
  138.         * @return bool True if successful, or false otherwise
  139.         */
  140.         function add_message($message, $user = null, $timestamp = null)
  141.         {
  142.             // Ignore empty messages
  143.             if (empty($message)) return false;
  144.             // Make sure the message is safe
  145.             $message = addslashes(clean_text(stripslashes($message)));
  146.             
  147.             // We need to get the user ID for the message
  148.             $userid = 0;
  149.             
  150.             // Has a user object been provided?
  151.             if (is_object($user)) {
  152.                 // Yes - grab the user ID
  153.                 $userid = $user->get_user_id();
  154.             } else if ($user != null) {
  155.                 // May be an ID
  156.                 $userid = (int)$user;
  157.             }
  158.             
  159.             // Did we end up with a valid user ID?
  160.             if ((int)$userid <= 0) {
  161.                 // No - do we have a user in the session parameter?
  162.                 if (isset($this->_session->user)) {
  163.                     // Store the user ID
  164.                     $userid = $this->_session->user->get_user_id();
  165.                 }
  166.             }
  167.             
  168.             // Are we still lacking a valid user?
  169.             if ((int)$userid <= 0) {
  170.                 // Yes - user the guest user
  171.                 $guest = guest_user();
  172.                 if ($guest) $userid = $guest->id;
  173.             }            
  174.             
  175.             // Prepare the timestamp variable if necessary
  176.             if (is_null($timestamp)) $timestamp = time();
  177.             
  178.             // Create a chat message record object
  179.             $rec = new stdClass();
  180.             $rec->chatid = $this->moodle_chat_instance->id;
  181.             $rec->userid = $userid;
  182.             $rec->message = $message;
  183.             $rec->timestamp = $timestamp;
  184.             // Attempt to insert the chat message
  185.             $result = insert_record('chat_messages', $rec);
  186.             if (!$result) return false;
  187.             
  188.             // We successfully added a chat message
  189.             // If possible, add an appropriate side effect code to our response
  190.             if (isset($this->_session->response)) {
  191.                 $this->_session->response->add_side_effect(10101);
  192.             }
  193.             
  194.             return true;
  195.         }
  196.         
  197.         
  198.     // ACCESSORS //
  199.     
  200.         /**
  201.         * Gets the name of this module instance.
  202.         * @return string The name of this controller
  203.         */
  204.         function get_name()
  205.         {
  206.             return $this->moodle_chat_instance->name;
  207.         }
  208.         
  209.         /**
  210.         * Gets the intro description of this module instance, if available.
  211.         * @return string The intro description of this controller
  212.         */
  213.         function get_intro()
  214.         {
  215.             return $this->moodle_chat_instance->intro;
  216.         }
  217.         
  218.         /**
  219.         * Gets the identifier of the course this controller belongs to.
  220.         * @return mixed Course identifier. Type depends on VLE. (In Moodle, it will be an integer).
  221.         */
  222.         function get_course_id()
  223.         {
  224.             return (int)$this->moodle_chat_instance->course;
  225.         }
  226.         
  227.         /**
  228.         * Gets the time at which this instance was created, or 0 if unknown.
  229.         * @return int Timestamp
  230.         */
  231.         function get_creation_time()
  232.         {
  233.             return 0;
  234.         }
  235.         
  236.         /**
  237.         * Gets the time at which this instance was last modified, or 0 if unknown.
  238.         * @return int Timestamp
  239.         */
  240.         function get_modification_time()
  241.         {
  242.             return $this->moodle_chat_instance->timemodified;
  243.         }
  244.         
  245.         
  246.         /**
  247.         * Gets the short type name of this instance.
  248.         * @return string 
  249.         */
  250.         function get_type()
  251.         {
  252.             return 'chat';
  253.         }
  254.  
  255.         /**
  256.         * Gets the full type name of this instance, according to the current language pack, if available.
  257.         * Note: should be overridden by sub-classes.
  258.         * @return string Full type name if possible, or the short name otherwise.
  259.         */
  260.         function get_type_full()
  261.         {
  262.             return get_string('modulename', 'chat');
  263.         }
  264.  
  265.     }
  266.     
  267.     
  268.     /**
  269.     * Represents a single chat message
  270.     * @package sloodle
  271.     */
  272.     class SloodleChatMessage
  273.     {
  274.         /**
  275.         * Constructor - initialises members.
  276.         * @param mixed $id The ID of this message - type depends on VLE, but is typically an integer
  277.         * @param string $message The chat message
  278.         * @param SloodleUser $user The user who wrote the message
  279.         * @param int $timestamp The timestamp of the message
  280.         */
  281.         function SloodleChatMessage($id, $message, $user, $timestamp)
  282.         {
  283.             $this->id = $id;
  284.             $this->message = $message;
  285.             $this->user = $user;
  286.             $this->timestamp = $timestamp;
  287.         }
  288.         
  289.         /**
  290.         * Accessor - set all members in a single call.
  291.         * @param mixed $id The ID of this message - type depends on VLE, but is typically an integer
  292.         * @param string $message The chat message
  293.         * @param SloodleUser $user The user who wrote the message
  294.         * @param int $timestamp The timestamp of the message
  295.         */
  296.         function set($id, $message, $user, $timestamp)
  297.         {
  298.             $this->id = $id;
  299.             $this->message = $message;
  300.             $this->user = $user;
  301.             $this->timestamp = $timestamp;
  302.         }
  303.         
  304.         /**
  305.         * The ID of the message.
  306.         * The type depends on the VLE, but typically is an integer.
  307.         * @var mixed 
  308.         * @access public
  309.         */
  310.         var $id = 0;
  311.     
  312.         /**
  313.         * The text of the message.
  314.         * @var string 
  315.         * @access public
  316.         */
  317.         var $message = '';
  318.         
  319.         /**
  320.         * The user who wrote this message.
  321.         * @var SloodleUser 
  322.         * @access public
  323.         */
  324.         var $user = null;
  325.         
  326.         /**
  327.         * Timestamp of the message.
  328.         * @var int 
  329.         * @access public
  330.         */
  331.         var $timestamp = 0;
  332.     }
  333.  
  334.  
  335. ?>

Documentation generated on Mon, 07 Jul 2008 12:32:53 +0100 by phpDocumentor 1.4.0