engine/lib/metadata.php File Reference

Go to the source code of this file.

Namespaces
namespace	Elgg::Core
	Activate a plugin or plugins.
Functions
	row_to_elggmetadata ($row)
	Convert a database row to a new ElggMetadata.
	elgg_get_metadata_from_id ($id)
	Get a specific metadata object by its id.
	elgg_delete_metadata_by_id ($id)
	Deletes metadata using its ID.
	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.
	update_metadata ($id, $name, $value, $value_type, $owner_guid, $access_id)
	Update a specific piece of metadata.
	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.
	elgg_get_metadata (array $options=array())
	Returns metadata.
	elgg_delete_metadata (array $options)
	Deletes metadata based on $options.
	elgg_disable_metadata (array $options)
	Disables metadata based on $options.
	elgg_enable_metadata (array $options)
	Enables metadata based on $options.
	elgg_get_entities_from_metadata (array $options=array())
	ElggEntities interfaces.
	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.
	elgg_list_entities_from_metadata ($options)
	Returns a list of entities filtered by provided metadata.
	export_metadata_plugin_hook ($hook, $entity_type, $returnvalue, $params)
	Other functions.
	string_to_tag_array ($string)
	Takes in a comma-separated string and returns an array of tags which have been trimmed.
	metadata_array_to_values ($array)
	Takes a metadata array (which has all kinds of properties) and turns it into a simple array of strings.
	get_metadata_url ($id)
	Get the URL for this metadata.
	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.
	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.
	metadata_update ($event, $object_type, $object)
	When an entity is updated, resets the access ID on all of its child metadata.
	elgg_register_metadata_url_handler ($extender_name, $function)
	Register a metadata url handler.
	elgg_get_metadata_cache ()
	Get the global metadata cache instance.
	elgg_invalidate_metadata_cache ($action, array $options)
	Invalidate the metadata cache based on options passed to various *_metadata functions.
	metadata_test ($hook, $type, $value, $params)
	Metadata unit test.

Function Documentation

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_guid The entity to attach the metadata to
	string	$name Name of the metadata
	string	$value Value of the metadata
	string	$value_type 'text', 'integer', or '' for automatic detection
	int	$owner_guid GUID of entity that owns the metadata
	int	$access_id Default is ACCESS_PRIVATE
	bool	$allow_multiple Allow 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_guid The entity to attach the metadata to
	array	$name_and_values Associative array - a value can be a string, number, bool
	string	$value_type 'text', 'integer', or '' for automatic detection
	int	$owner_guid GUID of entity that owns the metadata
	int	$access_id Default is ACCESS_PRIVATE
	bool	$allow_multiple Allow multiple values for one key. Default is FALSE

Returns:: bool

Definition at line 240 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

$options An options array. {

See also:: 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 307 of file metadata.php.

elgg_delete_metadata_by_id ( $ id )

Deletes metadata using its ID.

Parameters:

int

$id The 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

$options An 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 330 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

$options An 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 353 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

$options Array 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".

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 426 of file metadata.php.

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_table Entities table name
	string	$n_table Normalized metastrings table name (Where entities, values, and names are joined. annotations / metadata)
	array\|null	$names Array of names
	array\|null	$values Array of values
	array\|null	$pairs Array of names / values / operands
	string	$pair_operator ("AND" or "OR") Operator to use to join the where clauses for pairs
	bool	$case_sensitive Case sensitive metadata names?
	array\|null	$order_by_metadata Array of names / direction
	array\|null	$owner_guids Array of owner GUIDs

Returns:: false|array False on fail, array('joins', 'wheres')

Since:: 1.7.0 private

Definition at line 476 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

$options Array 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 283 of file metadata.php.

elgg_get_metadata_cache ( )

Get the global metadata cache instance.

Returns:: ElggVolatileMetadataCache

private

Definition at line 910 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

$id The id of the metadata object being retrieved.

Returns:: ElggMetadata|false FALSE if not found

Definition at line 35 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	$action Action performed on metadata. "delete", "disable", or "enable"
	array	$options Options passed to elgg_(delete\|disable\|enable)_metadata

Returns:: void

Definition at line 925 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

$options Options array

Returns:: array

Since:: 1.7.0

Definition at line 728 of file metadata.php.

elgg_register_metadata_url_handler	(	$	extender_name,
		$	function
	)

Register a metadata url handler.

Parameters:

	string	$extender_name The name, default 'all'.
	string	$function The function name.

Returns:: bool

Definition at line 899 of file metadata.php.

export_metadata_plugin_hook	(	$	hook,
		$	entity_type,
		$	returnvalue,
		$	params
	)

Other functions.

Handler called by trigger_plugin_hook on the "export" event.

Parameters:

	string	$hook export
	string	$entity_type all
	mixed	$returnvalue Value returned from previous hook
	mixed	$params Params

Returns:: array private

Exceptions:

InvalidParameterException

Definition at line 749 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

$id Metadata ID

Returns:: mixed

Definition at line 822 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	$type The type - object, user, etc
	string	$subtype The entity subtype

Returns:: bool

Definition at line 857 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

$array Metadata array

Returns:: array Array of strings

Definition at line 801 of file metadata.php.

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

Metadata unit test.

Parameters:

	string	$hook unit_test
	string	$type system
	mixed	$value Array of other tests
	mixed	$params Params

Returns:: array private

Definition at line 967 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	$event The name of the event
	string	$object_type The type of object
	ElggEntity	$object The entity itself

Returns:: true

Definition at line 878 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	$type The type - object, user, etc
	string	$subtype The subtype; all subtypes by default

Returns:: void

Definition at line 840 of file metadata.php.

row_to_elggmetadata ( $ row )

Convert a database row to a new ElggMetadata.

Parameters:

stdClass

$row An object from the database

Returns:: stdClass|ElggMetadata private

Definition at line 18 of file metadata.php.

string_to_tag_array ( $ string )

Takes in a comma-separated string and returns an array of tags which have been trimmed.

Parameters:

string

$string Comma-separated tag string

Returns:: array|false An array of strings, or false on failure

Definition at line 782 of file metadata.php.

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

Update a specific piece of metadata.

Parameters:

	int	$id ID of the metadata to update
	string	$name Metadata name
	string	$value Metadata value
	string	$value_type Value type
	int	$owner_guid Owner guid
	int	$access_id Access ID

Returns:: bool

Definition at line 156 of file metadata.php.

engine/lib/metadata.php File Reference

Namespaces

Functions

Function Documentation