Very brief introduction to Di.¶

Dependency Injection is a concept that has been talked about in numerous places over the web. For the purposes of this quickstart, we’ll explain the act of injecting dependencies simply with this below code:

1

$b = new B(new A));

Above, A is a dependency of B, and A was injected into B. If you are not familar with the concept of dependency injection, here are a couple of great reads: Matthew Weier O’Phinney’s Analogy, Ralph Schindler’s Learning DI, or Fabien Potencier’s Series on DI.

Very brief introduction to Di Container.¶

1

TBD.

Simplest usage case (2 classes, one consumes the other)¶

In the simplest use case, a developer might have one class (A) that is consumed by another class (B) through the constructor. By having the dependency injected through the constructor, this requires an object of type A be instantiated before an object of type B so that A can be injected into B.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16

namespace My {

    class A
    {
        /* Some useful functionality */
    }

    class B
    {
        protected $a = null;
        public function __construct(A $a)
        {
            $this->a = $a;
        }
    }
}

To create B by hand, a developer would follow this work flow, or a similar workflow to this:

1

$b = new B(new A());

If this workflow becomes repeated throughout your application multiple times, this creates an opportunity where one might want to DRY up the code. While there are several ways to do this, using a dependency injection container is one of these solutions. With Zend’s dependency injection container Zend\Di\DependencyInjector, the above use case can be taken care of with no configuration (provided all of your autoloading is already configured properly) with the following usage:

1
2

$di = new Zend\Di\DependencyInjector;
$b = $di->get('My\B'); // will produce a B object that is consuming an A object

Moreover, by using the DependencyInjector::get() method, you are ensuring that the same exact object is returned on subsequent calls. To force new objects to be created on each and every request, one would use the DependencyInjector::newInstance() method:

1

$b = $di->newInstance('My\B');

Let’s assume for a moment that A requires some configuration before it can be created. Our previous use case is expanded to this (we’ll throw a 3rd class in for good measure):

 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
30
31
32

namespace My {

    class A
    {
        protected $username = null;
        protected $password = null;
        public function __construct($username, $password)
        {
            $this->username = $username;
            $this->password = $password;
        }
    }

    class B
    {
        protected $a = null;
        public function __construct(A $a)
        {
            $this->a = $a;
        }
    }

    class C
    {
        protected $b = null;
        public function __construct(B $b)
        {
            $this->b = $b;
        }
    }

}

With the above, we need to ensure that our DependencyInjector is capable of seeing the A class with a few configuration values (which are generally scalar in nature). To do this, we need to interact with the InstanceManager:

1
2
3

$di = new Zend\Di\DependencyInjector;
$di->getInstanceManager()->setProperty('A', 'username', 'MyUsernameValue');
$di->getInstanceManager()->setProperty('A', 'password', 'MyHardToGuessPassword%$#');

Now that our container has values it can use when creating A, and our new goal is to have a C object that consumes B and in turn consumes A, the usage scenario is still the same:

1
2
3

$c = $di->get('My\C');
// or
$c = $di->newInstance('My\C');

Simple enough, but what if we wanted to pass in these parameters at call time? Assuming a default DependencyInjector object ($di = new Zend\Di\DependencyInjector() without any configuration to the InstanceManager), we could do the following:

1
2
3
4
5
6
7
8

$parameters = array(
    'username' => 'MyUsernameValue',
    'password' => 'MyHardToGuessPassword%$#',
);

$c = $di->get('My\C', $parameters);
// or
$c = $di->newInstance('My\C', $parameters);

Constructor injection is not the only supported type of injection. The other most popular method of injection is also supported: setter injection. Setter injection allows one to have a usage scenario that is the same as our previous example with the exception, for example, of our B class now looking like this:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10

namespace My {
    class B
    {
        protected $a;
        public function setA(A $a)
        {
            $this->a = $a;
        }
    }
}

Since the method is prefixed with set, and is followed by a capital letter, the DependencyInjector knows that this method is used for setter injection, and again, the use case $c = $di->get('C'), will once again know how to fill the dependencies when needed to create an object of type C.

Other methods are being created to determine what the wirings between classes are, such as interface injection and annotation based injection.

Simplest Usage Case Without Type-hints¶

If your code does not have type-hints or you are using 3rd party code that does not have type-hints but does practice dependency injection, you can still use the DependencyInjector, but you might find you need to describe your dependencies explicitly. To do this, you will need to interact with one of the definitions that is capable of letting a developer describe, with objects, the map between classes. This particular definition is called the BuilderDefinition and can work with, or in place of, the default RuntimeDefinition.

Definitions are a part of the DependencyInjector that attempt to describe the relationship between classes so that DependencyInjector::newInstance() and DependencyInjector::get() can know what the dependencies are that need to be filled for a particular class/object. With no configuration, DependencyInjector will use the RuntimeDefinition which uses reflection and the type-hints in your code to determine the dependency map. Without type-hints, it will assume that all dependencies are scalar or required configuration parameters.

The BuilderDefinition, which can be used in tandem with the RuntimeDefinition (technically, it can be used in tandem with any definition by way of the AggregateDefinition), allows you to programmatically describe the mappings with objects. Let’s say for example, our above A/B/C usage scenario, were altered such that class B now looks like this:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10

namespace My {
    class B
    {
        protected $a;
        public function setA($a)
        {
            $this->a = $a;
        }
    }
}

You’ll notice the only change is that setA now does not include any type-hinting information.

 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
30
31

use Zend\Di\DependencyInjector;
use Zend\Di\Definition;
use Zend\Di\Definition\Builder;

// Describe this class:
$builder = new Definition\BuilderDefinition;
$builder->addClass(($class = new Builder\PhpClass));

$class->setName('My\B');
$class->addInjectableMethod(($im = new Builder\InjectibleMethod));

$im->setName('setA');
$im->addParameter('a', 'My\A');

// Use both our Builder Definition as well as the default
// RuntimeDefinition, builder first
$aDef = new Definition\AggregateDefinition;
$aDef->addDefinition($builder);
$aDef->addDefinition(new Definition\RuntimeDefinition);

// Now make sure the DependencyInjector understands it
$di = new DependencyInjector;
$di->setDefinition($aDef);

// and finally, create C
$parameters = array(
    'username' => 'MyUsernameValue',
    'password' => 'MyHardToGuessPassword%$#',
);

$c = $di->get('My\C', $parameters);

This above usage scenario provides that whatever the code looks like, you can ensure that it works with the dependency injection container. In an ideal world, all of your code would have the proper type hinting and/or would be using a mapping strategy that reduces the amount of bootstrapping work that needs to be done in order to have a full definition that is capable of instantiating all of the objects you might require.

Simplest usage case with Compiled Definition¶

Without going into the gritty details, as you might expect, PHP at its core is not DI friendly. Out-of-the-box, the DependencyInjector uses a RuntimeDefinition which does all class map resolution via PHP’s Reflection extension. Couple that with the fact that PHP does not have a true application layer capable of storing objects in-memory between requests, and you get a recipe that is less performant than similar solutions you’ll find in Java and .Net (where there is an application layer with in-memory object storage.)

To mitigate this shortcoming, Zend\Di has several features built in capable of pre-compiling the most expensive tasks that surround dependency injection. It is worth noting that the RuntimeDefition, which is used by default, is the only definition that does lookups on-demand. The rest of the Definition objects are capable of being aggregated and stored to disk in a very performant way.

Ideally, 3rd party code will ship with a pre-compiled Definition that will describe the various relationships and parameter/property needs of each class that is to be instantiated. This Definition would have been built as part of some deployment or packaging task by this 3rd party. When this is not the case, you can create these Definitions via any of the Definition types provided with the exception of the RuntimeDefinition. Here is a breakdown of the job of each definition type:

• AggregateDefinition- Aggregates multiple definitions of various types. When looking for a class, it looks it up in the order the definitions were provided to this aggregate.
• ArrayDefinition- This definition takes an array of information and exposes it via the interface provided by Zend\Di\Definition suitable for usage by DependencyInjector or an AggregateDefinition
• BuilderDefinition- Creates a definition based on an object graph consisting of various Builder\PhpClass objects and Builder\InectionMethod objects that describe the mapping needs of the target codebase and …
• Compiler- This is not actually a definition, but produces an ArrayDefinition based off of a code scanner (Zend\Code\Scanner\DirectoryScanner or Zend\Code\Scanner\FileScanner).

The following is an example of producing a definition via a DirectoryScanner:

1
2
3
4
5

$compiler = new Zend\Di\Definition\Compiler();
$compiler->addCodeScannerDirectory(
    new Zend\Code\Scanner\ScannerDirectory('path/to/library/My/')
);
$definition = $compiler->compile();

This definition can then be directly used by the DependencyInjector (assuming the above A, B, C scenario was actually a file per class on disk):

1
2
3
4
5

$di = new Zend\Di\DependencyInjector;
$di->setDefinition($definition);
$di->getInstanceManager()->setProperty('My\A', 'username', 'foo');
$di->getInstanceManager()->setProperty('My\A', 'password', 'bar');
$c = $di->get('My\C');

One strategy for persisting these compiled definitions would be the following:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18

