[Summary view] [Print] [Text view]

   1  <?php
   2  /**
   3   * Part of the Joomla Framework String Package
   4   *
   5   * @copyright  Copyright (C) 2005 - 2021 Open Source Matters, Inc. All rights reserved.
   6   * @license    GNU General Public License version 2 or later; see LICENSE
   7   */
   8  
   9  namespace Joomla\String;
  10  
  11  use Doctrine\Common\Inflector\Inflector as DoctrineInflector;
  12  
  13  /**
  14   * Joomla Framework String Inflector Class
  15   *
  16   * The Inflector transforms words
  17   *
  18   * @since  1.0
  19   */
  20  class Inflector extends DoctrineInflector
  21  {
  22      /**
  23       * The singleton instance.
  24       *
  25       * @var    Inflector
  26       * @since  1.0
  27       * @deprecated  3.0
  28       */
  29      private static $instance;
  30  
  31      /**
  32       * The inflector rules for countability.
  33       *
  34       * @var    array
  35       * @since  2.0.0
  36       */
  37      private static $countable = [
  38          'rules' => [
  39              'id',
  40              'hits',
  41              'clicks',
  42          ],
  43      ];
  44  
  45      /**
  46       * Adds inflection regex rules to the inflector.
  47       *
  48       * @param   mixed   $data      A string or an array of strings or regex rules to add.
  49       * @param   string  $ruleType  The rule type: singular | plural | countable
  50       *
  51       * @return  void
  52       *
  53       * @since   1.0
  54       * @throws  \InvalidArgumentException
  55       */
  56  	private function addRule($data, string $ruleType)
  57      {
  58          if (\is_string($data))
  59          {
  60              $data = [$data];
  61          }
  62          elseif (!\is_array($data))
  63          {
  64              throw new \InvalidArgumentException('Invalid inflector rule data.');
  65          }
  66          elseif (!\in_array($ruleType, ['singular', 'plural', 'countable']))
  67          {
  68              throw new \InvalidArgumentException('Unsupported rule type.');
  69          }
  70  
  71          if ($ruleType === 'countable')
  72          {
  73              foreach ($data as $rule)
  74              {
  75                  // Ensure a string is pushed.
  76                  array_push(self::$countable['rules'], (string) $rule);
  77              }
  78          }
  79          else
  80          {
  81              static::rules($ruleType, $data);
  82          }
  83      }
  84  
  85      /**
  86       * Adds a countable word.
  87       *
  88       * @param   mixed  $data  A string or an array of strings to add.
  89       *
  90       * @return  $this
  91       *
  92       * @since   1.0
  93       */
  94  	public function addCountableRule($data)
  95      {
  96          $this->addRule($data, 'countable');
  97  
  98          return $this;
  99      }
 100  
 101      /**
 102       * Adds a specific singular-plural pair for a word.
 103       *
 104       * @param   string  $singular  The singular form of the word.
 105       * @param   string  $plural    The plural form of the word. If omitted, it is assumed the singular and plural are identical.
 106       *
 107       * @return  $this
 108       *
 109       * @since   1.0
 110       * @deprecated  3.0  Use Doctrine\Common\Inflector\Inflector::rules() instead.
 111       */
 112  	public function addWord($singular, $plural = '')
 113      {
 114          trigger_deprecation(
 115              'joomla/string',
 116              '2.0.0',
 117              '%s() is deprecated and will be removed in 3.0, use %s::rules() instead.',
 118              __METHOD__,
 119              DoctrineInflector::class
 120          );
 121  
 122          if ($plural !== '')
 123          {
 124              static::rules(
 125                  'plural',
 126                  [
 127                      'irregular' => [$plural => $singular],
 128                  ]
 129              );
 130  
 131              static::rules(
 132                  'singular',
 133                  [
 134                      'irregular' => [$singular => $plural],
 135                  ]
 136              );
 137          }
 138          else
 139          {
 140              static::rules(
 141                  'plural',
 142                  [
 143                      'uninflected' => [$singular],
 144                  ]
 145              );
 146  
 147              static::rules(
 148                  'singular',
 149                  [
 150                      'uninflected' => [$singular],
 151                  ]
 152              );
 153          }
 154  
 155          return $this;
 156      }
 157  
 158      /**
 159       * Adds a pluralisation rule.
 160       *
 161       * @param   mixed  $data  A string or an array of regex rules to add.
 162       *
 163       * @return  $this
 164       *
 165       * @since   1.0
 166       * @deprecated  3.0  Use Doctrine\Common\Inflector\Inflector::rules() instead.
 167       */
 168  	public function addPluraliseRule($data)
 169      {
 170          trigger_deprecation(
 171              'joomla/string',
 172              '2.0.0',
 173              '%s() is deprecated and will be removed in 3.0, use %s::rules() instead.',
 174              __METHOD__,
 175              DoctrineInflector::class
 176          );
 177  
 178          $this->addRule($data, 'plural');
 179  
 180          return $this;
 181      }
 182  
 183      /**
 184       * Adds a singularisation rule.
 185       *
 186       * @param   mixed  $data  A string or an array of regex rules to add.
 187       *
 188       * @return  $this
 189       *
 190       * @since   1.0
 191       * @deprecated  3.0  Use Doctrine\Common\Inflector\Inflector::rules() instead.
 192       */
 193  	public function addSingulariseRule($data)
 194      {
 195          trigger_deprecation(
 196              'joomla/string',
 197              '2.0.0',
 198              '%s() is deprecated and will be removed in 3.0, use %s::rules() instead.',
 199              __METHOD__,
 200              DoctrineInflector::class
 201          );
 202  
 203          $this->addRule($data, 'singular');
 204  
 205          return $this;
 206      }
 207  
 208      /**
 209       * Gets an instance of the Inflector singleton.
 210       *
 211       * @param   boolean  $new  If true (default is false), returns a new instance regardless if one exists. This argument is mainly used for testing.
 212       *
 213       * @return  static
 214       *
 215       * @since   1.0
 216       * @deprecated  3.0  Use static methods without a class instance instead.
 217       */
 218  	public static function getInstance($new = false)
 219      {
 220          trigger_deprecation(
 221              'joomla/string',
 222              '2.0.0',
 223              '%s() is deprecated and will be removed in 3.0.',
 224              __METHOD__
 225          );
 226  
 227          if ($new)
 228          {
 229              return new static;
 230          }
 231  
 232          if (!\is_object(self::$instance))
 233          {
 234              self::$instance = new static;
 235          }
 236  
 237          return self::$instance;
 238      }
 239  
 240      /**
 241       * Checks if a word is countable.
 242       *
 243       * @param   string  $word  The string input.
 244       *
 245       * @return  boolean  True if word is countable, false otherwise.
 246       *
 247       * @since   1.0
 248       */
 249  	public function isCountable($word)
 250      {
 251          return \in_array($word, self::$countable['rules']);
 252      }
 253  
 254      /**
 255       * Checks if a word is in a plural form.
 256       *
 257       * @param   string  $word  The string input.
 258       *
 259       * @return  boolean  True if word is plural, false if not.
 260       *
 261       * @since   1.0
 262       */
 263  	public function isPlural($word)
 264      {
 265          return $this->toPlural($this->toSingular($word)) === $word;
 266      }
 267  
 268      /**
 269       * Checks if a word is in a singular form.
 270       *
 271       * @param   string  $word  The string input.
 272       *
 273       * @return  boolean  True if word is singular, false if not.
 274       *
 275       * @since   1.0
 276       */
 277  	public function isSingular($word)
 278      {
 279          return $this->toSingular($word) === $word;
 280      }
 281  
 282      /**
 283       * Converts a word into its plural form.
 284       *
 285       * @param   string  $word  The singular word to pluralise.
 286       *
 287       * @return  string  The word in plural form.
 288       *
 289       * @since   1.0
 290       * @deprecated  3.0  Use Doctrine\Common\Inflector\Inflector::pluralize() instead.
 291       */
 292  	public function toPlural($word)
 293      {
 294          trigger_deprecation(
 295              'joomla/string',
 296              '2.0.0',
 297              '%s() is deprecated and will be removed in 3.0, use %s::pluralize() instead.',
 298              __METHOD__,
 299              DoctrineInflector::class
 300          );
 301  
 302          return static::pluralize($word);
 303      }
 304  
 305      /**
 306       * Converts a word into its singular form.
 307       *
 308       * @param   string  $word  The plural word to singularise.
 309       *
 310       * @return  string  The word in singular form.
 311       *
 312       * @since   1.0
 313       * @deprecated  3.0  Use Doctrine\Common\Inflector\Inflector::singularize() instead.
 314       */
 315  	public function toSingular($word)
 316      {
 317          trigger_deprecation(
 318              'joomla/string',
 319              '2.0.0',
 320              '%s() is deprecated and will be removed in 3.0, use %s::singularize() instead.',
 321              __METHOD__,
 322              DoctrineInflector::class
 323          );
 324  
 325          return static::singularize($word);
 326      }
 327  }