/engine/lib/private_settings.php

<?php
/**
 * Private settings for entities
 * Private settings provide metadata like storage of settings for plugins
 * and users.
 *
 * @package Elgg.Core
 * @subpackage PrivateSettings
 */

/**
 * Returns entities based upon private settings.  Also accepts all
 * options available to elgg_get_entities().  Supports
 * the singular option shortcut.
 *
 * @see elgg_get_entities
 *
 * @param array $options Array in format:
 *
 * 	private_setting_names => NULL|ARR private setting names
 *
 * 	private_setting_values => NULL|ARR metadata values
 *
 * 	private_setting_name_value_pairs => NULL|ARR (
 *                                         name => 'name',
 *                                         value => 'value',
 *                                         'operand' => '=',
 *                                        )
 * 	                             Currently if multiple values are sent via
 *                               an array (value => array('value1', 'value2')
 *                               the pair's operand will be forced to "IN".
 *
 * 	private_setting_name_value_pairs_operator => NULL|STR The operator to use for combining
 *                                        (name = value) OPERATOR (name = value); default AND
 *
 *  private_setting_name_prefix => STR A prefix to apply to all private settings. Used to
 *                                     namespace plugin user settings or by plugins to namespace
 *                                     their own settings.
 *
 *
 * @return mixed int If count, int. If not count, array. false on errors.
 * @since 1.8.0
 */
function elgg_get_entities_from_private_settings(array $options = array()) {
	$defaults = array(
		'private_setting_names'                     =>	ELGG_ENTITIES_ANY_VALUE,
		'private_setting_values'                    =>	ELGG_ENTITIES_ANY_VALUE,
		'private_setting_name_value_pairs'          =>	ELGG_ENTITIES_ANY_VALUE,
		'private_setting_name_value_pairs_operator' => 'AND',
		'private_setting_name_prefix'				=> '',
	);

	$options = array_merge($defaults, $options);

	$singulars = array('private_setting_name', 'private_setting_value',
		'private_setting_name_value_pair');

	$options = elgg_normalise_plural_options_array($options, $singulars);

	$clauses = elgg_get_entity_private_settings_where_sql('e', $options['private_setting_names'],
		$options['private_setting_values'], $options['private_setting_name_value_pairs'],
		$options['private_setting_name_value_pairs_operator'], $options['private_setting_name_prefix']);

	if ($clauses) {
		// merge wheres to pass to get_entities()
		if (isset($options['wheres']) && !is_array($options['wheres'])) {
			$options['wheres'] = array($options['wheres']);
		} elseif (!isset($options['wheres'])) {
			$options['wheres'] = array();
		}

		$options['wheres'] = array_merge($options['wheres'], $clauses['wheres']);

		// merge joins to pass to get_entities()
		if (isset($options['joins']) && !is_array($options['joins'])) {
			$options['joins'] = array($options['joins']);
		} elseif (!isset($options['joins'])) {
			$options['joins'] = array();
		}

		$options['joins'] = array_merge($options['joins'], $clauses['joins']);
	}

	return elgg_get_entities($options);
}

/**
 * Returns private setting name and value SQL where/join clauses for entities.
 *
 * @param string     $table         Entities table name
 * @param array|null $names         Array of names
 * @param array|null $values        Array of values
 * @param array|null $pairs         Array of names / values / operands
 * @param string     $pair_operator Operator for joining pairs where clauses
 * @param string     $name_prefix   A string to prefix all names with
 * @return array
 * @since 1.8.0
 * @access private
 */