if (!file_exists(__DIR__ . '/di-definition.php') && $isProduction) {
    $compiler = new Zend\Di\Definition\Compiler();
    $compiler->addCodeScannerDirectory(
        new Zend\Code\Scanner\ScannerDirectory('path/to/library/My/')
    );
    $definition = $compiler->compile();
    file_put_contents(
        __DIR__ . '/di-definition.php',
        '<?php return ' . var_export($definition->toArray(), true) . ';'
    );
} else {
    $definition = new Zend\Di\Definition\ArrayDefinition(
        include __DIR__ . '/di-definition.php'
    );
}

// $definition can now be used; in a production system it will be written
// to disk.

Since Zend\Code\Scanner does not include files, the classes contained within are not loaded into memory. Instead, Zend\Code\Scanner uses tokenization to determine the structure of your files. This makes this suitable to use this solution during development and within the same request as any one of your application’s dispatched actions.

Creating a precompiled definition for others to use¶

If you are a 3rd party code developer, it makes sense to produce a Definition file that describes your code so that others can utilize this Definition without having to Reflect it via the RuntimeDefintion, or create it via the Compiler. To do this, use the same technique as above. Instead of writing the resulting array to disk, you would write the information into a definition directly, by way of Zend\CodeGenerator:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16

// First, compile the information
$compiler = new Zend\Di\Definition\Compiler();
$compiler->addCodeScannerDirectory(new Zend\Code\Scanner\DirectoryScanner(__DIR__ . '/My/'));
$definition = $compiler->compile();

// Now, create a Definition class for this information
$codeGenerator = new Zend\CodeGenerator\Php\PhpFile();
$codeGenerator->setClass(($class = new Zend\CodeGenerator\Php\PhpClass()));
$class->setNamespaceName('My');
$class->setName('DiDefinition');
$class->setExtendedClass('\Zend\Di\Definition\ArrayDefinition');
$class->setMethod(array(
    'name' => '__construct',
    'body' => 'parent::__construct(' . var_export($definition->toArray(), true) . ');'
));
file_put_contents(__DIR__ . '/My/DiDefinition.php', $codeGenerator->generate());

Using Multiple Definitions From Multiple Sources¶

In all actuality, you will be using code from multiple places, some Zend Framework code, some other 3rd party code, and of course, your own code that makes up your application. Here is a method for consuming definitions from multiple places:

 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
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44

use Zend\Di\DependencyInjector;
use Zend\Di\Definition;
use Zend\Di\Definition\Builder;

$di = new DependencyInjector;
$diDefAggregate = new Definition\Aggregate();

// first add in provided Definitions, for example
$diDefAggregate->addDefinition(new ThirdParty\Dbal\DiDefinition());
$diDefAggregate->addDefinition(new Zend\Controller\DiDefinition());

// for code that does not have TypeHints
$builder = new Definition\BuilderDefinition();
$builder->addClass(($class = Builder\PhpClass));
$class->addInjectionMethod(
    ($injectMethod = new Builder\InjectionMethod())
);
$injectMethod->setName('injectImplementation');
$injectMethod->addParameter(
'implementation', 'Class\For\Specific\Implementation'
);

// now, your application code
$compiler = new Definition\Compiler()
$compiler->addCodeScannerDirectory(
    new Zend\Code\Scanner\DirectoryScanner(__DIR__ . '/App/')
);
$appDefinition = $compiler->compile();
$diDefAggregate->addDefinition($appDefinition);

// now, pass in properties
$im = $di->getInstanceManager();

// this could come from Zend\Config\Config::toArray
$propertiesFromConfig = array(
    'ThirdParty\Dbal\DbAdapter' => array(
        'username' => 'someUsername',
        'password' => 'somePassword'
    ),
    'Zend\Controller\Helper\ContentType' => array(
        'default' => 'xhtml5'
    ),
);
$im->setProperties($propertiesFromConfig);

Generating Service Locators¶

In production, you want things to be as fast as possible. The Dependency Injection Container, while engineered for speed, still must do a fair bit of work resolving parameters and dependencies at runtime. What if you could speed things up and remove those lookups?

The Zend\Di\ServiceLocator\Generator component can do just that. It takes a configured DI instance, and generates a service locator class for you from it. That class will manage instances for you, as well as provide hard-coded, lazy-loading instantiation of instances.

The method getCodeGenerator() returns an instance of Zend\CodeGenerator\Php\PhpFile, from which you can then write a class file with the new Service Locator. Methods on the Generator class allow you to specify the namespace and class for the generated Service Locator.

As an example, consider the following:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10

use Zend\Di\ServiceLocator\Generator;

// $di is a fully configured DI instance
$generator = new Generator($di);

$generator->setNamespace('Application')
          ->setContainerClass('Context');
$file = $generator->getCodeGenerator();
$file->setFilename(__DIR__ . '/../Application/Context.php');
$file->write();

The above code will write to ../Application/Context.php, and that file will contain the class Application\Context. That file might look like the following:

 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
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56

<?php

namespace Application;

use Zend\Di\ServiceLocator;

class Context extends ServiceLocator
{

    public function get($name, array $params = array())
    {
        switch ($name) {
            case 'composed':
            case 'My\ComposedClass':
                return $this->getMyComposedClass();

            case 'struct':
            case 'My\Struct':
                return $this->getMyStruct();

            default:
                return parent::get($name, $params);
        }
    }

    public function getComposedClass()
    {
        if (isset($this->services['My\ComposedClass'])) {
            return $this->services['My\ComposedClass'];
        }

        $object = new \My\ComposedClass();
        $this->services['My\ComposedClass'] = $object;
        return $object;
    }
    public function getMyStruct()
    {
        if (isset($this->services['My\Struct'])) {
            return $this->services['My\Struct'];
        }

        $object = new \My\Struct();
        $this->services['My\Struct'] = $object;
        return $object;
    }

    public function getComposed()
    {
        return $this->get('My\ComposedClass');
    }

    public function getStruct()
    {
        return $this->get('My\Struct');
    }
}

To use this class, you simply consume it as you would a DI container:

1
2
3

$container = new Application\Context;

$struct = $container->get('struct'); // My\Struct instance

One note about this functionality in its current incarnation. Configuration is per-environment only at this time. This means that you will need to generate a container per execution environment. Our recommendation is that you do so, and then in your environment, specify the container class to use.

Adapters¶

Zend\Authentication adapters are used to authenticate against a particular type of authentication service, such as LDAP, RDBMS, or file-based storage. Different adapters are likely to have vastly different options and behaviors, but some basic things are common among authentication adapters. For example, accepting authentication credentials (including a purported identity), performing queries against the authentication service, and returning results are common to Zend\Authentication adapters.

Each Zend\Authentication adapter class implements Zend\Authentication\Adapter\AdapterInterface. This interface defines one method, authenticate(), that an adapter class must implement for performing an authentication query. Each adapter class must be prepared prior to calling authenticate(). Such adapter preparation includes setting up credentials (e.g., username and password) and defining values for adapter-specific configuration options, such as database connection settings for a database table adapter.

The following is an example authentication adapter that requires a username and password to be set for authentication. Other details, such as how the authentication service is queried, have been omitted for brevity:

 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

use Zend\Authentication\Adapter\AdapterInterface;

class My\Auth\Adapter implements AdapterInterface
{
    /**
     * Sets username and password for authentication
     *
     * @return void
     */
    public function __construct($username, $password)
    {
        // ...
    }

    /**
     * Performs an authentication attempt
     *
     * @return \Zend\Authentication\Result
     * @throws \Zend\Authentication\Adapter\Exception\ExceptionInterface
     *               If authentication cannot be performed
     */
    public function authenticate()
    {
        // ...
    }
}

As indicated in its docblock, authenticate() must return an instance of Zend\Authentication\Result (or of a class derived from Zend\Authentication\Result). If for some reason performing an authentication query is impossible, authenticate() should throw an exception that derives from Zend\Authentication\Adapter\Exception\ExceptionInterface.

Results¶

Zend\Authentication adapters return an instance of Zend\Authentication\Result with authenticate() in order to represent the results of an authentication attempt. Adapters populate the Zend\Authentication\Result object upon construction, so that the following four methods provide a basic set of user-facing operations that are common to the results of Zend\Authentication adapters:

• isValid()- returns TRUE if and only if the result represents a successful authentication attempt
• getCode()- returns a Zend\Authentication\Result constant identifier for determining the type of authentication failure or whether success has occurred. This may be used in situations where the developer wishes to distinguish among several authentication result types. This allows developers to maintain detailed authentication result statistics, for example. Another use of this feature is to provide specific, customized messages to users for usability reasons, though developers are encouraged to consider the risks of providing such detailed reasons to users, instead of a general authentication failure message. For more information, see the notes below.
• getIdentity()- returns the identity of the authentication attempt
• getMessages()- returns an array of messages regarding a failed authentication attempt

A developer may wish to branch based on the type of authentication result in order to perform more specific operations. Some operations developers might find useful are locking accounts after too many unsuccessful password attempts, flagging an IP address after too many nonexistent identities are attempted, and providing specific, customized authentication result messages to the user. The following result codes are available:

1
2
3
4
5
6
7
8

use Zend\Authentication\Result;

Result::SUCCESS
Result::FAILURE
Result::FAILURE_IDENTITY_NOT_FOUND
Result::FAILURE_IDENTITY_AMBIGUOUS
Result::FAILURE_CREDENTIAL_INVALID
Result::FAILURE_UNCATEGORIZED

