diff options
Diffstat (limited to 'engine/lib/relationships.php')
| -rw-r--r-- | engine/lib/relationships.php | 399 |
1 files changed, 73 insertions, 326 deletions
diff --git a/engine/lib/relationships.php b/engine/lib/relationships.php index ff069fa48..b0cd627fc 100644 --- a/engine/lib/relationships.php +++ b/engine/lib/relationships.php @@ -12,7 +12,8 @@ * * @param stdClass $row Database row from the relationship table * - * @return stdClass or ElggMetadata + * @return ElggRelationship|stdClass + * @access private */ function row_to_elggrelationship($row) { if (!($row instanceof stdClass)) { @@ -27,7 +28,7 @@ function row_to_elggrelationship($row) { * * @param int $id The ID of a relationship * - * @return mixed + * @return ElggRelationship|false */ function get_relationship($id) { global $CONFIG; @@ -108,7 +109,7 @@ function add_entity_relationship($guid_one, $relationship, $guid_two) { * @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 + * @return ElggRelationship|false Depending on success */ function check_entity_relationship($guid_one, $relationship, $guid_two) { global $CONFIG; @@ -122,7 +123,7 @@ function check_entity_relationship($guid_one, $relationship, $guid_two) { AND relationship='$relationship' AND guid_two=$guid_two limit 1"; - $row = $row = get_data_row($query); + $row = row_to_elggrelationship(get_data_row($query)); if ($row) { return $row; } @@ -157,7 +158,7 @@ function remove_entity_relationship($guid_one, $relationship, $guid_two) { and relationship='$relationship' and guid_two=$guid_two"; - return delete_data($query); + return (bool)delete_data($query); } else { return false; } @@ -219,7 +220,7 @@ function remove_entity_relationships($guid_one, $relationship = "", $inverse = f * @param int $guid The GUID of the relationship owner * @param bool $inverse_relationship Inverse relationship owners? * - * @return mixed + * @return ElggRelationship[] */ function get_entity_relationships($guid, $inverse_relationship = FALSE) { global $CONFIG; @@ -233,9 +234,22 @@ function get_entity_relationships($guid, $inverse_relationship = FALSE) { return get_data($query, "row_to_elggrelationship"); } - /** * Return entities matching a given query joining against a relationship. + * Also accepts all options available to elgg_get_entities() and + * elgg_get_entities_from_metadata(). + * + * To ask for entities that do not have a particulat relationship to an entity, + * use a custom where clause like the following: + * + * $options['wheres'][] = "NOT EXISTS ( + * SELECT 1 FROM {$db_prefix}entity_relationships + * WHERE guid_one = e.guid + * AND relationship = '$relationship' + * )"; + * + * @see elgg_get_entities + * @see elgg_get_entities_from_metadata * * @param array $options Array in format: * @@ -245,7 +259,7 @@ function get_entity_relationships($guid, $inverse_relationship = FALSE) { * * inverse_relationship => BOOL Inverse the relationship * - * @return array + * @return ElggEntity[]|mixed If count, int. If not count, array. false on errors. * @since 1.7.0 */ function elgg_get_entities_from_relationship($options) { @@ -278,6 +292,16 @@ function elgg_get_entities_from_relationship($options) { } $options['joins'] = array_merge($options['joins'], $clauses['joins']); + + if (isset($options['selects']) && !is_array($options['selects'])) { + $options['selects'] = array($options['selects']); + } elseif (!isset($options['selects'])) { + $options['selects'] = array(); + } + + $select = array('r.id'); + + $options['selects'] = array_merge($options['selects'], $select); } return elgg_get_entities_from_metadata($options); @@ -292,15 +316,16 @@ function elgg_get_entities_from_relationship($options) { * Provide in table.column format. * @param string $relationship Relationship string * @param int $relationship_guid Entity guid to check - * @param string $inverse_relationship Inverse relationship check? + * @param bool $inverse_relationship Inverse relationship check? * * @return mixed * @since 1.7.0 + * @access private */ function elgg_get_entity_relationship_where_sql($column, $relationship = NULL, $relationship_guid = NULL, $inverse_relationship = FALSE) { - if ($relationship == NULL && $entity_guid == NULL) { + if ($relationship == NULL && $relationship_guid == NULL) { return ''; } @@ -336,73 +361,9 @@ $relationship_guid = NULL, $inverse_relationship = FALSE) { } /** - * Return entities from relationships - * - * @deprecated 1.7 Use elgg_get_entities_from_relationship() - * - * @param string $relationship The relationship type - * @param int $relationship_guid The GUID of the relationship owner - * @param bool $inverse_relationship Invert relationship? - * @param string $type Entity type - * @param string $subtype Entity subtype - * @param int $owner_guid Entity owner GUID - * @param string $order_by Order by clause - * @param int $limit Limit - * @param int $offset Offset - * @param bool $count Return a count instead of entities? - * @param int $site_guid Site GUID - * - * @return mixed - */ -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) { - - elgg_deprecated_notice('get_entities_from_relationship() was deprecated by elgg_get_entities_from_relationship()!', 1.7); - - $options = array(); - - $options['relationship'] = $relationship; - $options['relationship_guid'] = $relationship_guid; - $options['inverse_relationship'] = $inverse_relationship; - - if ($type) { - $options['types'] = $type; - } - - if ($subtype) { - $options['subtypes'] = $subtype; - } - - if ($owner_guid) { - $options['owner_guid'] = $owner_guid; - } - - $options['limit'] = $limit; - - if ($offset) { - $options['offset'] = $offset; - } - - if ($order_by) { - $options['order_by']; - } - - if ($site_guid) { - $options['site_guid']; - } - - if ($count) { - $options['count'] = $count; - } - - return elgg_get_entities_from_relationship($options); -} - -/** * Returns a viewable list of entities by relationship * - * @param array $options + * @param array $options Options array for retrieval of entities * * @see elgg_list_entities() * @see elgg_get_entities_from_relationship() @@ -414,37 +375,14 @@ function elgg_list_entities_from_relationship(array $options = array()) { } /** - * @deprecated 1.8 Use elgg_list_entities_from_relationship() - */ -function list_entities_from_relationship($relationship, $relationship_guid, -$inverse_relationship = false, $type = ELGG_ENTITIES_ANY_VALUE, -$subtype = ELGG_ENTITIES_ANY_VALUE, $owner_guid = 0, $limit = 10, -$fullview = true, $listtypetoggle = false, $pagination = true) { - - elgg_deprecated_notice("list_entities_from_relationship was deprecated by elgg_list_entities_from_relationship()!", 1.8); - return elgg_list_entities_from_relationship(array( - 'relationship' => $relationship, - 'relationship_guid' => $relationship_guid, - 'inverse_relationship' => $inverse_relationship, - 'types' => $type, - 'subtypes' => $subtype, - 'owner_guid' => $owner_guid, - 'limit' => $limit, - 'full_view' => $fullview, - 'list_type_toggle' => $listtypetoggle, - 'pagination' => $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 array $options An options array compatible with * elgg_get_entities_from_relationship() - * @return array - * @since 1.8 + * @return ElggEntity[]|mixed int If count, int. If not count, array. false on errors. + * @since 1.8.0 */ function elgg_get_entities_from_relationship_count(array $options = array()) { $options['selects'][] = "COUNT(e.guid) as total"; @@ -454,219 +392,31 @@ function elgg_get_entities_from_relationship_count(array $options = array()) { } /** - * 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. - * - * @deprecated 1.8 Use elgg_get_entities_from_relationship_count() - * - * @param string $relationship The relationship eg "friends_of" - * @param bool $inverse_relationship Inverse relationship owners - * @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 Limit - * @param int $offset Offset - * @param bool $count Return a count instead of entities - * @param int $site_guid Site GUID - * - * @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) { - elgg_deprecated_notice('get_entities_by_relationship_count() is deprecated by elgg_get_entities_from_relationship_count()', 1.8); - - $options = array(); - - $options['relationship'] = $relationship; - - // this used to default to true, which is wrong. - // flip it for the new function - $options['inverse_relationship'] = !$inverse_relationship; - - if ($type) { - $options['types'] = $type; - } - - if ($subtype) { - $options['subtypes'] = $subtype; - } - - if ($owner_guid) { - $options['owner_guid'] = $owner_guid; - } - - $options['limit'] = $limit; - - if ($offset) { - $options['offset'] = $offset; - } - - if ($site_guid) { - $options['site_guid']; - } - - if ($count) { - $options['count'] = $count; - } - - return elgg_get_entities_from_relationship_count($options); -} - -/** * Returns a list of entities by relationship count * * @see elgg_get_entities_from_relationship_count() * * @param array $options Options array * - * @return array - * @since 1.8 + * @return string + * @since 1.8.0 */ function elgg_list_entities_from_relationship_count($options) { return elgg_list_entities($options, 'elgg_get_entities_from_relationship_count'); } /** - * Displays a human-readable list of entities - * - * @deprecated 1.8 - * - * @param string $relationship The relationship eg "friends_of" - * @param bool $inverse_relationship Inverse relationship owners - * @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 bool $fullview Whether or not to display the full view (default: true) - * @param bool $listtypetoggle Whether or not to allow gallery view - * @param bool $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, -$listtypetoggle = false, $pagination = true) { - - elgg_deprecated_notice('list_entities_by_relationship_count() was deprecated by elgg_list_entities_from_relationship_count()', 1.8); - - $options = array(); - - $options['relationship'] = $relationship; - - // this used to default to true, which is wrong. - // flip it for the new function - $options['inverse_relationship'] = !$inverse_relationship; - - if ($type) { - $options['types'] = $type; - } - - if ($subtype) { - $options['subtypes'] = $subtype; - } - - if ($owner_guid) { - $options['owner_guid'] = $owner_guid; - } - - $options['limit'] = $limit; - - $options['full_view'] = $fullview; - - return elgg_list_entities_from_relationship_count($options); -} - -/** - * Gets the number of entities by a the number of entities related to - * them in a particular way also constrained by metadata. - * - * @deprecated 1.8 - * - * @param string $relationship The relationship eg "friends_of" - * @param int $relationship_guid The guid of the entity to use query - * @param bool $inverse_relationship Inverse relationship owner - * @param String $meta_name The metadata name - * @param String $meta_value The metadata value - * @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 Limit - * @param int $offset Offset - * @param bool $count Return a count instead of entities - * @param int $site_guid Site GUID - * - * @return array|int|false An array of entities, or the number of entities, or false on failure - */ -function get_entities_from_relationships_and_meta($relationship, $relationship_guid, -$inverse_relationship = false, $meta_name = "", $meta_value = "", $type = "", -$subtype = "", $owner_guid = 0, $limit = 10, $offset = 0, $count = false, $site_guid = 0) { - - elgg_deprecated_notice('get_entities_from_relationship_and_meta() was deprecated by elgg_get_entities_from_relationship()!', 1.7); - - $options = array(); - - $options['relationship'] = $relationship; - $options['relationship_guid'] = $relationship_guid; - $options['inverse_relationship'] = $inverse_relationship; - - if ($meta_value) { - $options['values'] = $meta_value; - } - - if ($entity_type) { - $options['types'] = $entity_type; - } - - if ($type) { - $options['types'] = $type; - } - - if ($subtype) { - $options['subtypes'] = $subtype; - } - - if ($owner_guid) { - $options['owner_guid'] = $owner_guid; - } - - if ($limit) { - $options['limit'] = $limit; - } - - if ($offset) { - $options['offset'] = $offset; - } - - if ($order_by) { - $options['order_by']; - } - - if ($site_guid) { - $options['site_guid']; - } - - if ($count) { - $options['count'] = $count; - } - - return elgg_get_entities_from_relationship($options); -} - -/** * Sets the URL handler for a particular relationship type * - * @param string $function_name The function to register * @param string $relationship_type The relationship type. + * @param string $function_name The function to register * * @return bool Depending on success */ -function register_relationship_url_handler($function_name, $relationship_type = "all") { +function elgg_register_relationship_url_handler($relationship_type, $function_name) { global $CONFIG; - if (!is_callable($function_name)) { + if (!is_callable($function_name, true)) { return false; } @@ -708,7 +458,7 @@ function get_relationship_url($id) { } if (is_callable($function)) { - $url = $function($relationship); + $url = call_user_func($function, $relationship); } if ($url == "") { @@ -733,7 +483,8 @@ function get_relationship_url($id) { * @param int $guid_two This is the object trying to attach to $guid_one * * @return bool - **/ + * @access private + */ function already_attached($guid_one, $guid_two) { if ($attached = check_entity_relationship($guid_one, "attached", $guid_two)) { return true; @@ -748,14 +499,15 @@ function already_attached($guid_one, $guid_two) { * @param int $guid Entity GUID * @param string $type The type of object to return e.g. 'file', 'friend_of' etc * - * @return an array of objects -**/ + * @return ElggEntity[] + * @access private + */ function get_attachments($guid, $type = "") { $options = array( 'relationship' => 'attached', 'relationship_guid' => $guid, 'inverse_relationship' => false, - 'types' => $type, + 'type' => $type, 'subtypes' => '', 'owner_guid' => 0, 'order_by' => 'time_created desc', @@ -775,7 +527,8 @@ function get_attachments($guid, $type = "") { * @param int $guid_two This is the object to remove from $guid_one * * @return void -**/ + * @access private + */ function remove_attachment($guid_one, $guid_two) { if (already_attached($guid_one, $guid_two)) { remove_entity_relationship($guid_one, "attached", $guid_two); @@ -789,7 +542,8 @@ function remove_attachment($guid_one, $guid_two) { * @param int $guid_two This is the object trying to attach to $guid_one * * @return true|void -**/ + * @access private + */ function make_attachment($guid_one, $guid_two) { if (!(already_attached($guid_one, $guid_two))) { if (add_entity_relationship($guid_one, "attached", $guid_two)) { @@ -807,7 +561,7 @@ function make_attachment($guid_one, $guid_two) { * @param mixed $params Array of params * * @return mixed - * + * @access private */ function import_relationship_plugin_hook($hook, $entity_type, $returnvalue, $params) { $element = $params['element']; @@ -817,9 +571,8 @@ function import_relationship_plugin_hook($hook, $entity_type, $returnvalue, $par if ($element instanceof ODDRelationship) { $tmp = new ElggRelationship(); $tmp->import($element); - - return $tmp; } + return $tmp; } /** @@ -832,10 +585,10 @@ function import_relationship_plugin_hook($hook, $entity_type, $returnvalue, $par * * @elgg_event_handler export all * @return mixed + * @throws InvalidParameterException + * @access private */ 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')); @@ -859,38 +612,32 @@ function export_relationship_plugin_hook($hook, $entity_type, $returnvalue, $par } /** - * An event listener which will notify users based on certain events. + * Notify user that someone has friended them * - * @param string $event Event name - * @param string $object_type Object type - * @param mixed $object Object + * @param string $event Event name + * @param string $type Object type + * @param mixed $object Object * * @return bool + * @access private */ -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); +function relationship_notification_hook($event, $type, $object) { + /* @var ElggRelationship $object */ + $user_one = get_entity($object->guid_one); + /* @var ElggUser $user_one */ - // Notify target user - return notify_user($object->guid_two, $object->guid_one, + return notify_user($object->guid_two, + $object->guid_one, elgg_echo('friend:newfriend:subject', array($user_one->name)), elgg_echo("friend:newfriend:body", array($user_one->name, $user_one->getURL())) - ); - } + ); } -/** Register the import hook */ +// Register the import hook elgg_register_plugin_hook_handler("import", "all", "import_relationship_plugin_hook", 3); -/** Register the hook, ensuring entities are serialised first */ +// Register the hook, ensuring entities are serialised first elgg_register_plugin_hook_handler("export", "all", "export_relationship_plugin_hook", 3); -/** Register event to listen to some events **/ +// Register event to listen to some events elgg_register_event_handler('create', 'friend', 'relationship_notification_hook'); |