Elgg  Version 1.9
Namespaces | Functions
metadata.php File Reference

Go to the source code of this file.

Namespaces

 Elgg\Core
 Activate a plugin or plugins.
 

Functions

 row_to_elggmetadata ($row)
 Convert a database row to a new ElggMetadata. More...
 
 elgg_get_metadata_from_id ($id)
 Get a specific metadata object by its id. More...
 
 elgg_delete_metadata_by_id ($id)
 Deletes metadata using its ID. More...
 
 create_metadata ($entity_guid, $name, $value, $value_type= '', $owner_guid=0, $access_id=ACCESS_PRIVATE, $allow_multiple=false)
 Create a new metadata object, or update an existing one. More...
 
 update_metadata ($id, $name, $value, $value_type, $owner_guid, $access_id)
 Update a specific piece of metadata. More...
 
 create_metadata_from_array ($entity_guid, array $name_and_values, $value_type, $owner_guid, $access_id=ACCESS_PRIVATE, $allow_multiple=false)
 This function creates metadata from an associative array of "key => value" pairs. More...
 
 elgg_get_metadata (array $options=array())
 Returns metadata. More...
 
 elgg_delete_metadata (array $options)
 Deletes metadata based on $options. More...
 
 elgg_disable_metadata (array $options)
 Disables metadata based on $options. More...
 
 elgg_enable_metadata (array $options)
 Enables metadata based on $options. More...
 
 elgg_get_entities_from_metadata (array $options=array())
 ElggEntities interfaces. More...
 
 elgg_list_entities_from_metadata ($options)
 Returns a list of entities filtered by provided metadata. More...
 
 _elgg_get_entity_metadata_where_sql ($e_table, $n_table, $names=null, $values=null, $pairs=null, $pair_operator= 'AND', $case_sensitive=true, $order_by_metadata=null, $owner_guids=null)
 Returns metadata name and value SQL where for entities. More...
 
 metadata_array_to_values ($array)
 Takes a metadata array (which has all kinds of properties) and turns it into a simple array of strings. More...
 
 get_metadata_url ($id)
 Get the URL for this metadata. More...
 
 register_metadata_as_independent ($type, $subtype= '*')
 Mark entities with a particular type and subtype as having access permissions that can be changed independently from their parent entity. More...
 
 is_metadata_independent ($type, $subtype)
 Determines whether entities of a given type and subtype should not change their metadata in line with their parent entity. More...
 
 metadata_update ($event, $object_type, $object)
 When an entity is updated, resets the access ID on all of its child metadata. More...
 
 _elgg_get_metadata_cache ()
 Get the global metadata cache instance. More...
 
 _elgg_invalidate_metadata_cache ($action, array $options)
 Invalidate the metadata cache based on options passed to various *_metadata functions. More...
 
 _elgg_metadata_test ($hook, $type, $value, $params)
 Metadata unit test. More...
 

Function Documentation

_elgg_get_entity_metadata_where_sql (   $e_table,
  $n_table,
  $names = null,
  $values = null,
  $pairs = null,
  $pair_operator = 'AND',
  $case_sensitive = true,
  $order_by_metadata = null,
  $owner_guids = null 
)

Returns metadata name and value SQL where for entities.

NB: $names and $values are not paired. Use $pairs for this. Pairs default to '=' operand.

This function is reused for annotations because the tables are exactly the same.

Parameters
string$e_tableEntities table name
string$n_tableNormalized metastrings table name (Where entities, values, and names are joined. annotations / metadata)
array | null$namesArray of names
array | null$valuesArray of values
array | null$pairsArray of names / values / operands
string$pair_operator("AND" or "OR") Operator to use to join the where clauses for pairs
bool$case_sensitiveCase sensitive metadata names?
array | null$order_by_metadataArray of names / direction
array | null$owner_guidsArray of owner GUIDs
Returns
false|array False on fail, array('joins', 'wheres')
Since
1.7.0 private

Definition at line 495 of file metadata.php.

_elgg_get_metadata_cache ( )

Get the global metadata cache instance.

Returns
ElggVolatileMetadataCache

private

Definition at line 849 of file metadata.php.

_elgg_invalidate_metadata_cache (   $action,
array  $options 
)

Invalidate the metadata cache based on options passed to various *_metadata functions.

Parameters
string$actionAction performed on metadata. "delete", "disable", or "enable"
array$optionsOptions passed to elgg_(delete|disable|enable)_metadata
Returns
void private

Definition at line 866 of file metadata.php.