The following example illustrates how a developer may branch on the result code:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21

// inside of AuthController / loginAction
$result = $this->_auth->authenticate($adapter);

switch ($result->getCode()) {

    case Zend_Auth_Result::FAILURE_IDENTITY_NOT_FOUND:
        /** do stuff for nonexistent identity **/
        break;

    case Zend_Auth_Result::FAILURE_CREDENTIAL_INVALID:
        /** do stuff for invalid credential **/
        break;

    case Zend_Auth_Result::SUCCESS:
        /** do stuff for successful authentication **/
        break;

    default:
        /** do stuff for other failure **/
        break;
}

Identity Persistence¶

Authenticating a request that includes authentication credentials is useful per se, but it is also important to support maintaining the authenticated identity without having to present the authentication credentials with each request.

HTTP is a stateless protocol, however, and techniques such as cookies and sessions have been developed in order to facilitate maintaining state across multiple requests in server-side web applications.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15

use Zend\Authentication\AuthenticationService;
use Zend\Authentication\Storage\Session as SessionStorage;

$auth = new AuthenticationService();

// Use 'someNamespace' instead of 'Zend_Auth'
$auth->setStorage(new SessionStorage('someNamespace'));

/**
 * @todo Set up the auth adapter, $authAdapter
 */

// Authenticate, saving the result, and persisting the identity on
// success
$result = $auth->authenticate($authAdapter);

 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
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67

use Zend\Authentication\Storage\StorageInterface;

class My\Storage implements StorageInterface
{
    /**
     * Returns true if and only if storage is empty
     *
     * @throws \Zend\Authentication\Exception\ExceptionInterface
     *               If it is impossible to
     *               determine whether storage is empty
     * @return boolean
     */
    public function isEmpty()
    {
        /**
         * @todo implementation
         */
    }

    /**
     * Returns the contents of storage
     *
     * Behavior is undefined when storage is empty.
     *
     * @throws \Zend\Authentication\Exception\ExceptionInterface
     *               If reading contents from storage is impossible
     * @return mixed
     */

    public function read()
    {
        /**
         * @todo implementation
         */
    }

    /**
     * Writes $contents to storage
     *
     * @param  mixed $contents
     * @throws \Zend\Authentication\Exception\ExceptionInterface
     *               If writing $contents to storage is impossible
     * @return void
     */

    public function write($contents)
    {
        /**
         * @todo implementation
         */
    }

    /**
     * Clears contents from storage
     *
     * @throws \Zend\Authentication\Exception\ExceptionInterface
     *               If clearing contents from storage is impossible
     * @return void
     */

    public function clear()
    {
        /**
         * @todo implementation
         */
    }
}

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14

use Zend\Authentication\AuthenticationService;

// Instruct AuthenticationService to use the custom storage class
$auth = new AuthenticationService();

$auth->setStorage(new My\Storage());

/**
 * @todo Set up the auth adapter, $authAdapter
 */

// Authenticate, saving the result, and persisting the identity on
// success
$result = $auth->authenticate($authAdapter);

Usage¶

There are two provided ways to use Zend\Authentication adapters:

. indirectly, through Zend\Authentication\AuthenticationService::authenticate()

. directly, through the adapter’s authenticate() method

The following example illustrates how to use a Zend\Authentication adapter indirectly, through the use of the Zend\Authentication\AuthenticationService class:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22

use Zend\Authentication\AuthenticationService;

// instantiate the authentication service
$auth = new AuthenticationService();

// Set up the authentication adapter
$authAdapter = new My\Auth\Adapter($username, $password);

// Attempt authentication, saving the result
$result = $auth->authenticate($authAdapter);

if (!$result->isValid()) {
    // Authentication failed; print the reasons why
    foreach ($result->getMessages() as $message) {
        echo "$message\n";
    }
} else {
    // Authentication succeeded; the identity ($username) is stored
    // in the session
    // $result->getIdentity() === $auth->getIdentity()
    // $result->getIdentity() === $username
}

Once authentication has been attempted in a request, as in the above example, it is a simple matter to check whether a successfully authenticated identity exists:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12

use Zend\Authentication\AuthenticationService;

$auth = new AuthenticationService();

/**
 * @todo Set up the auth adapter, $authAdapter
 */

if ($auth->hasIdentity()) {
    // Identity exists; get it
    $identity = $auth->getIdentity();
}

To remove an identity from persistent storage, simply use the clearIdentity() method. This typically would be used for implementing an application “logout” operation:

1

$auth->clearIdentity();

When the automatic use of persistent storage is inappropriate for a particular use case, a developer may simply bypass the use of the Zend\Authentication\AuthenticationService class, using an adapter class directly. Direct use of an adapter class involves configuring and preparing an adapter object and then calling its authenticate() method. Adapter-specific details are discussed in the documentation for each adapter. The following example directly utilizes My\Auth\Adapter:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15

// Set up the authentication adapter
$authAdapter = new My\Auth\Adapter($username, $password);

// Attempt authentication, saving the result
$result = $authAdapter->authenticate();

if (!$result->isValid()) {
    // Authentication failed; print the reasons why
    foreach ($result->getMessages() as $message) {
        echo "$message\n";
    }
} else {
    // Authentication succeeded
    // $result->getIdentity() === $username
}

Introduction¶

Zend\Authentication\Adapter\DbTable provides the ability to authenticate against credentials stored in a database table. Because Zend\Authentication\Adapter\DbTable requires an instance of Zend\Db\Adapter\Adapter to be passed to its constructor, each instance is bound to a particular database connection. Other configuration options may be set through the constructor and through instance methods, one for each option.

The available configuration options include:

• tableName: This is the name of the database table that contains the authentication credentials, and against which the database authentication query is performed.
• identityColumn: This is the name of the database table column used to represent the identity. The identity column must contain unique values, such as a username or e-mail address.
• credentialColumn: This is the name of the database table column used to represent the credential. Under a simple identity and password authentication scheme, the credential value corresponds to the password. See also the credentialTreatment option.
• credentialTreatment: In many cases, passwords and other sensitive data are encrypted, hashed, encoded, obscured, salted or otherwise treated through some function or algorithm. By specifying a parameterized treatment string with this method, such as ‘MD5(?)‘ or ‘PASSWORD(?)‘, a developer may apply such arbitrary SQL upon input credential data. Since these functions are specific to the underlying RDBMS, check the database manual for the availability of such functions for your database system.

Basic Usage

As explained in the introduction, the Zend\Authentication\Adapter\DbTable constructor requires an instance of Zend\Db\Adapter\Adapter that serves as the database connection to which the authentication adapter instance is bound. First, the database connection should be created.

The following code creates an adapter for an in-memory database, creates a simple table schema, and inserts a row against which we can perform an authentication query later. This example requires the PDO SQLite extension to be available:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24

use Zend\Db\Adapter\Adapter as DbAdapter;

// Create a SQLite database connection
$dbAdapter = new DbAdapter(array(
                'driver' => 'Pdo_Sqlite',
                'database' => 'path/to/sqlite.db'
            ));

// Build a simple table creation query
$sqlCreate = 'CREATE TABLE [users] ('
           . '[id] INTEGER  NOT NULL PRIMARY KEY, '
           . '[username] VARCHAR(50) UNIQUE NOT NULL, '
           . '[password] VARCHAR(32) NULL, '
           . '[real_name] VARCHAR(150) NULL)';

// Create the authentication credentials table
$dbAdapter->query($sqlCreate);

// Build a query to insert a row for which authentication may succeed
$sqlInsert = "INSERT INTO users (username, password, real_name) "
           . "VALUES ('my_username', 'my_password', 'My Real Name')";

// Insert the data
$dbAdapter->query($sqlInsert);

With the database connection and table data available, an instance of Zend\Authentication\Adapter\DbTable may be created. Configuration option values may be passed to the constructor or deferred as parameters to setter methods after instantiation:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17

use Zend\Authentication\Adapter\DbTable as AuthAdapter;

// Configure the instance with constructor parameters...
$authAdapter = new AuthAdapter($dbAdapter,
                               'users',
                               'username',
                               'password'
                               );

// ...or configure the instance with setter methods
$authAdapter = new AuthAdapter($dbAdapter);

$authAdapter
    ->setTableName('users')
    ->setIdentityColumn('username')
    ->setCredentialColumn('password')
;

At this point, the authentication adapter instance is ready to accept authentication queries. In order to formulate an authentication query, the input credential values are passed to the adapter prior to calling the authenticate() method:

1
2
3
4
5
6
7

// Set the input credential values (e.g., from a login form)
$authAdapter
    ->setIdentity('my_username')
    ->setCredential('my_password')
;

// Perform the authentication query, saving the result

In addition to the availability of the getIdentity() method upon the authentication result object, Zend\Authentication\Adapter\DbTable also supports retrieving the table row upon authentication success:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16

// Print the identity
echo $result->getIdentity() . "\n\n";

// Print the result row
print_r($authAdapter->getResultRowObject());

