root/elgg/branches/elgg1.5-sql-fixes/engine/lib/relationships.php

<?php
    /**
     * Elgg relationships.
     * Stub containing relationship functions, making import and export easier.
     * 
     * @package Elgg
     * @subpackage Core
     * @license http://www.gnu.org/licenses/old-licenses/gpl-2.0.html GNU Public License version 2
     * @author Curverider Ltd <info@elgg.com>
     * @copyright Curverider Ltd 2008-2009
     * @link http://elgg.org/
     */

    /**
     * Relationship class.
     * 
     * @author Curverider Ltd
     * @package Elgg
     * @subpackage Core
     */
    class ElggRelationship implements 
        Importable, 
        Exportable,
        Loggable,    // Can events related to this object class be logged
        Iterator,    // Override foreach behaviour
        ArrayAccess // Override for array access
    {
        /**
         * This contains the site's main properties (id, etc)
         * @var array
         */
        protected $attributes;
        
        /**
         * Construct a new site object, optionally from a given id value or row.
         *
         * @param mixed $id
         */
        function __construct($id = null) 
        {
            $this->attributes = array();
            
            if (!empty($id)) {
                
                if ($id instanceof stdClass)
                    $relationship = $id; // Create from db row
                else
                    $relationship = get_relationship($id);    
                
                if ($relationship) {
                    $objarray = (array) $relationship;
                    foreach($objarray as $key => $value) {
                        $this->attributes[$key] = $value;
                    }
                }
            }
        }
        
        /**
         * Class member get overloading
         *
         * @param string $name
         * @return mixed
         */
        protected function __get($name) {
            if (isset($this->attributes[$name])) 
                return $this->attributes[$name];
    
            return null;
        }
        
        /**
         * Class member set overloading
         *
         * @param string $name
         * @param mixed $value
         * @return mixed
         */
        protected function __set($name, $value) {
            $this->attributes[$name] = $value;
            return true;
        }

        /**
         * Save the relationship
         *
         * @return int the relationship id
         */
        public function save()
        {
            if ($this->id > 0)
            {
                delete_relationship($this->id);
            }

            $this->id = add_entity_relationship($this->guid_one, $this->relationship, $this->guid_two);
            if (!$this->id) throw new IOException(sprintf(elgg_new('IOException:UnableToSaveNew'), get_class()));

            return $this->id;
            
        }
        
        /**
         * Delete a given relationship.
         */
        public function delete() 
        { 
            return delete_relationship($this->id); 
        }
        
        /**
         * Get a URL for this relationship.
         *
         * @return string
         */
        public function getURL()
        {
            return get_relationship_url($this->id);
        }
    
        // EXPORTABLE INTERFACE ////////////////////////////////////////////////////////////
        
        /**
         * Return an array of fields which can be exported.
         */
        public function getExportableValues()
        {
            return array(
                'id',
                'guid_one',
                'relationship',
                'guid_two' 
            );
        }
        
        /**
         * Export this relationship
         *
         * @return array
         */
        public function export()
        {        
            $uuid = get_uuid_from_object($this);
            $relationship = new ODDRelationship(
                guid_to_uuid($this->guid_one),
                $this->relationship,
                guid_to_uuid($this->guid_two)
            );
            
            $relationship->setAttribute('uuid', $uuid);
            
            return $relationship;
        }
        
        // IMPORTABLE INTERFACE ////////////////////////////////////////////////////////////
        
        /**
         * Import a relationship
         *
         * @param array $data
         * @param int $version
         * @return ElggRelationship
         * @throws ImportException
         */
        public function import(ODD $data)
        {
            if (!($element instanceof ODDRelationship))
                throw new InvalidParameterException(elgg_echo('InvalidParameterException:UnexpectedODDClass')); 
            
            $uuid_one = $data->getAttribute('uuid1');
            $uuid_two = $data->getAttribute('uuid2');     
                
            // See if this entity has already been imported, if so then we need to link to it
            $entity1 = get_entity_from_uuid($uuid_one);
            $entity2 = get_entity_from_uuid($uuid_two);
            if (($entity1) && ($entity2))
            {
                // Set the item ID
                $this->attributes['guid_one'] = $entity1->getGUID();
                $this->attributes['guid_two'] = $entity2->getGUID();
                
                // Map verb to relationship
                //$verb = $data->getAttribute('verb');
                //$relationship = get_relationship_from_verb($verb);
                $relationship = $data->getAttribute('type');
                
                if ($relationship)
                {    
                    $this->attributes['relationship'] = $relationship;
                    // save
                    $result = $this->save(); 
                    if (!$result)
                        throw new ImportException(sprintf(elgg_echo('ImportException:ProblemSaving'), get_class()));
                    
                    return $this;
                }
            }
        }
        
        // SYSTEM LOG INTERFACE ////////////////////////////////////////////////////////////
        
        /**
         * Return an identification for the object for storage in the system log. 
         * This id must be an integer.
         * 
         * @return int 
         */
        public function getSystemLogID() { return $this->id;    }
        
        /**
         * Return the class name of the object.
         */
        public function getClassName() { return get_class($this); }
        
        /**
         * For a given ID, return the object associated with it.
         * This is used by the river functionality primarily.
         * This is useful for checking access permissions etc on objects.
         */
        public function getObjectFromID($id) { return get_relationship($id); }
        
        /**
         * Return the GUID of the owner of this object.
         */
        public function getObjectOwnerGUID() { return $this->owner_guid; }
        
        /**
         * Return a type of the object - eg. object, group, user, relationship, metadata, annotation etc
         */
        public function getType() { return 'relationship'; }
        
        /**
         * Return a subtype. For metadata & annotations this is the 'name' and for relationship this is the relationship type.
         */
        public function getSubtype() { return $this->relationship; } 
        
        // ITERATOR INTERFACE //////////////////////////////////////////////////////////////
        /*
         * This lets an entity's attributes be displayed using foreach as a normal array.
         * Example: http://www.sitepoint.com/print/php5-standard-library
         */
        
        private $valid = FALSE; 
        
           function rewind() 
           { 
               $this->valid = (FALSE !== reset($this->attributes));  
           }
   
           function current() 
           { 
               return current($this->attributes); 
           }
        
           function key() 
           { 
               return key($this->attributes); 
           }
        
           function next() 
           {
               $this->valid = (FALSE !== next($this->attributes));  
           }
           
           function valid() 
           { 
               return $this->valid;  
           }
    
           // ARRAY ACCESS INTERFACE //////////////////////////////////////////////////////////
        /*
         * This lets an entity's attributes be accessed like an associative array.
         * Example: http://www.sitepoint.com/print/php5-standard-library
         */

        function offsetSet($key, $value)
        {
               if ( array_key_exists($key, $this->attributes) ) {
                 $this->attributes[$key] = $value;
               }
         } 
         
         function offsetGet($key) 
         {
               if ( array_key_exists($key, $this->attributes) ) {
                 return $this->attributes[$key];
               }
         } 
         
         function offsetUnset($key) 
         {
               if ( array_key_exists($key, $this->attributes) ) {
                 $this->attributes[$key] = ""; // Full unsetting is dangerious for our objects
               }
         } 
         
         function offsetExists($offset) 
         {
               return array_key_exists($offset, $this->attributes);
         } 
    }
    
    
    /**
     * Convert a database row to a new ElggRelationship
     *
     * @param stdClass $row
     * @return stdClass or ElggMetadata
     */
    function row_to_elggrelationship($row) 
    {
        if (!($row instanceof stdClass))
            return $row;
            
        return new ElggRelationship($row);
    }
    
    /**
     * Return a relationship.
     *
     * @param int $id
     */
    function get_relationship($id)
    {
        global $CONFIG;
        
        $id = (int)$id;
        
        return row_to_elggrelationship(get_data_row("SELECT * from {$CONFIG->dbprefix}entity_relationships where id=$id"));
    }
    
    /**
     * Delete a specific relationship.
     *
     * @param int $id
     */
    function delete_relationship($id)
    {
        global $CONFIG;
        
        $id = (int)$id;
        
        $result = delete_data("delete from {$CONFIG->dbprefix}entity_relationships where id=$id");
        
        return $result;
    }
    
    /**
     * Define an arbitrary relationship between two entities.
     * This relationship could be a friendship, a group membership or a site membership.
     * 
     * This function lets you make the statement "$guid_one has $relationship with $guid_two".
     * 
     * @param int $guid_one
     * @param string $relationship 
     * @param int $guid_two
     */
    function add_entity_relationship($guid_one, $relationship, $guid_two)
    {
        global $CONFIG;
        
        $guid_one = (int)$guid_one;
        $relationship = sanitise_string($relationship);
        $guid_two = (int)$guid_two;
            
        // Check for duplicates
        if (check_entity_relationship($guid_one, $relationship, $guid_two))
            return false;
        
        $result = insert_data("INSERT into {$CONFIG->dbprefix}entity_relationships (guid_one, relationship, guid_two) values ($guid_one, '$relationship', $guid_two)");
        
        if ($result!==false) {
            $obj = get_relationship($result);
            if (trigger_elgg_event('create', $relationship, $obj)) {
                return true;
            } else {
                delete_relationship($result);
            }
        }
                
        return false;
    }
    
    /**
     * Determine whether or not a relationship between two entities exists and returns the relationship object if it does
     *
     * @param int $guid_one The GUID of the entity "owning" the relationship
     * @param string $relationship The type of relationship
     * @param int $guid_two The GUID of the entity the relationship is with
     * @return object|false Depending on success
     */
    function check_entity_relationship($guid_one, $relationship, $guid_two)
    {
        global $CONFIG;
        
        $guid_one = (int)$guid_one;
        $relationship = sanitise_string($relationship);
        $guid_two = (int)$guid_two;
            
        if ($row = get_data_row("SELECT * FROM {$CONFIG->dbprefix}entity_relationships WHERE guid_one=$guid_one AND relationship='$relationship' AND guid_two=$guid_two limit 1")) {
            return $row;
        }
        return false;
    }

    /**
     * Remove an arbitrary relationship between two entities.
     * 
     * @param int $guid_one
     * @param string $relationship 
     * @param int $guid_two
     */
    function remove_entity_relationship($guid_one, $relationship, $guid_two)
    {
        global $CONFIG;
        
        $guid_one = (int)$guid_one;
        $relationship = sanitise_string($relationship);
        $guid_two = (int)$guid_two;
        
        $obj = check_entity_relationship($guid_one, $relationship, $guid_two);
        if ($obj == false) return false;
        
        if (trigger_elgg_event('delete', $relationship, $obj)) {
            return delete_data("DELETE from {$CONFIG->dbprefix}entity_relationships where guid_one=$guid_one and relationship='$relationship' and guid_two=$guid_two");
        } else {
            return false;
        }
    }

    /**
     * Removes all arbitrary relationships originating from a particular entity
     *
     * @param int $guid_one The GUID of the entity 
     * @param string $relationship The name of the relationship (optionally)
     * @param true|false $inverse Whether we're deleting inverse relationships (default false)
     * @param string $type The type of entity to limit this relationship delete to (defaults to all)
     * @return true|false Depending on success
     */
    function remove_entity_relationships($guid_one, $relationship = "", $inverse = false, $type = '') {
        
        global $CONFIG;
        
        $guid_one = (int) $guid_one;
        
        if (!empty($relationship)) {
            $relationship = sanitise_string($relationship);
            $where = "and er.relationship='$relationship'";
        } else {
            $where = "";
        }
        
        if (!empty($type)) {
            $type = sanitise_string($type);
            if (!$inverse) {
                $join = " join {$CONFIG->dbprefix}entities e on e.guid = er.guid_two ";
            } else {
                $join = " join {$CONFIG->dbprefix}entities e on e.guid = er.guid_one ";
                $where .= " and ";
            }
            $where .= " and e.type = '{$type}' ";
        } else {
            $join = "";
        }
        
        if (!$inverse) {
            $sql = "DELETE from {$CONFIG->dbprefix}entity_relationships er {$join} where er.guid_one={$guid_one} {$where}";
            return delete_data($sql);
        } else {
            $sql = "DELETE from {$CONFIG->dbprefix}entity_relationships er {$join} where er.guid_two={$guid_one} {$where}";
            return delete_data($sql);
        }
        
    }

    /**
     * Get all the relationships for a given guid.
     * 
     * @param int $guid
     */
    function get_entity_relationships($guid)
    {
        global $CONFIG;
        
        $guid = (int)$guid;
        
        $query = "SELECT * from {$CONFIG->dbprefix}entity_relationships where guid_one=$guid";
        
        return get_data($query, "row_to_elggrelationship");
    }
    
    /**
     * Return entities matching a given query joining against a relationship.
     * 
     * @param string $relationship The relationship eg "friends_of"
     * @param int $relationship_guid The guid of the entity to use query
     * @param bool $inverse_relationship Reverse the normal function of the query to instead say "give me all entities for whome $relationship_guid is a $relationship of"
     * @param string $type 
     * @param string $subtype
     * @param int $owner_guid
     * @param string $order_by
     * @param int $limit
     * @param int $offset
     * @param boolean $count Set to true if you want to count the number of entities instead (default false)
     * @param int $site_guid The site to get entities for. Leave as 0 (default) for the current site; -1 for all sites.
     * @return array|int|false An array of entities, or the number of entities, or false on failure
     */
    function get_entities_from_relationship($relationship, $relationship_guid, $inverse_relationship = false, $type = "", $subtype = "", $owner_guid = 0, $order_by = "", $limit = 10, $offset = 0, $count = false, $site_guid = 0)
    {
        global $CONFIG;
        
        $relationship = sanitise_string($relationship);
        $relationship_guid = (int)$relationship_guid;
        $inverse_relationship = (bool)$inverse_relationship;
        $type = sanitise_string($type);
        $subtype = get_subtype_id($type, $subtype);
        $owner_guid = (int)$owner_guid;
        if ($order_by == "") $order_by = "time_created desc";
        $order_by = sanitise_string($order_by);
        $limit = (int)$limit;
        $offset = (int)$offset;
        $site_guid = (int) $site_guid;
        if ($site_guid == 0)
            $site_guid = $CONFIG->site_guid;
        
        //$access = get_access_list();
        
        $where = array();
        
        if ($relationship!="")
            $where[] = "r.relationship='$relationship'";
        if ($relationship_guid)
            $where[] = ($inverse_relationship ? "r.guid_two='$relationship_guid'" : "r.guid_one='$relationship_guid'");
        if ($type != "")
            $where[] = "e.type='$type'";
        if ($subtype)
            $where[] = "e.subtype=$subtype";
        if ($owner_guid != "")
            $where[] = "e.container_guid='$owner_guid'";
        if ($site_guid > 0)
            $where[] = "e.site_guid = {$site_guid}";
        
        // Select what we're joining based on the options
        $joinon = "e.guid = r.guid_one";
        if (!$inverse_relationship)
            $joinon = "e.guid = r.guid_two";    
            
        if ($count) {
            $query = "SELECT count(distinct e.guid) as total ";
        } else {
            $query = "SELECT distinct e.* ";
        }
        $query .= " from {$CONFIG->dbprefix}entity_relationships r JOIN {$CONFIG->dbprefix}entities e on $joinon where ";
        foreach ($where as $w)
            $query .= " $w and ";
        $query .= get_access_sql_suffix("e"); // Add access controls
        if (!$count) {
            $query .= " order by $order_by limit $limit offset $offset"; // Add order and limit
            return get_data($query, "entity_row_to_elggstar");
        } else {
            if ($count = get_data_row($query)) {
                return $count->total;
            }
        }
        return false;
        
    }

    /**
     * Returns a viewable list of entities by relationship
     *
     * @see elgg_view_entity_list
     * 
     * @param string $relationship The relationship eg "friends_of"
     * @param int $relationship_guid The guid of the entity to use query
     * @param bool $inverse_relationship Reverse the normal function of the query to instead say "give me all entities for whome $relationship_guid is a $relationship of"
     * @param string $type The type of entity (eg 'object')
     * @param string $subtype The entity subtype
     * @param int $owner_guid The owner (default: all)
     * @param int $limit The number of entities to display on a page
     * @param true|false $fullview Whether or not to display the full view (default: true)
     * @param true|false $viewtypetoggle Whether or not to allow gallery view 
     * @param true|false $pagination Whether to display pagination (default: true)
     * @return string The viewable list of entities
     */
    function list_entities_from_relationship($relationship, $relationship_guid, $inverse_relationship = false, $type = "", $subtype = "", $owner_guid = 0, $limit = 10, $fullview = true, $viewtypetoggle = false, $pagination = true) {
        
        $limit = (int) $limit;
        $offset = (int) get_input('offset');
        $count = get_entities_from_relationship($relationship, $relationship_guid, $inverse_relationship, $type, $subtype, $owner_guid, "", $limit, $offset, true);
        $entities = get_entities_from_relationship($relationship, $relationship_guid, $inverse_relationship, $type, $subtype, $owner_guid, "", $limit, $offset);

        return elgg_view_entity_list($entities, $count, $offset, $limit, $fullview, $viewtypetoggle, $pagination);
        
    }

    /**
     * Gets the number of entities by a the number of entities related to them in a particular way.
     * This is a good way to get out the users with the most friends, or the groups with the most members.
     *
     * @param string $relationship The relationship eg "friends_of"
     * @param bool $inverse_relationship Reverse the normal function of the query to instead say "give me all entities for whome $relationship_guid is a $relationship of" (default: true)
     * @param string $type The type of entity (default: all)
     * @param string $subtype The entity subtype (default: all)
     * @param int $owner_guid The owner of the entities (default: none)
     * @param int $limit
     * @param int $offset
     * @param boolean $count Set to true if you want to count the number of entities instead (default false)
     * @param int $site_guid The site to get entities for. Leave as 0 (default) for the current site; -1 for all sites.
     * @return array|int|false An array of entities, or the number of entities, or false on failure
     */
    
    function get_entities_by_relationship_count($relationship, $inverse_relationship = true, $type = "", $subtype = "", $owner_guid = 0, $limit = 10, $offset = 0, $count = false, $site_guid = 0) {
        
        global $CONFIG;
        
        $relationship = sanitise_string($relationship);
        $inverse_relationship = (bool)$inverse_relationship;
        $type = sanitise_string($type);
        $subtype = get_subtype_id($type, $subtype);
        $owner_guid = (int)$owner_guid;
        $order_by = sanitise_string($order_by);
        $limit = (int)$limit;
        $offset = (int)$offset;
        $site_guid = (int) $site_guid;
        if ($site_guid == 0)
            $site_guid = $CONFIG->site_guid;
        
        //$access = get_access_list();
        
        $where = array();
        
        if ($relationship!="")
            $where[] = "r.relationship='$relationship'";
        if ($inverse_relationship) {
            $on = 'e.guid = r.guid_two';
        } else {
            $on = 'e.guid = r.guid_one';
        }
        if ($type != "")
            $where[] = "e.type='$type'";
        if ($subtype)
            $where[] = "e.subtype=$subtype";
        if ($owner_guid != "")
            $where[] = "e.container_guid='$owner_guid'";
        if ($site_guid > 0)
            $where[] = "e.site_guid = {$site_guid}";
        
        if ($count) {
            $query = "SELECT count(distinct e.guid) as total ";
        } else {
            $query = "SELECT e.*, count(e.guid) as total ";
        }
        
        $query .= " from {$CONFIG->dbprefix}entity_relationships r JOIN {$CONFIG->dbprefix}entities e on {$on} where ";
        
        if (!empty($where))
        foreach ($where as $w)
            $query .= " $w and ";
        $query .= get_access_sql_suffix("e"); // Add access controls
        
        if (!$count) {
            $query .= " group by e.guid,e.type,e.subtype,e.owner_guid,e.site_guid,e.container_guid,e.access_id,e.time_created,e.time_updated,e.enabled ";//postgres requires all fields being selected to be listed in the group by clause.  
            $query .= " order by total desc limit {$limit} offset {$offset}"; // Add order and limit
            return get_data($query, "entity_row_to_elggstar");
        } else {
            if ($count = get_data_row($query)) {
                return $count->total;
            }
        }
        
        return false;
            
    }
    
    /**
     * Displays a human-readable list of entities
     * 
     * @param string $relationship The relationship eg "friends_of"
     * @param bool $inverse_relationship Reverse the normal function of the query to instead say "give me all entities for whome $relationship_guid is a $relationship of" (default: true)
     * @param string $type The type of entity (eg 'object')
     * @param string $subtype The entity subtype
     * @param int $owner_guid The owner (default: all)
     * @param int $limit The number of entities to display on a page
     * @param true|false $fullview Whether or not to display the full view (default: true)
     * @param true|false $viewtypetoggle Whether or not to allow gallery view 
     * @param true|false $pagination Whether to display pagination (default: true)
     * @return string The viewable list of entities
     */
    
    function list_entities_by_relationship_count($relationship, $inverse_relationship = true, $type = "", $subtype = "", $owner_guid = 0, $limit = 10, $fullview = true, $viewtypetoggle = false, $pagination = true) {
        
        $limit = (int) $limit;
        $offset = (int) get_input('offset');
        $count = get_entities_by_relationship_count($relationship,$inverse_relationship,$type,$subtype,$owner_guid,0,0,true);
        $entities = get_entities_by_relationship_count($relationship,$inverse_relationship,$type,$subtype,$owner_guid,$limit,$offset);

        return elgg_view_entity_list($entities, $count, $offset, $limit, $fullview, $viewtypetoggle, $pagination);
        
    }
    
    /**
     * Sets the URL handler for a particular relationship type
     *
     * @param string $function_name The function to register
     * @param string $relationship_type The relationship type.
     * @return true|false Depending on success
     */
    function register_relationship_url_handler($function_name, $relationship_type = "all") {
        global $CONFIG;
        
        if (!is_callable($function_name)) return false;
        
        if (!isset($CONFIG->relationship_url_handler)) {
            $CONFIG->relationship_url_handler = array();
        }
        
        $CONFIG->relationship_url_handler[$relationship_type] = $function_name;
        
        return true;
        
    }
    
    /**
     * Get the url for a given relationship.
     *
     * @param unknown_type $id
     * @return unknown
     */
    function get_relationship_url($id)
    {
        global $CONFIG;
        
        $id = (int)$id;
        
        if ($relationship = get_relationship($id))
        {
            $view = elgg_get_viewtype(); 
                
            $guid = $relationship->guid_one;
            $type = $relationship->relationship;
            
            $url = "";
            
            $function = "";
            if (isset($CONFIG->relationship_url_handler[$type]))
                $function = $CONFIG->relationship_url_handler[$type];
            if (isset($CONFIG->relationship_url_handler['all']))
                $function = $CONFIG->relationship_url_handler['all'];
                
            if (is_callable($function)) {
                $url = $function($relationship);
            }
            
            if ($url == "") {
                
                $nameid = $relationship->id;
                
                $url = $CONFIG->wwwroot  . "export/$view/$guid/relationship/$nameid/";
            } 
            
            return $url;
            
        }
        
        return false;
    }
    
    /**** HELPER FUNCTIONS FOR RELATIONSHIPS OF TYPE 'ATTACHED' ****/
    
     /**
     * Function to determine if the object trying to attach to other, has already done so
     * @param int $guid_one This is the target object
     * @param int $guid_two This is the object trying to attach to $guid_one
     * @return true | false
     **/
     
     function already_attached($guid_one, $guid_two){
    
         if($attached = check_entity_relationship($guid_one, "attached", $guid_two)){
             return true;
         }else{
             return false;
         }
     }
     
     /**
     * Function to get all objects attached to a particular object
     * @param int $guid
     * @param string $type - the type of object to return e.g. 'file', 'friend_of' etc
     * @return an array of objects
    **/
         
        function get_attachments($guid, $type=""){
            
            $attached = get_entities_from_relationship("attached", $guid, $inverse_relationship = false, $type, $subtype = "", $owner_guid = 0, $order_by = "time_created desc", $limit = 10, $offset = 0, $count = false, $site_guid = 0);
            return $attached;
           
        }
        
     /**
     * Function to remove a particular attachment between two objects
     * @param int $guid_one This is the target object
     * @param int $guid_two This is the object to remove from $guid_one
     * @return a view 
    **/
         
        function remove_attachment($guid_one, $guid_two){
            
            if(already_attached($guid_one, $guid_two))
                remove_entity_relationship($guid_one, "attached", $guid_two);
           
        }
        
        
     
     /**
     * Function to start the process of attaching one object to another
     * @param int $guid_one This is the target object
     * @param int $guid_two This is the object trying to attach to $guid_one
     * @return a view 
    **/
         
        function make_attachment($guid_one, $guid_two){
            
            if(!(already_attached($guid_one, $guid_two)))
                if(add_entity_relationship($guid_one, "attached", $guid_two))
                    return true;
           
        }
    
    /**
     *  Handler called by trigger_plugin_hook on the "import" event.
     */
    function import_relationship_plugin_hook($hook, $entity_type, $returnvalue, $params)
    {
        $element = $params['element'];
        
        $tmp = NULL;
        
        if ($element instanceof ODDRelationship)
        {
            $tmp = new ElggRelationship();
            $tmp->import($element);
            
            return $tmp;
        }
    }
    
    /**
     *  Handler called by trigger_plugin_hook on the "export" event.
     */
    function export_relationship_plugin_hook($hook, $entity_type, $returnvalue, $params)
    {
        global $CONFIG;
        
        // Sanity check values
        if ((!is_array($params)) && (!isset($params['guid'])))
            throw new InvalidParameterException(elgg_echo('InvalidParameterException:GUIDNotForExport'));
            
        if (!is_array($returnvalue))
            throw new InvalidParameterException(elgg_echo('InvalidParameterException:NonArrayReturnValue'));
            
        $guid = (int)$params['guid'];
        
        $result = get_entity_relationships($guid);
        
        if ($result)
        {
            foreach ($result as $r)
                $returnvalue[] = $r->export();
        }
        
        return $returnvalue;
    }

    /**
     * An event listener which will notify users based on certain events.
     *
     * @param unknown_type $event
     * @param unknown_type $object_type
     * @param unknown_type $object
     */
    function relationship_notification_hook($event, $object_type, $object)
    {
        global $CONFIG;
        
        if (
            ($object instanceof ElggRelationship) &&
            ($event == 'create') &&
            ($object_type == 'friend')
        )
        {
            $user_one = get_entity($object->guid_one);
            $user_two = get_entity($object->guid_two);
            
            // Notify target user
            return notify_user($object->guid_two, $object->guid_one, sprintf(elgg_echo('friend:newfriend:subject'), $user_one->name), 
                sprintf(elgg_echo("friend:newfriend:body"), $user_one->name, $CONFIG->site->url . "pg/profile/" . $user_one->username)
            ); 
        }
    }
    
    /** Register the import hook */
    register_plugin_hook("import", "all", "import_relationship_plugin_hook", 3);
    
    /** Register the hook, ensuring entities are serialised first */
    register_plugin_hook("export", "all", "export_relationship_plugin_hook", 3);
    
    /** Register event to listen to some events **/
    register_elgg_event_handler('create','friend','relationship_notification_hook');
?>