_elgg_metadata_test (   $hook,
  $type,
  $value,
  $params 
)

Metadata unit test.

Parameters
string$hookunit_test
string$typesystem
mixed$valueArray of other tests
mixed$paramsParams
Returns
array private

Definition at line 902 of file metadata.php.

create_metadata (   $entity_guid,
  $name,
  $value,
  $value_type = '',
  $owner_guid = 0,
  $access_id = ACCESS_PRIVATE,
  $allow_multiple = false 
)

Create a new metadata object, or update an existing one.

Metadata can be an array by setting allow_multiple to true, but it is an indexed array with no control over the indexing.

Parameters
int$entity_guidThe entity to attach the metadata to
string$nameName of the metadata
string$valueValue of the metadata
string$value_type'text', 'integer', or '' for automatic detection
int$owner_guidGUID of entity that owns the metadata. Default is logged in user.
int$access_idDefault is ACCESS_PRIVATE
bool$allow_multipleAllow multiple values for one key. Default is false
Returns
int|false id of metadata or false if failure

Definition at line 69 of file metadata.php.

create_metadata_from_array (   $entity_guid,
array  $name_and_values,
  $value_type,
  $owner_guid,
  $access_id = ACCESS_PRIVATE,
  $allow_multiple = false 
)

This function creates metadata from an associative array of "key => value" pairs.

To achieve an array for a single key, pass in the same key multiple times with allow_multiple set to true. This creates an indexed array. It does not support associative arrays and there is no guarantee on the ordering in the array.

Parameters
int$entity_guidThe entity to attach the metadata to
array$name_and_valuesAssociative array - a value can be a string, number, bool
string$value_type'text', 'integer', or '' for automatic detection
int$owner_guidGUID of entity that owns the metadata
int$access_idDefault is ACCESS_PRIVATE
bool$allow_multipleAllow multiple values for one key. Default is false
Returns
bool

Definition at line 239 of file metadata.php.

elgg_delete_metadata ( array  $options)

Deletes metadata based on $options.

Warning
Unlike elgg_get_metadata() this will not accept an empty options array! This requires at least one constraint: metadata_owner_guid(s), metadata_name(s), metadata_value(s), or guid(s) must be set.
Parameters
array$optionsAn options array. elgg_get_metadata()
Returns
bool|null true on success, false on failure, null if no metadata to delete.
Since
1.8.0

Definition at line 306 of file metadata.php.

elgg_delete_metadata_by_id (   $id)

Deletes metadata using its ID.

Parameters
int$idThe metadata ID to delete.
Returns
bool

Definition at line 45 of file metadata.php.

elgg_disable_metadata ( array  $options)

Disables metadata based on $options.

Warning
Unlike elgg_get_metadata() this will not accept an empty options array!
Parameters
array$optionsAn options array. elgg_get_metadata()
Returns
bool|null true on success, false on failure, null if no metadata disabled.
Since
1.8.0

Definition at line 329 of file metadata.php.

elgg_enable_metadata ( array  $options)

Enables metadata based on $options.

Warning
Unlike elgg_get_metadata() this will not accept an empty options array!
In order to enable metadata, you must first use access_show_hidden_entities().
Parameters
array$optionsAn options array. elgg_get_metadata()
Returns
bool|null true on success, false on failure, null if no metadata enabled.
Since
1.8.0

Definition at line 356 of file metadata.php.

elgg_get_entities_from_metadata ( array  $options = array())

ElggEntities interfaces.

Returns entities based upon metadata. Also accepts all options available to elgg_get_entities(). Supports the singular option shortcut.

Note
Using metadata_names and metadata_values results in a "names IN (...) AND values IN (...)" clause. This is subtly differently than default multiple metadata_name_value_pairs, which use "(name = value) AND (name = value)" clauses.

When in doubt, use name_value_pairs.

To ask for entities that do not have a metadata value, use a custom where clause like this:

$options['wheres'][] = "NOT EXISTS (
    SELECT 1 FROM {$dbprefix}metadata md
    WHERE md.entity_guid = e.guid
        AND md.name_id = $name_metastring_id
        AND md.value_id = $value_metastring_id)";

Note the metadata name and value has been denormalized in the above example.

See also
elgg_get_entities
Parameters
array$optionsArray in format:
metadata_names => null|ARR metadata names

metadata_values => null|ARR metadata values

