interface/modules/zend_modules/library/Zend/Filter/Inflector.php

   1 <?php
   2 /**
   3  * Zend Framework (http://framework.zend.com/)
   4  *
   5  * @link      http://github.com/zendframework/zf2 for the canonical source repository
   6  * @copyright Copyright (c) 2005-2013 Zend Technologies USA Inc. (http://www.zend.com)
   7  * @license   http://framework.zend.com/license/new-bsd New BSD License
   8  */
   9
  10 namespace Zend\Filter;
  11
  12 use Traversable;
  13 use Zend\Stdlib\ArrayUtils;
  14
  15 /**
  16  * Filter chain for string inflection
  17  */
  18 class Inflector extends AbstractFilter
  19 {
  20     /**
  21      * @var FilterPluginManager
  22      */
  23     protected $pluginManager = null;
  24
  25     /**
  26      * @var string
  27      */
  28     protected $target = null;
  29
  30     /**
  31      * @var bool
  32      */
  33     protected $throwTargetExceptionsOn = true;
  34
  35     /**
  36      * @var string
  37      */
  38     protected $targetReplacementIdentifier = ':';
  39
  40     /**
  41      * @var array
  42      */
  43     protected $rules = array();
  44
  45     /**
  46      * Constructor
  47      *
  48      * @param string|array|Traversable $options Options to set
  49      */
  50     public function __construct($options = null)
  51     {
  52         if ($options instanceof Traversable) {
  53             $options = ArrayUtils::iteratorToArray($options);
  54         }
  55         if (!is_array($options)) {
  56             $options = func_get_args();
  57             $temp    = array();
  58
  59             if (!empty($options)) {
  60                 $temp['target'] = array_shift($options);
  61             }
  62
  63             if (!empty($options)) {
  64                 $temp['rules'] = array_shift($options);
  65             }
  66
  67             if (!empty($options)) {
  68                 $temp['throwTargetExceptionsOn'] = array_shift($options);
  69             }
  70
  71             if (!empty($options)) {
  72                 $temp['targetReplacementIdentifier'] = array_shift($options);
  73             }
  74
  75             $options = $temp;
  76         }
  77
  78         $this->setOptions($options);
  79     }
  80
  81     /**
  82      * Retrieve plugin manager
  83      *
  84      * @return FilterPluginManager
  85      */
  86     public function getPluginManager()
  87     {
  88         if (!$this->pluginManager instanceof FilterPluginManager) {
  89             $this->setPluginManager(new FilterPluginManager());
  90         }
  91
  92         return $this->pluginManager;
  93     }
  94
  95     /**
  96      * Set plugin manager
  97      *
  98      * @param  FilterPluginManager $manager
  99      * @return self
 100      */
 101     public function setPluginManager(FilterPluginManager $manager)
 102     {
 103         $this->pluginManager = $manager;
 104         return $this;
 105     }
 106
 107     /**
 108      * Set options
 109      *
 110      * @param  array|Traversable $options
 111      * @return self
 112      */
 113     public function setOptions($options)
 114     {
 115         if ($options instanceof Traversable) {
 116             $options = ArrayUtils::iteratorToArray($options);
 117         }
 118
 119         // Set plugin manager
 120         if (array_key_exists('pluginManager', $options)) {
 121             if (is_scalar($options['pluginManager']) && class_exists($options['pluginManager'])) {
 122                 $options['pluginManager'] = new $options['pluginManager'];
 123             }
 124             $this->setPluginManager($options['pluginManager']);
 125         }
 126
 127         if (array_key_exists('throwTargetExceptionsOn', $options)) {
 128             $this->setThrowTargetExceptionsOn($options['throwTargetExceptionsOn']);
 129         }
 130
 131         if (array_key_exists('targetReplacementIdentifier', $options)) {
 132             $this->setTargetReplacementIdentifier($options['targetReplacementIdentifier']);
 133         }
 134
 135         if (array_key_exists('target', $options)) {
 136             $this->setTarget($options['target']);
 137         }
 138
 139         if (array_key_exists('rules', $options)) {
 140             $this->addRules($options['rules']);
 141         }
 142
 143         return $this;
 144     }
 145
 146     /**
 147      * Set Whether or not the inflector should throw an exception when a replacement
 148      * identifier is still found within an inflected target.
 149      *
 150      * @param  bool $throwTargetExceptionsOn
 151      * @return self
 152      */
 153     public function setThrowTargetExceptionsOn($throwTargetExceptionsOn)
 154     {
 155         $this->throwTargetExceptionsOn = ($throwTargetExceptionsOn == true) ? true : false;
 156         return $this;
 157     }
 158
 159     /**
 160      * Will exceptions be thrown?
 161      *
 162      * @return bool
 163      */
 164     public function isThrowTargetExceptionsOn()
 165     {
 166         return $this->throwTargetExceptionsOn;
 167     }
 168
 169     /**
 170      * Set the Target Replacement Identifier, by default ':'
 171      *
 172      * @param  string $targetReplacementIdentifier
 173      * @return self
 174      */
 175     public function setTargetReplacementIdentifier($targetReplacementIdentifier)
 176     {
 177         if ($targetReplacementIdentifier) {
 178             $this->targetReplacementIdentifier = (string) $targetReplacementIdentifier;
 179         }
 180
 181         return $this;
 182     }
 183
 184     /**
 185      * Get Target Replacement Identifier
 186      *
 187      * @return string
 188      */
 189     public function getTargetReplacementIdentifier()
 190     {
 191         return $this->targetReplacementIdentifier;
 192     }
 193
 194     /**
 195      * Set a Target
 196      * ex: 'scripts/:controller/:action.:suffix'
 197      *
 198      * @param  string $target
 199      * @return self
 200      */
 201     public function setTarget($target)
 202     {
 203         $this->target = (string) $target;
 204         return $this;
 205     }
 206
 207     /**
 208      * Retrieve target
 209      *
 210      * @return string
 211      */
 212     public function getTarget()
 213     {
 214         return $this->target;
 215     }
 216
 217     /**
 218      * Set Target Reference
 219      *
 220      * @param  reference $target
 221      * @return self
 222      */
 223     public function setTargetReference(&$target)
 224     {
 225         $this->target =& $target;
 226         return $this;
 227     }
 228
 229     /**
 230      * Is the same as calling addRules() with the exception that it
 231      * clears the rules before adding them.
 232      *
 233      * @param  array $rules
 234      * @return self
 235      */
 236     public function setRules(array $rules)
 237     {
 238         $this->clearRules();
 239         $this->addRules($rules);
 240         return $this;
 241     }
 242
 243     /**
 244      * Multi-call to setting filter rules.
 245      *
 246      * If prefixed with a ":" (colon), a filter rule will be added.  If not
 247      * prefixed, a static replacement will be added.
 248      *
 249      * ex:
 250      * array(
 251      *     ':controller' => array('CamelCaseToUnderscore', 'StringToLower'),
 252      *     ':action'     => array('CamelCaseToUnderscore', 'StringToLower'),
 253      *     'suffix'      => 'phtml'
 254      *     );
 255      *
 256      * @param  array $rules
 257      * @return self
 258      */
 259     public function addRules(array $rules)
 260     {
 261         $keys = array_keys($rules);
 262         foreach ($keys as $spec) {
 263             if ($spec[0] == ':') {
 264                 $this->addFilterRule($spec, $rules[$spec]);
 265             } else {
 266                 $this->setStaticRule($spec, $rules[$spec]);
 267             }
 268         }
 269
 270         return $this;
 271     }
 272
 273     /**
 274      * Get rules
 275      *
 276      * By default, returns all rules. If a $spec is provided, will return those
 277      * rules if found, false otherwise.
 278      *
 279      * @param  string $spec
 280      * @return array|false
 281      */
 282     public function getRules($spec = null)
 283     {
 284         if (null !== $spec) {
 285             $spec = $this->_normalizeSpec($spec);
 286             if (isset($this->rules[$spec])) {
 287                 return $this->rules[$spec];
 288             }
 289             return false;
 290         }
 291
 292         return $this->rules;
 293     }
 294
 295     /**
 296      * Returns a rule set by setFilterRule(), a numeric index must be provided
 297      *
 298      * @param  string $spec
 299      * @param  int $index
 300      * @return FilterInterface|false
 301      */
 302     public function getRule($spec, $index)
 303     {
 304         $spec = $this->_normalizeSpec($spec);
 305         if (isset($this->rules[$spec]) && is_array($this->rules[$spec])) {
 306             if (isset($this->rules[$spec][$index])) {
 307                 return $this->rules[$spec][$index];
 308             }
 309         }
 310         return false;
 311     }
 312
 313     /**
 314      * Clears the rules currently in the inflector
 315      *
 316      * @return self
 317      */
 318     public function clearRules()
 319     {
 320         $this->rules = array();
 321         return $this;
 322     }
 323
 324     /**
 325      * Set a filtering rule for a spec.  $ruleSet can be a string, Filter object
 326      * or an array of strings or filter objects.
 327      *
 328      * @param  string $spec
 329      * @param  array|string|\Zend\Filter\FilterInterface $ruleSet
 330      * @return self
 331      */
 332     public function setFilterRule($spec, $ruleSet)
 333     {
 334         $spec = $this->_normalizeSpec($spec);
 335         $this->rules[$spec] = array();
 336         return $this->addFilterRule($spec, $ruleSet);
 337     }
 338
 339     /**
 340      * Add a filter rule for a spec
 341      *
 342      * @param  mixed $spec
 343      * @param  mixed $ruleSet
 344      * @return self
 345      */
 346     public function addFilterRule($spec, $ruleSet)
 347     {
 348         $spec = $this->_normalizeSpec($spec);
 349         if (!isset($this->rules[$spec])) {
 350             $this->rules[$spec] = array();
 351         }
 352
 353         if (!is_array($ruleSet)) {
 354             $ruleSet = array($ruleSet);
 355         }
 356
 357         if (is_string($this->rules[$spec])) {
 358             $temp = $this->rules[$spec];
 359             $this->rules[$spec] = array();
 360             $this->rules[$spec][] = $temp;
 361         }
 362
 363         foreach ($ruleSet as $rule) {
 364             $this->rules[$spec][] = $this->_getRule($rule);
 365         }
 366
 367         return $this;
 368     }
 369
 370     /**
 371      * Set a static rule for a spec.  This is a single string value
 372      *
 373      * @param  string $name
 374      * @param  string $value
 375      * @return self
 376      */
 377     public function setStaticRule($name, $value)
 378     {
 379         $name = $this->_normalizeSpec($name);
 380         $this->rules[$name] = (string) $value;
 381         return $this;
 382     }
 383
 384     /**
 385      * Set Static Rule Reference.
 386      *
 387      * This allows a consuming class to pass a property or variable
 388      * in to be referenced when its time to build the output string from the
 389      * target.
 390      *
 391      * @param  string $name
 392      * @param  mixed $reference
 393      * @return self
 394      */
 395     public function setStaticRuleReference($name, &$reference)
 396     {
 397         $name = $this->_normalizeSpec($name);
 398         $this->rules[$name] =& $reference;
 399         return $this;
 400     }
 401
 402     /**
 403      * Inflect
 404      *
 405      * @param  string|array $source
 406      * @throws Exception\RuntimeException
 407      * @return string
 408      */
 409     public function filter($source)
 410     {
 411         // clean source
 412         foreach ((array) $source as $sourceName => $sourceValue) {
 413             $source[ltrim($sourceName, ':')] = $sourceValue;
 414         }
 415
 416         $pregQuotedTargetReplacementIdentifier = preg_quote($this->targetReplacementIdentifier, '#');
 417         $processedParts = array();
 418
 419         foreach ($this->rules as $ruleName => $ruleValue) {
 420             if (isset($source[$ruleName])) {
 421                 if (is_string($ruleValue)) {
 422                     // overriding the set rule
 423                     $processedParts['#' . $pregQuotedTargetReplacementIdentifier . $ruleName . '#'] = str_replace('\\', '\\\\', $source[$ruleName]);
 424                 } elseif (is_array($ruleValue)) {
 425                     $processedPart = $source[$ruleName];
 426                     foreach ($ruleValue as $ruleFilter) {
 427                         $processedPart = $ruleFilter($processedPart);
 428                     }
 429                     $processedParts['#' . $pregQuotedTargetReplacementIdentifier . $ruleName . '#'] = str_replace('\\', '\\\\', $processedPart);
 430                 }
 431             } elseif (is_string($ruleValue)) {
 432                 $processedParts['#' . $pregQuotedTargetReplacementIdentifier . $ruleName . '#'] = str_replace('\\', '\\\\', $ruleValue);
 433             }
 434         }
 435
 436         // all of the values of processedParts would have been str_replace('\\', '\\\\', ..)'d to disable preg_replace backreferences
 437         $inflectedTarget = preg_replace(array_keys($processedParts), array_values($processedParts), $this->target);
 438
 439         if ($this->throwTargetExceptionsOn && (preg_match('#(?=' . $pregQuotedTargetReplacementIdentifier.'[A-Za-z]{1})#', $inflectedTarget) == true)) {
 440             throw new Exception\RuntimeException('A replacement identifier ' . $this->targetReplacementIdentifier . ' was found inside the inflected target, perhaps a rule was not satisfied with a target source?  Unsatisfied inflected target: ' . $inflectedTarget);
 441         }
 442
 443         return $inflectedTarget;
 444     }
 445
 446     /**
 447      * Normalize spec string
 448      *
 449      * @param  string $spec
 450      * @return string
 451      */
 452     protected function _normalizeSpec($spec)
 453     {
 454         return ltrim((string) $spec, ':&');
 455     }
 456
 457     /**
 458      * Resolve named filters and convert them to filter objects.
 459      *
 460      * @param  string $rule
 461      * @return FilterInterface
 462      */
 463     protected function _getRule($rule)
 464     {
 465         if ($rule instanceof FilterInterface) {
 466             return $rule;
 467         }
 468
 469         $rule = (string) $rule;
 470         return $this->getPluginManager()->get($rule);
 471     }
 472 }