/* Output:
my_username

Array
(
    [id] => 1
    [username] => my_username
    [password] => my_password
    [real_name] => My Real Name
)

Since the table row contains the credential value, it is important to secure the values against unintended access.

Advanced Usage: Persisting a DbTable Result Object¶

By default, Zend\Authentication\Adapter\DbTable returns the identity supplied back to the auth object upon successful authentication. Another use case scenario, where developers want to store to the persistent storage mechanism of Zend\Authentication an identity object containing other useful information, is solved by using the getResultRowObject() method to return a stdClass object. The following code snippet illustrates its use:

 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

// authenticate with Zend\Authentication\Adapter\DbTable
$result = $this->_auth->authenticate($adapter);

if ($result->isValid()) {
    // store the identity as an object where only the username and
    // real_name have been returned
    $storage = $this->_auth->getStorage();
    $storage->write($adapter->getResultRowObject(array(
        'username',
        'real_name',
    )));

    // store the identity as an object where the password column has
    // been omitted
    $storage->write($adapter->getResultRowObject(
        null,
        'password'
    ));

    /* ... */

} else {

    /* ... */

}

Advanced Usage By Example¶

While the primary purpose of the Zend\Authentication component (and consequently Zend\Authentication\Adapter\DbTable) is primarily authentication and not authorization, there are a few instances and problems that toe the line between which domain they fit within. Depending on how you’ve decided to explain your problem, it sometimes makes sense to solve what could look like an authorization problem within the authentication adapter.

With that disclaimer out of the way, Zend\Authentication\Adapter\DbTable has some built in mechanisms that can be leveraged for additional checks at authentication time to solve some common user problems.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17

use Zend\Authentication\Adapter\DbTable as AuthAdapter;

// The status field value of an account is not equal to "compromised"
$adapter = new AuthAdapter($db,
                           'users',
                           'username',
                           'password',
                           'MD5(?) AND status != "compromised"'
                           );

// The active field value of an account is equal to "TRUE"
$adapter = new AuthAdapter($db,
                           'users',
                           'username',
                           'password',
                           'MD5(?) AND active = "TRUE"'
                           );

Another scenario can be the implementation of a salting mechanism. Salting is a term referring to a technique which can highly improve your application’s security. It’s based on the idea that concatenating a random string to every password makes it impossible to accomplish a successful brute force attack on the database using pre-computed hash values from a dictionary.

Therefore, we need to modify our table to store our salt string:

1
2
3

$sqlAlter = "ALTER TABLE [users] "
          . "ADD COLUMN [password_salt] "
          . "AFTER [password]";

Here’s a simple way to generate a salt string for every user at registration:

1
2