metadata_name_value_pairs => null|ARR (
                                    name => 'name',
                                    value => 'value',
                                    'operand' => '=',
                                    'case_sensitive' => true
                                   )
                          Currently if multiple values are sent via
                          an array (value => array('value1', 'value2')
                          the pair's operand will be forced to "IN".
                          If passing "IN" as the operand and a string as the value,
                          the value must be a properly quoted and escaped string.

metadata_name_value_pairs_operator => null|STR The operator to use for combining
                                   (name = value) OPERATOR (name = value); default AND

metadata_case_sensitive => BOOL Overall Case sensitive

order_by_metadata => null|ARR array( 'name' => 'metadata_text1', 'direction' => ASC|DESC, 'as' => text|integer ) Also supports array('name' => 'metadata_text1')

metadata_owner_guids => null|ARR guids for metadata owners

Returns
ElggEntity[]|mixed If count, int. If not count, array. false on errors.
Since
1.7.0

Definition at line 431 of file metadata.php.

elgg_get_metadata ( array  $options = array())

Returns metadata.

Accepts all elgg_get_entities() options for entity restraints.

See also
elgg_get_entities
Warning
1.7's find_metadata() didn't support limits and returned all metadata. This function defaults to a limit of 25. There is probably not a reason for you to return all metadata unless you're exporting an entity, have other restraints in place, or are doing something horribly wrong in your code.
Parameters
array$optionsArray in format:

metadata_names => null|ARR metadata names metadata_values => null|ARR metadata values metadata_ids => null|ARR metadata ids metadata_case_sensitive => BOOL Overall Case sensitive metadata_owner_guids => null|ARR guids for metadata owners metadata_created_time_lower => INT Lower limit for created time. metadata_created_time_upper => INT Upper limit for created time. metadata_calculation => STR Perform the MySQL function on the metadata values returned. The "metadata_calculation" option causes this function to return the result of performing a mathematical calculation on all metadata that match the query instead of returning ElggMetadata objects.

Returns
ElggMetadata[]|mixed
Since
1.8.0

Definition at line 282 of file metadata.php.

elgg_get_metadata_from_id (   $id)

Get a specific metadata object by its id.

If you want multiple metadata objects, use elgg_get_metadata().

Parameters
int$idThe id of the metadata object being retrieved.
Returns
ElggMetadata|false false if not found

Definition at line 35 of file metadata.php.

elgg_list_entities_from_metadata (   $options)

Returns a list of entities filtered by provided metadata.

See also
elgg_get_entities_from_metadata
Parameters
array$optionsOptions array
Returns
array
Since
1.7.0

Definition at line 468 of file metadata.php.

get_metadata_url (   $id)

Get the URL for this metadata.

By default this links to the export handler in the current view.

Parameters
int$idMetadata ID
Returns
mixed

Definition at line 772 of file metadata.php.

is_metadata_independent (   $type,
  $subtype 
)

Determines whether entities of a given type and subtype should not change their metadata in line with their parent entity.

Parameters
string$typeThe type - object, user, etc
string$subtypeThe entity subtype
Returns
bool

Definition at line 807 of file metadata.php.

metadata_array_to_values (   $array)

Takes a metadata array (which has all kinds of properties) and turns it into a simple array of strings.

Parameters
array$arrayMetadata array
Returns
array Array of strings

Definition at line 751 of file metadata.php.

metadata_update (   $event,
  $object_type,
  $object 
)

When an entity is updated, resets the access ID on all of its child metadata.

Parameters
string$eventThe name of the event
string$object_typeThe type of object
ElggEntity$objectThe entity itself
Returns
true private Set as private in 1.9.0

Definition at line 829 of file metadata.php.

register_metadata_as_independent (   $type,
  $subtype = '*' 
)

Mark entities with a particular type and subtype as having access permissions that can be changed independently from their parent entity.

Parameters
string$typeThe type - object, user, etc
string$subtypeThe subtype; all subtypes by default
Returns
void

Definition at line 790 of file metadata.php.

row_to_elggmetadata (   $row)

Convert a database row to a new ElggMetadata.

Parameters
stdClass$rowAn object from the database
Returns
stdClass|ElggMetadata private

Definition at line 18 of file metadata.php.

update_metadata (   $id,
  $name,
  $value,
  $value_type,
  $owner_guid,
  $access_id 
)

Update a specific piece of metadata.

Parameters
int$idID of the metadata to update
string$nameMetadata name
string$valueMetadata value
string$value_typeValue type
int$owner_guidOwner guid
int$access_idAccess ID
Returns
bool

Definition at line 156 of file metadata.php.