Fixes #3046 adds documentation for requesting entities that do not have metadata...

diff --git a/engine/lib/metadata.php b/engine/lib/metadata.php
index 0ff3a43dc986b38da5fb9469a08a3697d5419ab5..77fa30e412fc3eef23d9674243fbd19280d42e7b 100644 (file)
--- a/engine/lib/metadata.php
+++ b/engine/lib/metadata.php
@@ -361,13 +361,24 @@ function elgg_enable_metadata(array $options) {
  * options available to elgg_get_entities().  Supports
  * the singular option shortcut.
  *
- * NB: Using metadata_names and metadata_values results in a
+ * @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 elgg_get_entities
  *
  * @param array $options Array in format:

diff --git a/engine/lib/relationships.php b/engine/lib/relationships.php
index f50c4a485bdb81cc9d56ebe781f266b51efd02be..09d541e22309db1912ff01e2e4807b78c60efe6e 100644 (file)
--- a/engine/lib/relationships.php
+++ b/engine/lib/relationships.php
@@ -239,6 +239,15 @@ function get_entity_relationships($guid, $inverse_relationship = FALSE) {
  * 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
  *