Zend\Filter\Inflector

Zend\Filter\Inflector is a general purpose tool for rules-based inflection of strings to a given target.

As an example, you may find you need to transform MixedCase or camelCasedWords into a path; for readability, OS policies, or other reasons, you also need to lower case this, and you want to separate the words using a dash (‘-‘). An inflector can do this for you.

Zend\Filter\Inflector implements Zend\Filter\FilterInterface; you perform inflection by calling filter() on the object instance.

Transforming MixedCase and camelCaseText to another format

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
$inflector = new Zend\Filter\Inflector('pages/:page.:suffix');
$inflector->setRules(array(
    ':page'  => array('Word\CamelCaseToDash', 'StringToLower'),
    'suffix' => 'html',
));

$string   = 'camelCasedWords';
$filtered = $inflector->filter(array('page' => $string));
// pages/camel-cased-words.html

$string   = 'this_is_not_camel_cased';
$filtered = $inflector->filter(array('page' => $string));
// pages/this_is_not_camel_cased.html

Operation

An inflector requires a target and one or more rules. A target is basically a string that defines placeholders for variables you wish to substitute. These are specified by prefixing with a ‘:’: :script.

When calling filter(), you then pass in an array of key and value pairs corresponding to the variables in the target.

Each variable in the target can have zero or more rules associated with them. Rules may be either static or refer to a Zend\Filter class. Static rules will replace with the text provided. Otherwise, a class matching the rule provided will be used to inflect the text. Classes are typically specified using a short name indicating the filter name stripped of any common prefix.

As an example, you can use any Zend\Filter concrete implementations; however, instead of referring to them as ‘Zend\Filter\Alpha‘ or ‘Zend\Filter\StringToLower‘, you’d specify only ‘Alpha‘ or ‘StringToLower‘.

Using Custom Filters

Zend\Filter\Inflector uses Zend\Filter\FilterPluginManager to manage loading filters to use with inflection. By default, filters registered with Zend\Filter\FilterPluginManager are available. To access filters with that prefix but which occur deeper in the hierarchy, such as the various Word filters, simply strip off the Zend\Filter prefix:

1
2
// use Zend\Filter\Word\CamelCaseToDash as a rule
$inflector->addRules(array('script' => 'Word\CamelCaseToDash'));

To use custom filters, you have two choices: reference them by fully qualified class name (e.g., My\Custom\Filter\Mungify), or manipulate the composed FilterPluginManager instance.

1
2
$filters = $inflector->getPluginManager();
$filters->addInvokableClass('mungify', 'My\Custom\Filter\Mungify');

Setting the Inflector Target

The inflector target is a string with some placeholders for variables. Placeholders take the form of an identifier, a colon (‘:’) by default, followed by a variable name: ‘:script’, ‘:path’, etc. The filter() method looks for the identifier followed by the variable name being replaced.

You can change the identifier using the setTargetReplacementIdentifier() method, or passing it as the third argument to the constructor:

1
2
3
4
5
// Via constructor:
$inflector = new Zend\Filter\Inflector('#foo/#bar.#sfx', null, '#');

// Via accessor:
$inflector->setTargetReplacementIdentifier('#');

Typically, you will set the target via the constructor. However, you may want to re-set the target later. setTarget() can be used for this purpose:

1
$inflector->setTarget('layouts/:script.phtml');

Additionally, you may wish to have a class member for your class that you can use to keep the inflector target updated – without needing to directly update the target each time (thus saving on method calls). setTargetReference() allows you to do this:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
class Foo
{
    /**
     * @var string Inflector target
     */
    protected $_target = 'foo/:bar/:baz.:suffix';

    /**
     * Constructor
     * @return void
     */
    public function __construct()
    {
        $this->_inflector = new Zend\Filter\Inflector();
        $this->_inflector->setTargetReference($this->_target);
    }

    /**
     * Set target; updates target in inflector
     *
     * @param  string $target
     * @return Foo
     */
    public function setTarget($target)
    {
        $this->_target = $target;
        return $this;
    }
}

Inflection Rules

As mentioned in the introduction, there are two types of rules: static and filter-based.

Note

It is important to note that regardless of the method in which you add rules to the inflector, either one-by-one, or all-at-once; the order is very important. More specific names, or names that might contain other rule names, must be added before least specific names. For example, assuming the two rule names ‘moduleDir’ and ‘module’, the ‘moduleDir’ rule should appear before module since ‘module’ is contained within ‘moduleDir’. If ‘module’ were added before ‘moduleDir’, ‘module’ will match part of ‘moduleDir’ and process it leaving ‘Dir’ inside of the target uninflected.

Static Rules

Static rules do simple string substitution; use them when you have a segment in the target that will typically be static, but which you want to allow the developer to modify. Use the setStaticRule() method to set or modify the rule:

1
2
3
4
5
$inflector = new Zend\Filter\Inflector(':script.:suffix');
$inflector->setStaticRule('suffix', 'phtml');

// change it later:
$inflector->setStaticRule('suffix', 'php');

Much like the target itself, you can also bind a static rule to a reference, allowing you to update a single variable instead of require a method call; this is often useful when your class uses an inflector internally, and you donR