library/Zend/Filter/Inflector.php

   1 <?php
   2 /**
   3  * Zend Framework
   4  *
   5  * LICENSE
   6  *
   7  * This source file is subject to the new BSD license that is bundled
   8  * with this package in the file LICENSE.txt.
   9  * It is also available through the world-wide-web at this URL:
  10  * http://framework.zend.com/license/new-bsd
  11  * If you did not receive a copy of the license and are unable to
  12  * obtain it through the world-wide-web, please send an email
  13  * to license@zend.com so we can send you a copy immediately.
  14  *
  15  * @category   Zend
  16  * @package    Zend_Filter
  17  * @copyright  Copyright (c) 2005-2010 Zend Technologies USA Inc. (http://www.zend.com)
  18  * @license    http://framework.zend.com/license/new-bsd     New BSD License
  19  * @version    $Id$
  20  */
  21
  22 /**
  23  * @see Zend_Filter
  24  * @see Zend_Filter_Interface
  25  */
  26 require_once 'Zend/Filter.php';
  27
  28 /**
  29  * @see Zend_Loader_PluginLoader
  30  */
  31 require_once 'Zend/Loader/PluginLoader.php';
  32
  33 /**
  34  * Filter chain for string inflection
  35  *
  36  * @category   Zend
  37  * @package    Zend_Filter
  38  * @copyright  Copyright (c) 2005-2010 Zend Technologies USA Inc. (http://www.zend.com)
  39  * @license    http://framework.zend.com/license/new-bsd     New BSD License
  40  */
  41 class Zend_Filter_Inflector implements Zend_Filter_Interface
  42 {
  43     /**
  44      * @var Zend_Loader_PluginLoader_Interface
  45      */
  46     protected $_pluginLoader = null;
  47
  48     /**
  49      * @var string
  50      */
  51     protected $_target = null;
  52
  53     /**
  54      * @var bool
  55      */
  56     protected $_throwTargetExceptionsOn = true;
  57
  58     /**
  59      * @var string
  60      */
  61     protected $_targetReplacementIdentifier = ':';
  62
  63     /**
  64      * @var array
  65      */
  66     protected $_rules = array();
  67
  68     /**
  69      * Constructor
  70      *
  71      * @param string|array $options Options to set
  72      */
  73     public function __construct($options = null)
  74     {
  75         if ($options instanceof Zend_Config) {
  76             $options = $options->toArray();
  77         } else if (!is_array($options)) {
  78             $options = func_get_args();
  79             $temp    = array();
  80
  81             if (!empty($options)) {
  82                 $temp['target'] = array_shift($options);
  83             }
  84
  85             if (!empty($options)) {
  86                 $temp['rules'] = array_shift($options);
  87             }
  88
  89             if (!empty($options)) {
  90                 $temp['throwTargetExceptionsOn'] = array_shift($options);
  91             }
  92
  93             if (!empty($options)) {
  94                 $temp['targetReplacementIdentifier'] = array_shift($options);
  95             }
  96
  97             $options = $temp;
  98         }
  99
 100         $this->setOptions($options);
 101     }
 102
 103     /**
 104      * Retreive PluginLoader
 105      *
 106      * @return Zend_Loader_PluginLoader_Interface
 107      */
 108     public function getPluginLoader()
 109     {
 110         if (!$this->_pluginLoader instanceof Zend_Loader_PluginLoader_Interface) {
 111             $this->_pluginLoader = new Zend_Loader_PluginLoader(array('Zend_Filter_' => 'Zend/Filter/'), __CLASS__);
 112         }
 113
 114         return $this->_pluginLoader;
 115     }
 116
 117     /**
 118      * Set PluginLoader
 119      *
 120      * @param Zend_Loader_PluginLoader_Interface $pluginLoader
 121      * @return Zend_Filter_Inflector
 122      */
 123     public function setPluginLoader(Zend_Loader_PluginLoader_Interface $pluginLoader)
 124     {
 125         $this->_pluginLoader = $pluginLoader;
 126         return $this;
 127     }
 128
 129     /**
 130      * Use Zend_Config object to set object state
 131      *
 132      * @deprecated Use setOptions() instead
 133      * @param  Zend_Config $config
 134      * @return Zend_Filter_Inflector
 135      */
 136     public function setConfig(Zend_Config $config)
 137     {
 138         return $this->setOptions($config);
 139     }
 140
 141     /**
 142      * Set options
 143      *
 144      * @param  array $options
 145      * @return Zend_Filter_Inflector
 146      */
 147     public function setOptions($options) {
 148         if ($options instanceof Zend_Config) {
 149             $options = $options->toArray();
 150         }
 151
 152         // Set Präfix Path
 153         if (array_key_exists('filterPrefixPath', $options)) {
 154             if (!is_scalar($options['filterPrefixPath'])) {
 155                 foreach ($options['filterPrefixPath'] as $prefix => $path) {
 156                     $this->addFilterPrefixPath($prefix, $path);
 157                 }
 158             }
 159         }
 160
 161         if (array_key_exists('throwTargetExceptionsOn', $options)) {
 162             $this->setThrowTargetExceptionsOn($options['throwTargetExceptionsOn']);
 163         }
 164
 165         if (array_key_exists('targetReplacementIdentifier', $options)) {
 166             $this->setTargetReplacementIdentifier($options['targetReplacementIdentifier']);
 167         }
 168
 169         if (array_key_exists('target', $options)) {
 170             $this->setTarget($options['target']);
 171         }
 172
 173         if (array_key_exists('rules', $options)) {
 174             $this->addRules($options['rules']);
 175         }
 176
 177         return $this;
 178     }
 179
 180     /**
 181      * Convienence method to add prefix and path to PluginLoader
 182      *
 183      * @param string $prefix
 184      * @param string $path
 185      * @return Zend_Filter_Inflector
 186      */
 187     public function addFilterPrefixPath($prefix, $path)
 188     {
 189         $this->getPluginLoader()->addPrefixPath($prefix, $path);
 190         return $this;
 191     }
 192
 193     /**
 194      * Set Whether or not the inflector should throw an exception when a replacement
 195      * identifier is still found within an inflected target.
 196      *
 197      * @param bool $throwTargetExceptions
 198      * @return Zend_Filter_Inflector
 199      */
 200     public function setThrowTargetExceptionsOn($throwTargetExceptionsOn)
 201     {
 202         $this->_throwTargetExceptionsOn = ($throwTargetExceptionsOn == true) ? true : false;
 203         return $this;
 204     }
 205
 206     /**
 207      * Will exceptions be thrown?
 208      *
 209      * @return bool
 210      */
 211     public function isThrowTargetExceptionsOn()
 212     {
 213         return $this->_throwTargetExceptionsOn;
 214     }
 215
 216     /**
 217      * Set the Target Replacement Identifier, by default ':'
 218      *
 219      * @param string $targetReplacementIdentifier
 220      * @return Zend_Filter_Inflector
 221      */
 222     public function setTargetReplacementIdentifier($targetReplacementIdentifier)
 223     {
 224         if ($targetReplacementIdentifier) {
 225             $this->_targetReplacementIdentifier = (string) $targetReplacementIdentifier;
 226         }
 227
 228         return $this;
 229     }
 230
 231     /**
 232      * Get Target Replacement Identifier
 233      *
 234      * @return string
 235      */
 236     public function getTargetReplacementIdentifier()
 237     {
 238         return $this->_targetReplacementIdentifier;
 239     }
 240
 241     /**
 242      * Set a Target
 243      * ex: 'scripts/:controller/:action.:suffix'
 244      *
 245      * @param string
 246      * @return Zend_Filter_Inflector
 247      */
 248     public function setTarget($target)
 249     {
 250         $this->_target = (string) $target;
 251         return $this;
 252     }
 253
 254     /**
 255      * Retrieve target
 256      *
 257      * @return string
 258      */
 259     public function getTarget()
 260     {
 261         return $this->_target;
 262     }
 263
 264     /**
 265      * Set Target Reference
 266      *
 267      * @param reference $target
 268      * @return Zend_Filter_Inflector
 269      */
 270     public function setTargetReference(&$target)
 271     {
 272         $this->_target =& $target;
 273         return $this;
 274     }
 275
 276     /**
 277      * SetRules() is the same as calling addRules() with the exception that it
 278      * clears the rules before adding them.
 279      *
 280      * @param array $rules
 281      * @return Zend_Filter_Inflector
 282      */
 283     public function setRules(Array $rules)
 284     {
 285         $this->clearRules();
 286         $this->addRules($rules);
 287         return $this;
 288     }
 289
 290     /**
 291      * AddRules(): multi-call to setting filter rules.
 292      *
 293      * If prefixed with a ":" (colon), a filter rule will be added.  If not
 294      * prefixed, a static replacement will be added.
 295      *
 296      * ex:
 297      * array(
 298      *     ':controller' => array('CamelCaseToUnderscore','StringToLower'),
 299      *     ':action'     => array('CamelCaseToUnderscore','StringToLower'),
 300      *     'suffix'      => 'phtml'
 301      *     );
 302      *
 303      * @param array
 304      * @return Zend_Filter_Inflector
 305      */
 306     public function addRules(Array $rules)
 307     {
 308         $keys = array_keys($rules);
 309         foreach ($keys as $spec) {
 310             if ($spec[0] == ':') {
 311                 $this->addFilterRule($spec, $rules[$spec]);
 312             } else {
 313                 $this->setStaticRule($spec, $rules[$spec]);
 314             }
 315         }
 316
 317         return $this;
 318     }
 319
 320     /**
 321      * Get rules
 322      *
 323      * By default, returns all rules. If a $spec is provided, will return those
 324      * rules if found, false otherwise.
 325      *
 326      * @param  string $spec
 327      * @return array|false
 328      */
 329     public function getRules($spec = null)
 330     {
 331         if (null !== $spec) {
 332             $spec = $this->_normalizeSpec($spec);
 333             if (isset($this->_rules[$spec])) {
 334                 return $this->_rules[$spec];
 335             }
 336             return false;
 337         }
 338
 339         return $this->_rules;
 340     }
 341
 342     /**
 343      * getRule() returns a rule set by setFilterRule(), a numeric index must be provided
 344      *
 345      * @param string $spec
 346      * @param int $index
 347      * @return Zend_Filter_Interface|false
 348      */
 349     public function getRule($spec, $index)
 350     {
 351         $spec = $this->_normalizeSpec($spec);
 352         if (isset($this->_rules[$spec]) && is_array($this->_rules[$spec])) {
 353             if (isset($this->_rules[$spec][$index])) {
 354                 return $this->_rules[$spec][$index];
 355             }
 356         }
 357         return false;
 358     }
 359
 360     /**
 361      * ClearRules() clears the rules currently in the inflector
 362      *
 363      * @return Zend_Filter_Inflector
 364      */
 365     public function clearRules()
 366     {
 367         $this->_rules = array();
 368         return $this;
 369     }
 370
 371     /**
 372      * Set a filtering rule for a spec.  $ruleSet can be a string, Filter object
 373      * or an array of strings or filter objects.
 374      *
 375      * @param string $spec
 376      * @param array|string|Zend_Filter_Interface $ruleSet
 377      * @return Zend_Filter_Inflector
 378      */
 379     public function setFilterRule($spec, $ruleSet)
 380     {
 381         $spec = $this->_normalizeSpec($spec);
 382         $this->_rules[$spec] = array();
 383         return $this->addFilterRule($spec, $ruleSet);
 384     }
 385
 386     /**
 387      * Add a filter rule for a spec
 388      *
 389      * @param mixed $spec
 390      * @param mixed $ruleSet
 391      * @return void
 392      */
 393     public function addFilterRule($spec, $ruleSet)
 394     {
 395         $spec = $this->_normalizeSpec($spec);
 396         if (!isset($this->_rules[$spec])) {
 397             $this->_rules[$spec] = array();
 398         }
 399
 400         if (!is_array($ruleSet)) {
 401             $ruleSet = array($ruleSet);
 402         }
 403
 404         if (is_string($this->_rules[$spec])) {
 405             $temp = $this->_rules[$spec];
 406             $this->_rules[$spec] = array();
 407             $this->_rules[$spec][] = $temp;
 408         }
 409
 410         foreach ($ruleSet as $rule) {
 411             $this->_rules[$spec][] = $this->_getRule($rule);
 412         }
 413
 414         return $this;
 415     }
 416
 417     /**
 418      * Set a static rule for a spec.  This is a single string value
 419      *
 420      * @param string $name
 421      * @param string $value
 422      * @return Zend_Filter_Inflector
 423      */
 424     public function setStaticRule($name, $value)
 425     {
 426         $name = $this->_normalizeSpec($name);
 427         $this->_rules[$name] = (string) $value;
 428         return $this;
 429     }
 430
 431     /**
 432      * Set Static Rule Reference.
 433      *
 434      * This allows a consuming class to pass a property or variable
 435      * in to be referenced when its time to build the output string from the
 436      * target.
 437      *
 438      * @param string $name
 439      * @param mixed $reference
 440      * @return Zend_Filter_Inflector
 441      */
 442     public function setStaticRuleReference($name, &$reference)
 443     {
 444         $name = $this->_normalizeSpec($name);
 445         $this->_rules[$name] =& $reference;
 446         return $this;
 447     }
 448
 449     /**
 450      * Inflect
 451      *
 452      * @param  string|array $source
 453      * @return string
 454      */
 455     public function filter($source)
 456     {
 457         // clean source
 458         foreach ( (array) $source as $sourceName => $sourceValue) {
 459             $source[ltrim($sourceName, ':')] = $sourceValue;
 460         }
 461
 462         $pregQuotedTargetReplacementIdentifier = preg_quote($this->_targetReplacementIdentifier, '#');
 463         $processedParts = array();
 464
 465         foreach ($this->_rules as $ruleName => $ruleValue) {
 466             if (isset($source[$ruleName])) {
 467                 if (is_string($ruleValue)) {
 468                     // overriding the set rule
 469                     $processedParts['#'.$pregQuotedTargetReplacementIdentifier.$ruleName.'#'] = str_replace('\\', '\\\\', $source[$ruleName]);
 470                 } elseif (is_array($ruleValue)) {
 471                     $processedPart = $source[$ruleName];
 472                     foreach ($ruleValue as $ruleFilter) {
 473                         $processedPart = $ruleFilter->filter($processedPart);
 474                     }
 475                     $processedParts['#'.$pregQuotedTargetReplacementIdentifier.$ruleName.'#'] = str_replace('\\', '\\\\', $processedPart);
 476                 }
 477             } elseif (is_string($ruleValue)) {
 478                 $processedParts['#'.$pregQuotedTargetReplacementIdentifier.$ruleName.'#'] = str_replace('\\', '\\\\', $ruleValue);
 479             }
 480         }
 481
 482         // all of the values of processedParts would have been str_replace('\\', '\\\\', ..)'d to disable preg_replace backreferences
 483         $inflectedTarget = preg_replace(array_keys($processedParts), array_values($processedParts), $this->_target);
 484
 485         if ($this->_throwTargetExceptionsOn && (preg_match('#(?='.$pregQuotedTargetReplacementIdentifier.'[A-Za-z]{1})#', $inflectedTarget) == true)) {
 486             require_once 'Zend/Filter/Exception.php';
 487             throw new Zend_Filter_Exception('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);
 488         }
 489
 490         return $inflectedTarget;
 491     }
 492
 493     /**
 494      * Normalize spec string
 495      *
 496      * @param  string $spec
 497      * @return string
 498      */
 499     protected function _normalizeSpec($spec)
 500     {
 501         return ltrim((string) $spec, ':&');
 502     }
 503
 504     /**
 505      * Resolve named filters and convert them to filter objects.
 506      *
 507      * @param  string $rule
 508      * @return Zend_Filter_Interface
 509      */
 510     protected function _getRule($rule)
 511     {
 512         if ($rule instanceof Zend_Filter_Interface) {
 513             return $rule;
 514         }
 515
 516         $rule = (string) $rule;
 517
 518         $className  = $this->getPluginLoader()->load($rule);
 519         $ruleObject = new $className();
 520         if (!$ruleObject instanceof Zend_Filter_Interface) {
 521             require_once 'Zend/Filter/Exception.php';
 522             throw new Zend_Filter_Exception('No class named ' . $rule . ' implementing Zend_Filter_Interface could be found');
 523         }
 524
 525         return $ruleObject;
 526     }
 527 }