function elgg_get_entity_private_settings_where_sql($table, $names = NULL, $values = NULL,
$pairs = NULL, $pair_operator = 'AND', $name_prefix = '') {

	global $CONFIG;

	// @todo short circuit test

	$return = array (
		'joins' => array (),
		'wheres' => array(),
	);

	$return['joins'][] = "JOIN {$CONFIG->dbprefix}private_settings ps on
		{$table}.guid = ps.entity_guid";

	$wheres = array();

	// get names wheres
	$names_where = '';
	if ($names !== NULL) {
		if (!is_array($names)) {
			$names = array($names);
		}

		$sanitised_names = array();
		foreach ($names as $name) {
			$name = $name_prefix . $name;
			$sanitised_names[] = '\'' . sanitise_string($name) . '\'';
		}

		$names_str = implode(',', $sanitised_names);
		if ($names_str) {
			$names_where = "(ps.name IN ($names_str))";
		}
	}

	// get values wheres
	$values_where = '';
	if ($values !== NULL) {
		if (!is_array($values)) {
			$values = array($values);
		}

		$sanitised_values = array();
		foreach ($values as $value) {
			// normalize to 0
			if (!$value) {
				$value = 0;
			}
			$sanitised_values[] = '\'' . sanitise_string($value) . '\'';
		}

		$values_str = implode(',', $sanitised_values);
		if ($values_str) {
			$values_where = "(ps.value IN ($values_str))";
		}
	}

	if ($names_where && $values_where) {
		$wheres[] = "($names_where AND $values_where)";
	} elseif ($names_where) {
		$wheres[] = "($names_where)";
	} elseif ($values_where) {
		$wheres[] = "($values_where)";
	}

	// add pairs which must be in arrays.
	if (is_array($pairs)) {
		// join counter for incremental joins in pairs
		$i = 1;

		// check if this is an array of pairs or just a single pair.
		if (isset($pairs['name']) || isset($pairs['value'])) {
			$pairs = array($pairs);
		}

		$pair_wheres = array();

		foreach ($pairs as $index => $pair) {
			// @todo move this elsewhere?
			// support shortcut 'n' => 'v' method.
			if (!is_array($pair)) {
				$pair = array(
					'name' => $index,
					'value' => $pair
				);
			}

			// must have at least a name and value
			if (!isset($pair['name']) || !isset($pair['value'])) {
				// @todo should probably return false.
				continue;
			}

			if (isset($pair['operand'])) {
				$operand = sanitise_string($pair['operand']);
			} else {
				$operand = ' = ';
			}

			// for comparing
			$trimmed_operand = trim(strtolower($operand));

			// if the value is an int, don't quote it because str '15' < str '5'
			// if the operand is IN don't quote it because quoting should be done already.
			if (is_numeric($pair['value'])) {
				$value = sanitise_string($pair['value']);
			} else if (is_array($pair['value'])) {
				$values_array = array();

				foreach ($pair['value'] as $pair_value) {
					if (is_numeric($pair_value)) {
						$values_array[] = sanitise_string($pair_value);
					} else {
						$values_array[] = "'" . sanitise_string($pair_value) . "'";
					}
				}

				if ($values_array) {
					$value = '(' . implode(', ', $values_array) . ')';
				}

				// @todo allow support for non IN operands with array of values.
				// will have to do more silly joins.
				$operand = 'IN';
			} else if ($trimmed_operand == 'in') {
				$value = "({$pair['value']})";
			} else {
				$value = "'" . sanitise_string($pair['value']) . "'";
			}

			$name = sanitise_string($name_prefix . $pair['name']);

			// @todo The multiple joins are only needed when the operator is AND
			$return['joins'][] = "JOIN {$CONFIG->dbprefix}private_settings ps{$i}
				on {$table}.guid = ps{$i}.entity_guid";

			$pair_wheres[] = "(ps{$i}.name = '$name' AND ps{$i}.value
				$operand $value)";

			$i++;
		}

		$where = implode(" $pair_operator ", $pair_wheres);
		if ($where) {
			$wheres[] = "($where)";
		}
	}

	$where = implode(' AND ', $wheres);
	if ($where) {
		$return['wheres'][] = "($where)";
	}

	return $return;
}

/**
 * Gets a private setting for an entity.
 *
 * Plugin authors can set private data on entities.  By default
 * private data will not be searched or exported.
 *
 * @internal Private data is used to store settings for plugins
 * and user settings.
 *
 * @param int    $entity_guid The entity GUID
 * @param string $name        The name of the setting
 *
 * @return mixed The setting value, or false on failure
 * @see set_private_setting()
 * @see get_all_private_settings()
 * @see remove_private_setting()
 * @see remove_all_private_settings()
 * @link http://docs.elgg.org/DataModel/Entities/PrivateSettings
 */