for ($i = 0; $i < 50; $i++) {
    $dynamicSalt .= chr(rand(33, 126));

And now let’s build the adapter:

1
2
3
4
5
6

$adapter = new AuthAdapter($db,
                           'users',
                           'username',
                           'password',
                           "MD5(CONCAT('staticSalt', ?, password_salt))"
                          );

Another alternative is to use the getDbSelect() method of the Zend\Authentication\Adapter\DbTable after the adapter has been constructed. This method will return the Zend\Db\Sql\Select object instance it will use to complete the authenticate() routine. It is important to note that this method will always return the same object regardless if authenticate() has been called or not. This object will not have any of the identity or credential information in it as those values are placed into the select object at authenticate() time.

An example of a situation where one might want to use the getDbSelect() method would check the status of a user, in other words to see if that user’s account is enabled.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14

// Continuing with the example from above
$adapter = new AuthAdapter($db,
                           'users',
                           'username',
                           'password',
                           'MD5(?)'
                           );

// get select object (by reference)
$select = $adapter->getDbSelect();
$select->where('active = "TRUE"');

// authenticate, this ensures that users.active = TRUE
$adapter->authenticate();

Introduction¶

Digest authentication is a method of HTTP authentication that improves upon Basic authentication by providing a way to authenticate without having to transmit the password in clear text across the network.

This adapter allows authentication against text files containing lines having the basic elements of Digest authentication:

• username, such as “joe.user“
• realm, such as “Administrative Area“
• MD5 hash of the username, realm, and password, separated by colons

The above elements are separated by colons, as in the following example (in which the password is “somePassword”):

1

someUser:Some Realm:fde17b91c3a510ecbaf7dbd37f59d4f8

Specifics¶

The digest authentication adapter, Zend\Authentication\Adapter\Digest, requires several input parameters:

• filename - Filename against which authentication queries are performed
• realm - Digest authentication realm
• username - Digest authentication user
• password - Password for the user of the realm

These parameters must be set prior to calling authenticate().

Identity¶

The digest authentication adapter returns a Zend\Authentication\Result object, which has been populated with the identity as an array having keys of realm and username. The respective array values associated with these keys correspond to the values set before authenticate() is called.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20

use Zend\Authentication\Adapter\Digest as AuthAdapter;

$adapter = new AuthAdapter($filename,
                           $realm,
                           $username,
                           $password);

$result = $adapter->authenticate();

$identity = $result->getIdentity();

print_r($identity);

/*
Array
(
    [realm] => Some Realm
    [username] => someUser
)
*/

Introduction¶

Zend\Authentication\Adapter\Http provides a mostly-compliant implementation of RFC-2617, Basic and Digest HTTP Authentication. Digest authentication is a method of HTTP authentication that improves upon Basic authentication by providing a way to authenticate without having to transmit the password in clear text across the network.

Major Features:

• Supports both Basic and Digest authentication.
• Issues challenges in all supported schemes, so client can respond with any scheme it supports.
• Supports proxy authentication.
• Includes support for authenticating against text files and provides an interface for authenticating against other sources, such as databases.

There are a few notable features of RFC-2617 that are not implemented yet:

• Nonce tracking, which would allow for “stale” support, and increased replay attack protection.
• Authentication with integrity checking, or “auth-int”.
• Authentication-Info HTTP header.

Design Overview¶

This adapter consists of two sub-components, the HTTP authentication class itself, and the so-called “Resolvers.” The HTTP authentication class encapsulates the logic for carrying out both Basic and Digest authentication. It uses a Resolver to look up a client’s identity in some data store (text file by default), and retrieve the credentials from the data store. The “resolved” credentials are then compared to the values submitted by the client to determine whether authentication is successful.

Configuration Options¶

The Zend\Authentication\Adapter\Http class requires a configuration array passed to its constructor. There are several configuration options available, and some are required:

Resolvers¶

The resolver’s job is to take a username and realm, and return some kind of credential value. Basic authentication expects to receive the Base64 encoded version of the user’s password. Digest authentication expects to receive a hash of the user’s username, the realm, and their password (each separated by colons). Currently, the only supported hash algorithm is MD5.

Zend\Authentication\Adapter\Http relies on objects implementing Zend\Authentication\Adapter\Http\ResolverInterface. A text file resolver class is included with this adapter, but any other kind of resolver can be created simply by implementing the resolver interface.

1

<username>:<realm>:<credentials>\n

1
2
3

use Zend\Authentication\Adapter\Http\FileResolver;
$path     = 'files/passwd.txt';
$resolver = new FileResolver($path);

1
2
3

$path     = 'files/passwd.txt';
$resolver = new FileResolver();
$resolver->setFile($path);

Basic Usage¶

First, set up an array with the required configuration values:

1
2
3
4
5
6

$config = array(
    'accept_schemes' => 'basic digest',
    'realm'          => 'My Web Site',
    'digest_domains' => '/members_only /my_account',
    'nonce_timeout'  => 3600,
);

This array will cause the adapter to accept either Basic or Digest authentication, and will require authenticated access to all the areas of the site under /members_only and /my_account. The realm value is usually displayed by the browser in the password dialog box. The nonce_timeout, of course, behaves as described above.

Next, create the Zend\Authentication\Adapter\Http object:

1

$adapter = new Zend\Authentication\Adapter\Http($config);

Since we’re supporting both Basic and Digest authentication, we need two different resolver objects. Note that this could just as easily be two different classes:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10

use Zend\Authentication\Adapter\Http\FileResolver;

$basicResolver = new FileResolver();
$basicResolver->setFile('files/basicPasswd.txt');

$digestResolver = new FileResolver();
$digestResolver->setFile('files/digestPasswd.txt');

$adapter->setBasicResolver($basicResolver);
$adapter->setDigestResolver($digestResolver);

Finally, we perform the authentication. The adapter needs a reference to both the Request and Response objects in order to do its job:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10

assert($request instanceof Zend\Http\Request);
assert($response instanceof Zend\Http\Response);

$adapter->setRequest($request);
$adapter->setResponse($response);

$result = $adapter->authenticate();
if (!$result->isValid()) {
    // Bad userame/password, or canceled password prompt
}

Introduction¶

Zend\Authentication\Adapter\Ldap supports web application authentication with LDAP services. Its features include username and domain name canonicalization, multi-domain authentication, and failover capabilities. It has been tested to work with Microsoft Active Directory and OpenLDAP, but it should also work with other LDAP service providers.

This documentation includes a guide on using Zend\Authentication\Adapter\Ldap, an exploration of its API, an outline of the various available options, diagnostic information for troubleshooting authentication problems, and example options for both Active Directory and OpenLDAP servers.

Usage¶

To incorporate Zend\Authentication\Adapter\Ldap authentication into your application quickly, even if you’re not using Zend\Mvc, the meat of your code should look something like the following:

 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
30
31
32
33
34
35
36
37
38
39
40
41
42
43

use Zend\Authentication\AuthenticationService;
use Zend\Authentication\Adapter\Ldap as AuthAdapter;
use Zend\Config\Reader\Ini as ConfigReader;
use Zend\Log\Logger;
use Zend\Log\Writer\Stream as LogWriter;
use Zend\Log\Filter\Priority as LogFilter;

$username = $this->_request->getParam('username');
$password = $this->_request->getParam('password');


$auth = new AuthenticationService();

$config = new ConfigReader('./ldap-config.ini','production');

$log_path = $config->ldap->log_path;
$options = $config->ldap->toArray();
unset($options['log_path']);

$adapter = new AuthAdapter($options,
                           $username,
                           $password);

$result = $auth->authenticate($adapter);

if ($log_path) {
    $messages = $result->getMessages();

    $logger = new Logger;
    $writer = new LogWriter($log_path);

    $logger->addWriter($writer);

    $filter = new LogFilter(Logger::DEBUG);
    $logger->addFilter($filter);

    foreach ($messages as $i => $message) {
        if ($i-- > 1) { // $messages[2] and up are log messages
            $message = str_replace("\n", "\n  ", $message);
            $logger->log("Ldap: $i: $message", Logger::DEBUG);
        }
    }
}

Of course, the logging code is optional, but it is highly recommended that you use a logger. Zend\Authentication\Adapter\Ldap will record just about every bit of information anyone could want in $messages (more below), which is a nice feature in itself for something that has a history of being notoriously difficult to debug.

The Zend\Config\Reader\Ini code is used above to load the adapter options. It is also optional. A regular array would work equally well. The following is an example ldap-config.ini file that has options for two separate servers. With multiple sets of server options the adapter will try each, in order, until the credentials are successfully authenticated. The names of the servers (e.g., ‘server1’ and ‘server2’) are largely arbitrary. For details regarding the options array, see the Server Options section below. Note that Zend\Config\Reader\Ini requires that any values with “equals” characters (=) will need to be quoted (like the DNs shown below).

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21

[production]

ldap.log_path = /tmp/ldap.log

; Typical options for OpenLDAP
ldap.server1.host = s0.foo.net
ldap.server1.accountDomainName = foo.net
ldap.server1.accountDomainNameShort = FOO
ldap.server1.accountCanonicalForm = 3
ldap.server1.username = "CN=user1,DC=foo,DC=net"
ldap.server1.password = pass1
ldap.server1.baseDn = "OU=Sales,DC=foo,DC=net"
ldap.server1.bindRequiresDn = true

; Typical options for Active Directory
ldap.server2.host = dc1.w.net
ldap.server2.useStartTls = true
ldap.server2.accountDomainName = w.net
ldap.server2.accountDomainNameShort = W
ldap.server2.accountCanonicalForm = 3
ldap.server2.baseDn = "CN=Users,DC=w,DC=net"

The above configuration will instruct Zend\Authentication\Adapter\Ldap to attempt to authenticate users with the OpenLDAP server s0.foo.net first. If the authentication fails for any reason, the AD server dc1.w.net will be tried.

With servers in different domains, this configuration illustrates multi-domain authentication. You can also have multiple servers in the same domain to provide redundancy.

Note that in this case, even though OpenLDAP has no need for the short NetBIOS style domain name used by Windows, we provide it here for name canonicalization purposes (described in the Username Canonicalization section below).

The API¶

The Zend\Authentication\Adapter\Ldap constructor accepts three parameters.

The $options parameter is required and must be an array containing one or more sets of options. Note that it is an array of arrays of Zend\Ldap\Ldap options. Even if you will be using only one LDAP server, the options must still be within another array.

Below is print_r() output of an example options parameter containing two sets of server options for LDAP servers s0.foo.net and dc1.w.net (the same options as the above INI representation):

 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

Array
(
    [server2] => Array
        (
            [host] => dc1.w.net
            [useStartTls] => 1
            [accountDomainName] => w.net
            [accountDomainNameShort] => W
            [accountCanonicalForm] => 3
            [baseDn] => CN=Users,DC=w,DC=net
        )

    [server1] => Array
        (
            [host] => s0.foo.net
            [accountDomainName] => foo.net
            [accountDomainNameShort] => FOO
            [accountCanonicalForm] => 3
            [username] => CN=user1,DC=foo,DC=net
            [password] => pass1
            [baseDn] => OU=Sales,DC=foo,DC=net
            [bindRequiresDn] => 1
        )

)

The information provided in each set of options above is different mainly because AD does not require a username be in DN form when binding (see the bindRequiresDn option in the Server Options section below), which means we can omit a number of options associated with retrieving the DN for a username being authenticated.

The names of servers (e.g. ‘server1’ and ‘server2’ shown above) are largely arbitrary, but for the sake of using Zend\Config\Reader\Ini, the identifiers should be present (as opposed to being numeric indexes) and should not contain any special characters used by the associated file formats (e.g. the ‘.‘INI property separator, ‘&‘ for XML entity references, etc).

With multiple sets of server options, the adapter can authenticate users in multiple domains and provide failover so that if one server is not available, another will be queried.

The username and password parameters of the Zend\Authentication\Adapter\Ldap constructor represent the credentials being authenticated (i.e., the credentials supplied by the user through your HTML login form). Alternatively, they may also be set with the setUsername() and setPassword() methods.

Server Options¶

Each set of server options in the context of ZendAuthenticationAdapterLdap consists of the following options, which are passed, largely unmodified, to Zend\Ldap\Ldap::setOptions():

Collecting Debugging Messages¶

Zend\Authentication\Adapter\Ldap collects debugging information within its authenticate() method. This information is stored in the Zend\Authentication\Result object as messages. The array returned by Zend\Authentication\Result::getMessages() is described as follows

In practice, index 0 should be displayed to the user (e.g., using the FlashMessenger helper), index 1 should be logged and, if debugging information is being collected, indexes 2 and higher could be logged as well (although the final message always includes the string from index 1).

Common Options for Specific Servers¶

Using Zend\Barcode\Barcode::factory¶

Zend_Barcode uses a factory method to create an instance of a renderer that extends Zend\Barcode\Renderer\AbstractRenderer. The factory method accepts five arguments.

. The name of the barcode format (e.g., “code39”) or a Traversable object (required)

. The name of the renderer (e.g., “image”) (required)

. Options to pass to the barcode object (an array or a Traversable object) (optional)

. Options to pass to the renderer object (an array or a Traversable object) (optional)

. Boolean to indicate whether or not to automatically render errors. If an exception occurs, the provided barcode

object will be replaced with an Error representation (optional default TRUE)

Getting a Renderer with Zend\Barcode\Barcode::factory()

Zend\Barcode\Barcode::factory() instantiates barcode objects and renderers and ties them together. In this first example, we will use the Code39 barcode type together with the Image renderer.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10

use Zend\Barcode;

// Only the text to draw is required
$barcodeOptions = array('text' => 'ZEND-FRAMEWORK');

// No required options
$rendererOptions = array();
$renderer = Barcode::factory(
    'code39', 'image', $barcodeOptions, $rendererOptions
);

Using Zend\Barcode\Barcode::factory() with Zend\Config\Config objects

You may pass a Zend\Config\Config object to the factory in order to create the necessary objects. The following example is functionally equivalent to the previous.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12

use Zend\Config;
use Zend\Barcode;

// Using only one Zend\Config\Config object
$config = new Config(array(
    'barcode'        => 'code39',
    'barcodeParams'  => array('text' => 'ZEND-FRAMEWORK'),
    'renderer'       => 'image',
    'rendererParams' => array('imageType' => 'gif'),
));

$renderer = Barcode::factory($config);

Drawing a barcode¶

When you draw the barcode, you retrieve the resource in which the barcode is drawn. To draw a barcode, you can call the draw() of the renderer, or simply use the proxy method provided by Zend\Barcode\Barcode.

Drawing a barcode with the renderer object

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12

use Zend\Barcode;

// Only the text to draw is required
$barcodeOptions = array('text' => 'ZEND-FRAMEWORK');

// No required options
$rendererOptions = array();

// Draw the barcode in a new image,
$imageResource = Barcode::factory(
    'code39', 'image', $barcodeOptions, $rendererOptions
)->draw();

Drawing a barcode with Zend\Barcode\Barcode::draw()

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12

use Zend\Barcode;

// Only the text to draw is required
$barcodeOptions = array('text' => 'ZEND-FRAMEWORK');

// No required options
$rendererOptions = array();

// Draw the barcode in a new image,
$imageResource = Barcode::draw(
    'code39', 'image', $barcodeOptions, $rendererOptions
);

Renderering a barcode¶

When you render a barcode, you draw the barcode, you send the headers and you send the resource (e.g. to a browser). To render a barcode, you can call the render() method of the renderer or simply use the proxy method provided by Zend\Barcode\Barcode.

Renderering a barcode with the renderer object

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13

use Zend\Barcode;

// Only the text to draw is required
$barcodeOptions = array('text' => 'ZEND-FRAMEWORK');

// No required options
$rendererOptions = array();

// Draw the barcode in a new image,
// send the headers and the image
Barcode::factory(
    'code39', 'image', $barcodeOptions, $rendererOptions
)->render();

This will generate this barcode:

Renderering a barcode with Zend\Barcode\Barcode::render()

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13

use Zend\Barcode;

// Only the text to draw is required
$barcodeOptions = array('text' => 'ZEND-FRAMEWORK');

// No required options
$rendererOptions = array();

// Draw the barcode in a new image,
// send the headers and the image
Barcode::render(
    'code39', 'image', $barcodeOptions, $rendererOptions
);

This will generate the same barcode as the previous example.

Common Options¶

In the following list, the values have no units; we will use the term “unit.” For example, the default value of the “thin bar” is “1 unit”. The real units depend on the rendering support (see the renderers documentation for more information). Setters are each named by uppercasing the initial letter of the option and prefixing the name with “set” (e.g. “barHeight” becomes “setBarHeight”). All options have a corresponding getter prefixed with “get” (e.g. “getBarHeight”). Available options are:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21

use Zend\Barcode;

// In your bootstrap:
Barcode::setBarcodeFont('my_font.ttf');

// Later in your code:
Barcode::render(
    'code39',
    'pdf',
    array('text' => 'ZEND-FRAMEWORK')
); // will use 'my_font.ttf'

// or:
Barcode::render(
    'code39',
    'image',
    array(
        'text' => 'ZEND-FRAMEWORK',
        'font' => 3
    )
); // will use the 3rd GD internal font

Common Additional Getters¶

Zend\Barcode\Object\Error¶

This barcode is a special case. It is internally used to automatically render an exception caught by the Zend\Barcode component.

Zend\Barcode\Object\Code128¶

• Name: Code 128
• Allowed characters: the complete ASCII-character set
• Checksum: optional (modulo 103)
• Length: variable

There are no particular options for this barcode.

Zend\Barcode\Object\Codabar¶

• Name: Codabar (or Code 2 of 7)
• Allowed characters:‘0123456789-$:/.+’ with ‘ABCD’ as start and stop characters
• Checksum: none
• Length: variable

There are no particular options for this barcode.

Zend\Barcode\Object\Code25¶

• Name: Code 25 (or Code 2 of 5 or Code 25 Industrial)
• Allowed characters:‘0123456789’
• Checksum: optional (modulo 10)
• Length: variable

There are no particular options for this barcode.

Zend\Barcode\Object\Code25interleaved¶

This barcode extends Zend\Barcode\Object\Code25 (Code 2 of 5), and has the same particulars and options, and adds the following:

• Name: Code 2 of 5 Interleaved
• Allowed characters:‘0123456789’
• Checksum: optional (modulo 10)
• Length: variable (always even number of characters)

Available options include:

Zend\Barcode\Object\Ean2¶

This barcode extends Zend\Barcode\Object\Ean5 (EAN 5), and has the same particulars and options, and adds the following:

• Name: EAN-2
• Allowed characters:‘0123456789’
• Checksum: only use internally but not displayed
• Length: 2 characters

There are no particular options for this barcode.

Zend\Barcode\Object\Ean5¶

This barcode extends Zend\Barcode\Object\Ean13 (EAN 13), and has the same particulars and options, and adds the following:

• Name: EAN-5
• Allowed characters:‘0123456789’
• Checksum: only use internally but not displayed
• Length: 5 characters

There are no particular options for this barcode.

Zend\Barcode\Object\Ean8¶

This barcode extends Zend\Barcode\Object\Ean13 (EAN 13), and has the same particulars and options, and adds the following:

• Name: EAN-8
• Allowed characters:‘0123456789’
• Checksum: mandatory (modulo 10)
• Length: 8 characters (including checksum)

There are no particular options for this barcode.

Zend\Barcode\Object\Ean13¶

• Name: EAN-13
• Allowed characters:‘0123456789’
• Checksum: mandatory (modulo 10)
• Length: 13 characters (including checksum)

There are no particular options for this barcode.

Zend\Barcode\Object\Code39¶

• Name: Code 39
• Allowed characters:‘0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZ -.$/+%’
• Checksum: optional (modulo 43)
• Length: variable

There are no particular options for this barcode.

Zend\Barcode\Object\Identcode¶

This barcode extends Zend\Barcode\Object\Code25interleaved (Code 2 of 5 Interleaved), and inherits some of its capabilities; it also has a few particulars of its own.

• Name: Identcode (Deutsche Post Identcode)
• Allowed characters:‘0123456789’
• Checksum: mandatory (modulo 10 different from Code25)
• Length: 12 characters (including checksum)

There are no particular options for this barcode.

Zend\Barcode\Object\Itf14¶

This barcode extends Zend\Barcode\Object\Code25interleaved (Code 2 of 5 Interleaved), and inherits some of its capabilities; it also has a few particulars of its own.

• Name: ITF-14
• Allowed characters:‘0123456789’
• Checksum: mandatory (modulo 10)
• Length: 14 characters (including checksum)

There are no particular options for this barcode.

Zend\Barcode\Object\Leitcode¶

This barcode extends Zend\Barcode\Object\Identcode (Deutsche Post Identcode), and inherits some of its capabilities; it also has a few particulars of its own.

• Name: Leitcode (Deutsche Post Leitcode)
• Allowed characters:‘0123456789’
• Checksum: mandatory (modulo 10 different from Code25)
• Length: 14 characters (including checksum)

There are no particular options for this barcode.

Zend\Barcode\Object\Planet¶

• Name: Planet (PostaL Alpha Numeric Encoding Technique)
• Allowed characters:‘0123456789’
• Checksum: mandatory (modulo 10)
• Length: 12 or 14 characters (including checksum)

There are no particular options for this barcode.

Zend\Barcode\Object\Postnet¶

• Name: Postnet (POSTal Numeric Encoding Technique)
• Allowed characters:‘0123456789’
• Checksum: mandatory (modulo 10)
• Length: 6, 7, 10 or 12 characters (including checksum)

There are no particular options for this barcode.

Zend\Barcode\Object\Royalmail¶

• Name: Royal Mail or RM4SCC (Royal Mail 4-State Customer Code)
• Allowed characters:‘0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZ’
• Checksum: mandatory
• Length: variable

There are no particular options for this barcode.

Zend\Barcode\Object\Upca¶

This barcode extends Zend\Barcode\Object\Ean13 (EAN-13), and inherits some of its capabilities; it also has a few particulars of its own.

• Name: UPC-A (Universal Product Code)
• Allowed characters:‘0123456789’
• Checksum: mandatory (modulo 10)
• Length: 12 characters (including checksum)

There are no particular options for this barcode.

Zend\Barcode\Object\Upce¶

This barcode extends Zend\Barcode\Object\Upca (UPC-A), and inherits some of its capabilities; it also has a few particulars of its own. The first character of the text to encode is the system (0 or 1).

• Name: UPC-E (Universal Product Code)
• Allowed characters:‘0123456789’
• Checksum: mandatory (modulo 10)
• Length: 8 characters (including checksum)

There are no particular options for this barcode.

Common Options¶

In the following list, the values have no unit; we will use the term “unit.” For example, the default value of the “thin bar” is “1 unit.” The real units depend on the rendering support. The individual setters are obtained by uppercasing the initial letter of the option and prefixing the name with “set” (e.g. “barHeight” => “setBarHeight”). All options have a correspondant getter prefixed with “get” (e.g. “getBarHeight”). Available options are:

An additional getter exists: getType(). It returns the name of the renderer class without the namespace (e.g. Zend\Barcode\Renderer\Image returns “image”).

Zend\Barcode\Renderer\Image¶

The Image renderer will draw the instruction list of the barcode object in an image resource. The component requires the GD extension. The default width of a module is 1 pixel.

Available options are:

Zend\Barcode\Renderer\Pdf¶

The PDF renderer will draw the instruction list of the barcode object in a PDF document. The default width of a module is 0.5 point.

There are no particular options for this renderer.

The Zend_Cache Factory Method¶

A good way to build a usable instance of a Zend_Cache Frontend is given in the following example :

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18

// We choose a backend (for example 'File' or 'Sqlite'...)
$backendName = '[...]';

// We choose a frontend (for example 'Core', 'Output', 'Page'...)
$frontendName = '[...]';

// We set an array of options for the chosen frontend
$frontendOptions = array([...]);

// We set an array of options for the chosen backend
$backendOptions = array([...]);

// We create an instance of Zend_Cache
// (of course, the two last arguments are optional)
$cache = Zend_Cache::factory($frontendName,
                             $backendName,
                             $frontendOptions,
                             $backendOptions);

In the following examples we will assume that the $cache variable holds a valid, instantiated frontend as shown and that you understand how to pass parameters to your chosen backends.

Tagging Records¶

Tags are a way to categorize cache records. When you save a cache with the save() method, you can set an array of tags to apply for this record. Then you will be able to clean all cache records tagged with a given tag (or tags):

1

$cache->save($huge_data, 'myUniqueID', array('tagA', 'tagB', 'tagC'));

Cleaning the Cache¶

To remove or invalidate in particular cache id, you can use the remove() method :

1

$cache->remove('idToRemove');

To remove or invalidate several cache ids in one operation, you can use the clean() method. For example to remove all cache records :

1
2
3
4
5

// clean all records
$cache->clean(Zend_Cache::CLEANING_MODE_ALL);

// clean only outdated
$cache->clean(Zend_Cache::CLEANING_MODE_OLD);

If you want to remove cache entries matching the tags ‘tagA’ and ‘tagC’:

1
2
3
4

$cache->clean(
    Zend_Cache::CLEANING_MODE_MATCHING_TAG,
    array('tagA', 'tagC')
);

If you want to remove cache entries not matching the tags ‘tagA’ or ‘tagC’:

1
2
3
4

$cache->clean(
    Zend_Cache::CLEANING_MODE_NOT_MATCHING_TAG,
    array('tagA', 'tagC')
);

If you want to remove cache entries matching the tags ‘tagA’ or ‘tagC’:

1
2
3
4

$cache->clean(
    Zend_Cache::CLEANING_MODE_MATCHING_ANY_TAG,
    array('tagA', 'tagC')
);

Available cleaning modes are: CLEANING_MODE_ALL, CLEANING_MODE_OLD, CLEANING_MODE_MATCHING_TAG, CLEANING_MODE_NOT_MATCHING_TAG and CLEANING_MODE_MATCHING_ANY_TAG. The latter are, as their names suggest, combined with an array of tags in cleaning operations.

Zend_Cache_Core¶

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17

// we assume you already have $cache

$id = 'myBigLoop'; // cache id of "what we want to cache"

if (!($data = $cache->load($id))) {
    // cache miss

    $data = '';
    for ($i = 0; $i < 10000; $i++) {
        $data = $data . $i;
    }

    $cache->save($data);

}

// [...] do something with $data (echo it, pass it on etc.)

 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
30
31
32
33
34

// make sure you use unique identifiers:
$id1 = 'foo';
$id2 = 'bar';

// block 1
if (!($data = $cache->load($id1))) {
    // cache missed

    $data = '';
    for ($i=0;$i<10000;$i++) {
        $data = $data . $i;
    }

    $cache->save($data);

}
echo($data);

// this isn't affected by caching
echo('NEVER CACHED! ');

// block 2
if (!($data = $cache->load($id2))) {
    // cache missed

    $data = '';
    for ($i=0;$i<10000;$i++) {
        $data = $data . '!';
    }

    $cache->save($data);

}
echo($data);

 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
30
31
32
33
34

// the compact construction
// (not good if you cache empty strings and/or booleans)
if (!($data = $cache->load($id))) {

    // cache missed

    // [...] we make $data

    $cache->save($data);

}

// we do something with $data

// [...]

// the complete construction (works in any case)
if (!($cache->test($id))) {

    // cache missed

    // [...] we make $data

    $cache->save($data);

} else {

    // cache hit

    $data = $cache->load($id);

}

// we do something with $data

Zend_Cache_Frontend_Output¶

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12

// if it is a cache miss, output buffering is triggered
if (!($cache->start('mypage'))) {

    // output everything as usual
    echo 'Hello world! ';
    echo 'This is cached ('.time().') ';

    $cache->end(); // output buffering ends

}

echo 'This is never cached ('.time().').';

Zend_Cache_Frontend_Function¶

1
2
3
4
5
6

$cache->call('veryExpensiveFunc', $params);

// $params is an array
// For example to call veryExpensiveFunc(1, 'foo', 'bar') with
// caching, you can use
// $cache->call('veryExpensiveFunc', array(1, 'foo', 'bar'))

Zend_Cache_Frontend_Class¶

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18

class Test {

    // Static method
    public static function foobar($param1, $param2) {
        echo "foobar_output($param1, $param2)";
        return "foobar_return($param1, $param2)";
    }

}

// [...]
$frontendOptions = array(
    'cached_entity' => 'Test' // The name of the class
);
// [...]

// The cached call
$result = $cache->foobar('1', '2');

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20

class Test {

    private $_string = 'hello !';

    public function foobar2($param1, $param2) {
        echo($this->_string);
        echo "foobar2_output($param1, $param2)";
        return "foobar2_return($param1, $param2)";
    }

}

// [...]
$frontendOptions = array(
    'cached_entity' => new Test() // An instance of the class
);
// [...]

// The cached call
$result = $cache->foobar2('1', '2');

Zend_Cache_Frontend_File¶

Zend_Cache_Frontend_Page¶

1
2
3
4
5
6
7

// [...] // require, configuration and factory

$cache->start();
// if the cache is hit, the result is sent to the browser
// and the script stop here

// rest of the page ...

 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
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48

/*
 * You should avoid putting too many lines before the cache section.
 * For example, for optimal performances, "require_once" or
 * "Zend_Loader::loadClass" should be after the cache section.
 */

$frontendOptions = array(
   'lifetime' => 7200,
   'debug_header' => true, // for debugging
   'regexps' => array(
       // cache the whole IndexController
       '^/$' => array('cache' => true),

       // cache the whole IndexController
       '^/index/' => array('cache' => true),

       // we don't cache the ArticleController...
       '^/article/' => array('cache' => false),

       // ... but we cache the "view" action of this ArticleController
       '^/article/view/' => array(
           'cache' => true,

           // and we cache even there are some variables in $_POST
           'cache_with_post_variables' => true,

           // but the cache will be dependent on the $_POST array
           'make_id_with_post_variables' => true
       )
   )
);

$backendOptions = array(
    'cache_dir' => '/tmp/'
);

// getting a Zend_Cache_Frontend_Page object
$cache = Zend_Cache::factory('Page',
                             'File',
                             $frontendOptions,
                             $backendOptions);

$cache->start();
// if the cache is hit, the result is sent to the browser and the
// script stop here

// [...] the end of the bootstrap file
// these lines won't be executed if the cache is hit

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12

// [...] // require, configuration and factory

$cache->start();

// [...]

if ($someTest) {
    $cache->cancel();
    // [...]
}

// [...]

Zend_Cache_Frontend_Capture¶

Overview¶

Storage adapters are wrappers for real storage resources such as memory and the filesystem, using the well known adapter pattern.

They comes with tons of methods to read, write and modify stored items and to get information about stored items and the storage.

All adapters implements the interface Zend\Cache\Storage\Adapter and most extend Zend\Cache\Storage\Adapter\AbstractAdapter, which comes with basic logic.

Configuration is handled by either Zend\Cache\Storage\Adapter\AdapterOptions, or an adapter-specific options class if it exists. You may pass the options instance to the class at instantiation or via the setOptions() method, or alternately pass an associative array of options in either place (internally, these are then passed to an options class instance). Alternately, you can pass either the options instance or associative array to the Zend\Cache\StorageFactory::factory method.

Quick Start¶

Caching adapters can either be created from the provided Zend\Cache\StorageFactory factory, or by simply instantiating one of the Zend\Cache\Storage\Adapter\*classes.

To make life easier, the Zend\Cache\StorageFactory comes with a factory method to create an adapter and create/add all requested plugins at once.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23

use Zend\Cache\StorageFactory;

// Via factory:
$cache = StorageFactory::factory(array(
    'adapter' => 'apc',
    'plugins' => array(
        'exception_handler' => array('throw_exceptions' => false),
    ),
));

// Alternately:
$cache  = StorageFactory::adapterFactory('apc');
$plugin = StorageFactory::pluginFactory('exception_handler', array(
    'throw_exceptions' => false,
));
$cache->addPlugin($plugin);

// Or manually:
$cache  = new Zend\Cache\Storage\Adapter\Apc();
$plugin = new Zend\Cache\Storage\Plugin\ExceptionHandler(array(
    'throw_exceptions' => false,
));
$cache->addPlugin($plugin);

Configuration Options¶

ignore_missing_items

Enables or disables ignoring of missing items.

If enabled and a missing item was requested:

• getItem, getMetadata: return false
• removeItem[s]: return true
• incrementItem[s], decrementItem[s]: add a new item with 0 as base
• touchItem[s]: add new empty item

If disabled and a missing item was requested:

• getItem, getMetadata, incrementItem[s], decrementItem[s], touchItem[s]
• setIgnoreMissingItems(boolean $flag) Implements a fluent interface.
• getIgnoreMissingItems() Returns boolean

key_pattern

Pattern against which to validate cache keys.

• setKeyPattern(null|string $pattern) Implements a fluent interface.
• getKeyPattern() Returns string

namespace

The “namespace” in which cache items will live.

• setNamespace(string $namespace) Implements a fluent interface.
• getNamespace() Returns string

namespace_pattern

Pattern against which to validate namespace values.

• setNamespacePattern(null|string $pattern) Implements a fluent interface.
• getNamespacePattern() Returns string

readable

Enable/Disable reading data from cache.

• setReadable(boolean $flag) Implements a fluent interface.
• getReadable() Returns boolean

ttl

Set time to live.

• setTtl(int|float $ttl) Implements a fluent interface.
• getTtl() Returns float

writable

Enable/Disable writing data to cache.

• setWritable(boolean $flag) Implements a fluent interface.
• getWritable() Returns boolean

Available Methods¶

setOptions

setOptions(array|Traversable|Zend\Cache\Storage\Adapter\AdapterOptions $options)

Set options.

Implements a fluent interface.

getOptions

getOptions()

Get options

Returns Zend\Cache\Storage\Adapter\AdapterOptions

getItem

getItem(string $key, array $options = array ())

Get an item.

Returns mixed

getItems

getItems(array $keys, array $options = array ())

Get multiple items.

Returns array

hasItem

hasItem(string $key, array $options = array ())

Test if an item exists.

Returns boolean

hasItems

hasItems(array $keys, array $options = array ())

Test multiple items.

Returns array

getMetadata

getMetadata(string $key, array $options = array ())

Get metadata of an item.

Returns array|boolean

getMetadatas

getMetadatas(array $keys, array $options = array ())

Get multiple metadata

Returns array

setItem

setItem(string $key, mixed $value, array $options = array ())

Store an item.

Returns boolean

setItems

setItems(array $keyValuePairs, array $options = array ())

Store multiple items.

Returns boolean

addItem

addItem(string $key, mixed $value, array $options = array ())

Add an item.

Returns boolean

addItems

addItems(array $keyValuePairs, array $options = array ())

Add multiple items.

Returns boolean

replaceItem

replaceItem(string $key, mixed $value, array $options = array ())

Replace an item.

Returns boolean

replaceItems

replaceItems(array $keyValuePairs, array $options = array ())

Replace multiple items.

Returns boolean

checkAndSetItem

checkAndSetItem(mixed $token, string|null $key, mixed $value, array $options = array ())

Set item only if token matches

It uses the token from received from getItem() to check if the item has changed before overwriting it.

Returns boolean

touchItem

touchItem(string $key, array $options = array ())

Reset lifetime of an item

Returns boolean

touchItems

touchItems(array $keys, array $options = array ())

Reset lifetime of multiple items.

Returns boolean

removeItem

removeItem(string $key, array $options = array ())

Remove an item.

Returns boolean

removeItems

removeItems(array $keys, array $options = array ())

Remove multiple items.

Returns boolean

incrementItem

incrementItem(string $key, int $value, array $options = array ())

Increment an item.

Returns int|boolean

incrementItems

incrementItems(array $keyValuePairs, array $options = array ())

Increment multiple items.

Returns boolean

decrementItem

decrementItem(string $key, int $value, array $options = array ())

Decrement an item.

Returns int|boolean

decrementItems

decrementItems(array $keyValuePairs, array $options = array ())

Decrement multiple items.

Returns boolean

getDelayed

getDelayed(array $keys, array $options = array ())

Request multiple items.

Returns boolean

find

find(int $mode = 2, array $options = array ())

Find items.

Returns boolean

fetch

fetch()

Fetches the next item from result set

Returns array|boolean

fetchAll

fetchAll()

Returns all items of result set.

Returns array

clear

clear(int $mode = 1, array $options = array ())

Clear items off all namespaces.

Returns boolean

clearByNamespace

clearByNamespace(int $mode = 1, array $options = array ())

Clear items by namespace.

Returns boolean

optimize

optimize(array $options = array ())

Optimize adapter storage.

Returns boolean

getCapabilities

getCapabilities()

Capabilities of this storage

Returns Zend\Cache\Storage\Capabilities

getCapacity

getCapacity(array $options = array ())

Get storage capacity.

Returns array|boolean

TODO: Examples¶

Overview¶

Storage capabilities describes how a storage adapter works and which features it supports.

To get capabilities of a storage adapter, you can use the method getCapabilities() of the storage adapter but only the storage adapter and its plugins have permissions to change them.

Because capabilities are mutable, for example, by changing some options, you can subscribe to the “change” event to get notifications; see the examples for details.

If you are writing your own plugin or adapter, you can also change capabilities because you have access to the marker object and can create your own marker to instantiate a new object of Zend\Cache\Storage\Capabilities.

Available Methods¶

__construct

__construct(stdClass $marker, array $capabilities = array ( ), null|Zend\Cache\Storage\Capabilities $baseCapabilities)

Returns void

hasEventManager

hasEventManager()

Returns if the dependency of Zend\EventManager is available.

Returns boolean

getEventManager

getEventManager()

Get the event manager

Returns Zend\EventManager\EventCollection instance.

getSupportedDatatypes

getSupportedDatatypes()

Get supported datatypes.

Returns array.

setSupportedDatatypes

setSupportedDatatypes(stdClass $marker, array $datatypes)

Set supported datatypes.

Implements a fluent interface.

getSupportedMetadata

getSupportedMetadata()

Get supported metadata.

Returns array.

setSupportedMetadata

setSupportedMetadata(stdClass $marker, string $metadata)

Set supported metadata

Implements a fluent interface.

getMaxTtl

getMaxTtl()

Get maximum supported time-to-live

Returns int

setMaxTtl

setMaxTtl(stdClass $marker, int $maxTtl)

Set maximum supported time-to-live

Implements a fluent interface.

getStaticTtl

getStaticTtl()

Is the time-to-live handled static (on write), or dynamic (on read).

Returns boolean

setStaticTtl

setStaticTtl(stdClass $marker, boolean $flag)

Set if the time-to-live is handled statically (on write) or dynamically (on read)

Implements a fluent interface.

getTtlPrecision

getTtlPrecision()

Get time-to-live precision.

Returns float.

setTtlPrecision

setTtlPrecision(stdClass $marker, float $ttlPrecision)

Set time-to-live precision.

Implements a fluent interface.

getUseRequestTime

getUseRequestTime()

Get the “use request time” flag status

Returns boolean

setUseRequestTime

setUseRequestTime(stdClass $marker, boolean $flag)

Set the “use request time” flag.

Implements a fluent interface.

getExpiredRead

getExpiredRead()

Get flag indicating if expired items are readable.

Returns boolean

setExpiredRead

setExpiredRead(stdClass $marker, boolean $flag)

Set if expired items are readable.

Implements a fluent interface.

getMaxKeyLength

getMaxKeyLength()

Get maximum key lenth.

Returns int

setMaxKeyLength

setMaxKeyLength(stdClass $marker, int $maxKeyLength)

Set maximum key lenth.

Implements a fluent interface.

getNamespaceIsPrefix

getNamespaceIsPrefix()

Get if namespace support is implemented as a key prefix.

Returns boolean

setNamespaceIsPrefix

setNamespaceIsPrefix(stdClass $marker, boolean $flag)

Set if namespace support is implemented as a key prefix.

Implements a fluent interface.

getNamespaceSeparator

getNamespaceSeparator()

Get namespace separator if namespace is implemented as a key prefix.

Returns string

setNamespaceSeparator

setNamespaceSeparator(stdClass $marker, string $separator)

Set the namespace separator if namespace is implemented as a key prefix.

Implements a fluent interface.

getIterable

getIterable()

Get if items are iterable.

Returns boolean

setIterable

setIterable(stdClass $marker, boolean $flag)

Set if items are iterable.

Implements a fluent interface.

getClearAllNamespaces

getClearAllNamespaces()

Get flag indicating support to clear items of all namespaces.

Returns boolean

setClearAllNamespaces

setClearAllNamespaces(stdClass $marker, boolean $flag)

Set flag indicating support to clear items of all namespaces.

Implements a fluent interface.

getClearByNamespace

getClearByNamespace()

Get flag indicating support to clear items by namespace.

Returns boolean

setClearByNamespace

setClearByNamespace(stdClass $marker, boolean $flag)

Set flag indicating support to clear items by namespace.

Implements a fluent interface.

Examples¶

Get storage capabilities and do specific stuff in base of it

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14

use Zend\Cache\StorageFactory;

$cache = StorageFactory::adapterFactory('filesystem');
$capabilities = $cache->getCapabilities();

// now you can run specific stuff in base of supported feature
if ($capabilities->getIterable()) {
    $cache->find();
    while ( ($item => $cache->fetch()) ) {
        echo $item['key'] . ': ' . $item['value'] . "\n";
    }
} else {
    echo 'Iterating cached items not supported.';
}

Listen to change event

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19

use Zend\Cache\StorageFactory;

$cache = StorageFactory::adapterFactory('filesystem', array(
    'no_atime' => false,
));
$capabilities = $cache->getCapabilities();

// Catching the change event
$capabilities->getEventManager()->attach('change', function() {
    echo 'Capabilities changed';
});

// change option which changes capabilities
$cache->getOptions()->setNoATime(true);

/*
 * Will output:
 * "Capabilities changed"
 */

Overview¶

Cache storage plugins are objects to add missing functionality or to influence behavior of a storage adapter.

The plugins listen to events the adapter triggers and can change called method arguments (*.post - events), skipping and directly return a result (using stopPropagation), changing the result (with setResult of Zend\Cache\Storage\PostEvent) and catching exceptions (with Zend\Cache\Storage\ExceptionEvent).

Quick Start¶

Storage plugins can either be created from Zend\Cache\StorageFactory with the pluginFactory, or by simply instantiating one of the Zend\Cache\Storage\Plugin\*classes.

To make life easier, the Zend\Cache\StorageFactory comes with the method factory to create an adapter and all given plugins at once.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17

use Zend\Cache\StorageFactory;

// Via factory:
$cache = StorageFactory::factory(array(
    'adapter' => 'filesystem',
    'plugins' => array('serializer'),
));

// Alternately:
$cache  = StorageFactory::adapterFactory('filesystem');
$plugin = StorageFactory::pluginFactory('serializer');
$cache->addPlugin($plugin);

// Or manually:
$cache  = new Zend\Cache\Storage\Adapter\Filesystem();
$plugin = new Zend\Cache\Storage\Plugin\Serializer();
$cache->addPlugin($plugin);