www.aleph1.co.uk Git - yaffs-website/blob - web/core/modules/locale/src/StringStorageInterface.php

   1 <?php
   2
   3 namespace Drupal\locale;
   4
   5 /**
   6  * Defines the locale string storage interface.
   7  */
   8 interface StringStorageInterface {
   9
  10   /**
  11    * Loads multiple source string objects.
  12    *
  13    * @param array $conditions
  14    *   (optional) Array with conditions that will be used to filter the strings
  15    *   returned and may include any of the following elements:
  16    *   - Any simple field value indexed by field name.
  17    *   - 'translated', TRUE to get only translated strings or FALSE to get only
  18    *     untranslated strings. If not set it returns both translated and
  19    *     untranslated strings that fit the other conditions.
  20    *   Defaults to no conditions which means that it will load all strings.
  21    * @param array $options
  22    *   (optional) An associative array of additional options. It may contain
  23    *   any of the following optional keys:
  24    *   - 'filters': Array of string filters indexed by field name.
  25    *   - 'pager limit': Use pager and set this limit value.
  26    *
  27    * @return array
  28    *   Array of \Drupal\locale\StringInterface objects matching the conditions.
  29    */
  30   public function getStrings(array $conditions = [], array $options = []);
  31
  32   /**
  33    * Loads multiple string translation objects.
  34    *
  35    * @param array $conditions
  36    *   (optional) Array with conditions that will be used to filter the strings
  37    *   returned and may include all of the conditions defined by getStrings().
  38    * @param array $options
  39    *   (optional) An associative array of additional options. It may contain
  40    *   any of the options defined by getStrings().
  41    *
  42    * @return \Drupal\locale\StringInterface[]
  43    *   Array of \Drupal\locale\StringInterface objects matching the conditions.
  44    *
  45    * @see \Drupal\locale\StringStorageInterface::getStrings()
  46    */
  47   public function getTranslations(array $conditions = [], array $options = []);
  48
  49   /**
  50    * Loads string location information.
  51    *
  52    * @param array $conditions
  53    *   (optional) Array with conditions to filter the locations that may be any
  54    *   of the following elements:
  55    *   - 'sid', The string identifier.
  56    *   - 'type', The location type.
  57    *   - 'name', The location name.
  58    *
  59    * @return \Drupal\locale\StringInterface[]
  60    *   Array of \Drupal\locale\StringInterface objects matching the conditions.
  61    *
  62    * @see \Drupal\locale\StringStorageInterface::getStrings()
  63    */
  64   public function getLocations(array $conditions = []);
  65
  66   /**
  67    * Loads a string source object, fast query.
  68    *
  69    * These 'fast query' methods are the ones in the critical path and their
  70    * implementation must be optimized for speed, as they may run many times
  71    * in a single page request.
  72    *
  73    * @param array $conditions
  74    *   (optional) Array with conditions that will be used to filter the strings
  75    *   returned and may include all of the conditions defined by getStrings().
  76    *
  77    * @return \Drupal\locale\SourceString|null
  78    *   Minimal TranslationString object if found, NULL otherwise.
  79    */
  80   public function findString(array $conditions);
  81
  82   /**
  83    * Loads a string translation object, fast query.
  84    *
  85    * This function must only be used when actually translating strings as it
  86    * will have the effect of updating the string version. For other purposes
  87    * the getTranslations() method should be used instead.
  88    *
  89    * @param array $conditions
  90    *   (optional) Array with conditions that will be used to filter the strings
  91    *   returned and may include all of the conditions defined by getStrings().
  92    *
  93    * @return \Drupal\locale\TranslationString|null
  94    *   Minimal TranslationString object if found, NULL otherwise.
  95    */
  96   public function findTranslation(array $conditions);
  97
  98   /**
  99    * Save string object to storage.
 100    *
 101    * @param \Drupal\locale\StringInterface $string
 102    *   The string object.
 103    *
 104    * @return \Drupal\locale\StringStorageInterface
 105    *   The called object.
 106    *
 107    * @throws \Drupal\locale\StringStorageException
 108    *   In case of failures, an exception is thrown.
 109    */
 110   public function save($string);
 111
 112   /**
 113    * Delete string from storage.
 114    *
 115    * @param \Drupal\locale\StringInterface $string
 116    *   The string object.
 117    *
 118    * @return \Drupal\locale\StringStorageInterface
 119    *   The called object.
 120    *
 121    * @throws \Drupal\locale\StringStorageException
 122    *   In case of failures, an exception is thrown.
 123    */
 124   public function delete($string);
 125
 126   /**
 127    * Deletes source strings and translations using conditions.
 128    *
 129    * @param array $conditions
 130    *   Array with simple field conditions for source strings.
 131    */
 132   public function deleteStrings($conditions);
 133
 134   /**
 135    * Deletes translations using conditions.
 136    *
 137    * @param array $conditions
 138    *   Array with simple field conditions for string translations.
 139    */
 140   public function deleteTranslations($conditions);
 141
 142   /**
 143    * Counts source strings.
 144    *
 145    * @return int
 146    *   The number of source strings contained in the storage.
 147    */
 148   public function countStrings();
 149
 150   /**
 151    * Counts translations.
 152    *
 153    * @return array
 154    *   The number of translations for each language indexed by language code.
 155    */
 156   public function countTranslations();
 157
 158   /**
 159    * Creates a source string object bound to this storage but not saved.
 160    *
 161    * @param array $values
 162    *   (optional) Array with initial values. Defaults to empty array.
 163    *
 164    * @return \Drupal\locale\SourceString
 165    *   New source string object.
 166    */
 167   public function createString($values = []);
 168
 169   /**
 170    * Creates a string translation object bound to this storage but not saved.
 171    *
 172    * @param array $values
 173    *   (optional) Array with initial values. Defaults to empty array.
 174    *
 175    * @return \Drupal\locale\TranslationString
 176    *   New string translation object.
 177    */
 178   public function createTranslation($values = []);
 179
 180 }