"Fossies" - the Fresh Open Source Software Archive

Member "drupal-8.9.9/core/lib/Drupal/Core/Entity/Query/QueryInterface.php" (18 Nov 2020, 8844 Bytes) of package /linux/www/drupal-8.9.9.tar.gz:


As a special service "Fossies" has tried to format the requested source page into HTML format using (guessed) PHP source code syntax highlighting (style: standard) with prefixed line numbers and code folding option. Alternatively you can here view or download the uninterpreted source code file. For more information about "QueryInterface.php" see the Fossies "Dox" file reference documentation.

    1 <?php
    2 
    3 namespace Drupal\Core\Entity\Query;
    4 
    5 use Drupal\Core\Database\Query\AlterableInterface;
    6 
    7 /**
    8  * Interface for entity queries.
    9  *
   10  * Never instantiate classes implementing this interface directly. Always use
   11  * the QueryFactory class.
   12  *
   13  * @ingroup database
   14  */
   15 interface QueryInterface extends AlterableInterface {
   16 
   17   /**
   18    * Gets the ID of the entity type for this query.
   19    *
   20    * @return string
   21    */
   22   public function getEntityTypeId();
   23 
   24   /**
   25    * Add a condition to the query or a condition group.
   26    *
   27    * For example, to find all entities containing both the Turkish 'merhaba'
   28    * and the Polish 'siema' within a 'greetings' text field:
   29    * @code
   30    *   $entity_ids = \Drupal::entityQuery($entity_type)
   31    *     ->condition('greetings', 'merhaba', '=', 'tr')
   32    *     ->condition('greetings.value', 'siema', '=', 'pl')
   33    *     ->execute();
   34    * @endcode
   35    *
   36    * @param $field
   37    *   Name of the field being queried. It must contain a field name, optionally
   38    *   followed by a column name. The column can be the reference property,
   39    *   usually "entity", for reference fields and that can be followed
   40    *   similarly by a field name and so on. Additionally, the target entity type
   41    *   can be specified by appending the ":target_entity_type_id" to "entity".
   42    *   Some examples:
   43    *   - nid
   44    *   - tags.value
   45    *   - tags
   46    *   - tags.entity.name
   47    *   - tags.entity:taxonomy_term.name
   48    *   - uid.entity.name
   49    *   - uid.entity:user.name
   50    *   "tags" "is the same as "tags.value" as value is the default column.
   51    *   If two or more conditions have the same field names they apply to the
   52    *   same delta within that field. In order to limit the condition to a
   53    *   specific item a numeric delta should be added between the field name and
   54    *   the column name.
   55    *   @code
   56    *   ->condition('tags.5.value', 'news')
   57    *   @endcode
   58    *   This will require condition to be satisfied on a specific delta of the
   59    *   field. The condition above will require the 6th value of the field to
   60    *   match the provided value. Further, it's possible to create a condition on
   61    *   the delta itself by using '%delta'. For example,
   62    *   @code
   63    *   ->condition('tags.%delta', 5)
   64    *   @endcode
   65    *   will find only entities which have at least six tags. Finally, the
   66    *   condition on the delta itself accompanied with a condition on the value
   67    *   will require the value to appear in the specific delta range. For
   68    *   example,
   69    *   @code
   70    *   ->condition('tags.%delta', 0, '>'))
   71    *   ->condition('tags.%delta.value', 'news'))
   72    *   @endcode
   73    *   will only find the "news" tag if it is not the first value. It should be
   74    *   noted that conditions on specific deltas and delta ranges are only
   75    *   supported when querying content entities.
   76    * @param $value
   77    *   The value for $field. In most cases, this is a scalar and it's treated as
   78    *   case-insensitive. For more complex operators, it is an array. The meaning
   79    *   of each element in the array is dependent on $operator.
   80    * @param $operator
   81    *   Possible values:
   82    *   - '=', '<>', '>', '>=', '<', '<=', 'STARTS_WITH', 'CONTAINS',
   83    *     'ENDS_WITH': These operators expect $value to be a literal of the
   84    *     same type as the column.
   85    *   - 'IN', 'NOT IN': These operators expect $value to be an array of
   86    *     literals of the same type as the column.
   87    *   - 'BETWEEN': This operator expects $value to be an array of two literals
   88    *     of the same type as the column.
   89    * @param $langcode
   90    *   Language code (optional). If omitted, any translation satisfies the
   91    *   condition. However, if two or more conditions omit the langcode within
   92    *   one condition group then they are presumed to apply to the same
   93    *   translation. If within one condition group one condition has a langcode
   94    *   and another does not they are not presumed to apply to the same
   95    *   translation.
   96    *
   97    * @return $this
   98    * @see \Drupal\Core\Entity\Query\andConditionGroup
   99    * @see \Drupal\Core\Entity\Query\orConditionGroup
  100    */
  101   public function condition($field, $value = NULL, $operator = NULL, $langcode = NULL);
  102 
  103   /**
  104    * Queries for a non-empty value on a field.
  105    *
  106    * @param $field
  107    *   Name of a field.
  108    * @param $langcode
  109    *   Language code (optional).
  110    *
  111    * @return $this
  112    */
  113   public function exists($field, $langcode = NULL);
  114 
  115   /**
  116    * Queries for an empty field.
  117    *
  118    * @param $field
  119    *   Name of a field.
  120    * @param $langcode
  121    *   Language code (optional).
  122    *
  123    * @return $this
  124    */
  125   public function notExists($field, $langcode = NULL);
  126 
  127   /**
  128    * Enables a pager for the query.
  129    *
  130    * @param $limit
  131    *   An integer specifying the number of elements per page.  If passed a false
  132    *   value (FALSE, 0, NULL), the pager is disabled.
  133    * @param $element
  134    *   An optional integer to distinguish between multiple pagers on one page.
  135    *   If not provided, one is automatically calculated.
  136    *
  137    * @return $this
  138    *   The called object.
  139    */
  140   public function pager($limit = 10, $element = NULL);
  141 
  142   /**
  143    * @param null $start
  144    * @param null $length
  145    * @return $this
  146    *   The called object.
  147    */
  148   public function range($start = NULL, $length = NULL);
  149 
  150   /**
  151    * @param $field
  152    *   Name of a field.
  153    * @param string $direction
  154    * @param $langcode
  155    *   Language code (optional).
  156    * @return $this
  157    *   The called object.
  158    */
  159   public function sort($field, $direction = 'ASC', $langcode = NULL);
  160 
  161   /**
  162    * Makes this a count query.
  163    *
  164    * For count queries, execute() returns the number entities found.
  165    *
  166    * @return $this
  167    *   The called object.
  168    */
  169   public function count();
  170 
  171   /**
  172    * Enables sortable tables for this query.
  173    *
  174    * @param $headers
  175    *   An array of headers of the same structure as described in
  176    *   template_preprocess_table(). Use a 'specifier' in place of a 'field' to
  177    *   specify what to sort on. This can be an entity or a field as described
  178    *   in condition().
  179    *
  180    * @return $this
  181    *   The called object.
  182    */
  183   public function tableSort(&$headers);
  184 
  185   /**
  186    * @return $this
  187    *   The called object.
  188    */
  189   public function accessCheck($access_check = TRUE);
  190 
  191   /**
  192    * Execute the query.
  193    *
  194    * @return int|array
  195    *   Returns an integer for count queries or an array of ids. The values of
  196    *   the array are always entity ids. The keys will be revision ids if the
  197    *   entity supports revision and entity ids if not.
  198    */
  199   public function execute();
  200 
  201   /**
  202    * Creates a new group of conditions ANDed together.
  203    *
  204    * For example, consider a drawing entity type with a 'figures' multi-value
  205    * field containing 'shape' and 'color' columns. To find all drawings
  206    * containing both a red triangle and a blue circle:
  207    * @code
  208    *   $query = \Drupal::entityQuery('drawing');
  209    *   $group = $query->andConditionGroup()
  210    *     ->condition('figures.color', 'red')
  211    *     ->condition('figures.shape', 'triangle');
  212    *   $query->condition($group);
  213    *   $group = $query->andConditionGroup()
  214    *     ->condition('figures.color', 'blue')
  215    *     ->condition('figures.shape', 'circle');
  216    *   $query->condition($group);
  217    *   $entity_ids = $query->execute();
  218    * @endcode
  219    *
  220    * @return \Drupal\Core\Entity\Query\ConditionInterface
  221    */
  222   public function andConditionGroup();
  223 
  224   /**
  225    * Creates a new group of conditions ORed together.
  226    *
  227    * For example, consider a map entity with an 'attributes' field
  228    * containing 'building_type' and 'color' columns.  To find all green and
  229    * red bikesheds:
  230    * @code
  231    *   $query = \Drupal::entityQuery('map');
  232    *   $group = $query->orConditionGroup()
  233    *     ->condition('attributes.color', 'red')
  234    *     ->condition('attributes.color', 'green');
  235    *   $entity_ids = $query
  236    *     ->condition('attributes.building_type', 'bikeshed')
  237    *     ->condition($group)
  238    *     ->execute();
  239    * @endcode
  240    * Note that this particular example can be simplified:
  241    * @code
  242    *   $entity_ids = $query
  243    *     ->condition('attributes.color', array('red', 'green'))
  244    *     ->condition('attributes.building_type', 'bikeshed')
  245    *     ->execute();
  246    * @endcode
  247    *
  248    * @return \Drupal\Core\Entity\Query\ConditionInterface
  249    */
  250   public function orConditionGroup();
  251 
  252   /**
  253    * Queries the current revision.
  254    *
  255    * @return $this
  256    */
  257   public function currentRevision();
  258 
  259   /**
  260    * Queries the latest revision.
  261    *
  262    * The latest revision is the most recent revision of an entity. This will be
  263    * either the default revision, or a pending revision if one exists and it is
  264    * newer than the default.
  265    *
  266    * @return $this
  267    */
  268   public function latestRevision();
  269 
  270   /**
  271    * Queries all the revisions.
  272    *
  273    * @return $this
  274    */
  275   public function allRevisions();
  276 
  277 }