www.aleph1.co.uk Git - yaffs-website/blob - web/core/lib/Drupal/Core/Database/Query/AlterableInterface.php

   1 <?php
   2
   3 namespace Drupal\Core\Database\Query;
   4
   5 /**
   6  * Interface for a query that can be manipulated via an alter hook.
   7  */
   8 interface AlterableInterface {
   9
  10   /**
  11    * Adds a tag to a query.
  12    *
  13    * Tags are strings that identify a query. A query may have any number of
  14    * tags. Tags are used to mark a query so that alter hooks may decide if they
  15    * wish to take action. Tags should be all lower-case and contain only
  16    * letters, numbers, and underscore, and start with a letter. That is, they
  17    * should follow the same rules as PHP identifiers in general.
  18    *
  19    * @param $tag
  20    *   The tag to add.
  21    *
  22    * @return \Drupal\Core\Database\Query\AlterableInterface
  23    *   The called object.
  24    */
  25   public function addTag($tag);
  26
  27   /**
  28    * Determines if a given query has a given tag.
  29    *
  30    * @param $tag
  31    *   The tag to check.
  32    *
  33    * @return
  34    *   TRUE if this query has been marked with this tag, FALSE otherwise.
  35    */
  36   public function hasTag($tag);
  37
  38   /**
  39    * Determines if a given query has all specified tags.
  40    *
  41    * @param $tags
  42    *   A variable number of arguments, one for each tag to check.
  43    *
  44    * @return
  45    *   TRUE if this query has been marked with all specified tags, FALSE
  46    *   otherwise.
  47    */
  48   public function hasAllTags();
  49
  50   /**
  51    * Determines if a given query has any specified tag.
  52    *
  53    * @param $tags
  54    *   A variable number of arguments, one for each tag to check.
  55    *
  56    * @return
  57    *   TRUE if this query has been marked with at least one of the specified
  58    *   tags, FALSE otherwise.
  59    */
  60   public function hasAnyTag();
  61
  62   /**
  63    * Adds additional metadata to the query.
  64    *
  65    * Often, a query may need to provide additional contextual data to alter
  66    * hooks. Alter hooks may then use that information to decide if and how
  67    * to take action.
  68    *
  69    * @param $key
  70    *   The unique identifier for this piece of metadata. Must be a string that
  71    *   follows the same rules as any other PHP identifier.
  72    * @param $object
  73    *   The additional data to add to the query. May be any valid PHP variable.
  74    *
  75    * @return \Drupal\Core\Database\Query\AlterableInterface
  76    *   The called object.
  77    */
  78   public function addMetaData($key, $object);
  79
  80   /**
  81    * Retrieves a given piece of metadata.
  82    *
  83    * @param $key
  84    *   The unique identifier for the piece of metadata to retrieve.
  85    *
  86    * @return
  87    *   The previously attached metadata object, or NULL if one doesn't exist.
  88    */
  89   public function getMetaData($key);
  90
  91 }