function get_private_setting($entity_guid, $name) {
	global $CONFIG;
	$entity_guid = (int) $entity_guid;
	$name = sanitise_string($name);

	$entity = get_entity($entity_guid);
	if (!$entity instanceof ElggEntity) {
		return false;
	}

	$query = "SELECT value from {$CONFIG->dbprefix}private_settings
		where name = '{$name}' and entity_guid = {$entity_guid}";
	$setting = get_data_row($query);

	if ($setting) {
		return $setting->value;
	}
	return false;
}

/**
 * Return an array of all private settings.
 *
 * @param int $entity_guid The entity GUID
 *
 * @return array|false
 * @see set_private_setting()
 * @see get_private_settings()
 * @see remove_private_setting()
 * @see remove_all_private_settings()
 * @link http://docs.elgg.org/DataModel/Entities/PrivateSettings
 */
function get_all_private_settings($entity_guid) {
	global $CONFIG;

	$entity_guid = (int) $entity_guid;
	$entity = get_entity($entity_guid);
	if (!$entity instanceof ElggEntity) {
		return false;
	}

	$query = "SELECT * from {$CONFIG->dbprefix}private_settings where entity_guid = {$entity_guid}";
	$result = get_data($query);
	if ($result) {
		$return = array();
		foreach ($result as $r) {
			$return[$r->name] = $r->value;
		}

		return $return;
	}

	return false;
}

/**
 * Sets a private setting for an entity.
 *
 * @param int    $entity_guid The entity GUID
 * @param string $name        The name of the setting
 * @param string $value       The value of the setting
 *
 * @return bool
 * @see get_private_setting()
 * @see get_all_private_settings()
 * @see remove_private_setting()
 * @see remove_all_private_settings()
 * @link http://docs.elgg.org/DataModel/Entities/PrivateSettings
 */
function set_private_setting($entity_guid, $name, $value) {
	global $CONFIG;

	$entity_guid = (int) $entity_guid;
	$name = sanitise_string($name);
	$value = sanitise_string($value);

	$result = insert_data("INSERT into {$CONFIG->dbprefix}private_settings
		(entity_guid, name, value) VALUES
		($entity_guid, '$name', '$value')
		ON DUPLICATE KEY UPDATE value='$value'");

	return $result !== false;
}

/**
 * Deletes a private setting for an entity.
 *
 * @param int    $entity_guid The Entity GUID
 * @param string $name        The name of the setting
 *
 * @return bool
 * @see get_private_setting()
 * @see get_all_private_settings()
 * @see set_private_setting()
 * @see remove_all_private_settings()
 * @link http://docs.elgg.org/DataModel/Entities/PrivateSettings
 */
function remove_private_setting($entity_guid, $name) {
	global $CONFIG;

	$entity_guid = (int) $entity_guid;

	$entity = get_entity($entity_guid);
	if (!$entity instanceof ElggEntity) {
		return false;
	}

	$name = sanitise_string($name);

	return delete_data("DELETE from {$CONFIG->dbprefix}private_settings
		WHERE name = '{$name}'
		AND entity_guid = {$entity_guid}");
}

/**
 * Deletes all private settings for an entity.
 *
 * @param int $entity_guid The Entity GUID
 *
 * @return bool
 * @see get_private_setting()
 * @see get_all_private_settings()
 * @see set_private_setting()
 * @see remove_private_settings()
 * @link http://docs.elgg.org/DataModel/Entities/PrivateSettings
 */
function remove_all_private_settings($entity_guid) {
	global $CONFIG;

	$entity_guid = (int) $entity_guid;

	$entity = get_entity($entity_guid);
	if (!$entity instanceof ElggEntity) {
		return false;
	}

	return delete_data("DELETE from {$CONFIG->dbprefix}private_settings
		WHERE entity_guid = {$entity_guid}");
}