# Using the Registry

A registry is a container for storing objects and values in the application space. By storing the value in a registry, the same object is always available throughout your application. This mechanism is an alternative to using global storage.

The typical method to use registries with Zend Framework is through static methods in the `Zend_Registry` class. Alternatively, the registry can be used as an array object, so you can access elements stored within it with a convenient array-like interface.

## Setting Values in the Registry

Use the static method `set()` to store an entry in the registry.

### Example of set() Method Usage

    Zend_Registry::set('index', $value);

The value returned can be an object, an array, or a scalar. You can change the value stored in a specific entry of the registry by calling the `set()` method to set the entry to a new value.

The index can be a scalar (`NULL`, string, or number), like an ordinary array.

## Getting Values from the Registry

To retrieve an entry from the registry, use the static `get()` method.

### Example of get() Method Usage

    $value = Zend_Registry::get('index');

The `getInstance()` method returns the singleton registry object. This registry object is iterable, making all values stored in the registry easily accessible.

### Example of Iterating over the Registry

    $registry = Zend_Registry::getInstance();

    foreach ($registry as $index => $value) {
        echo "Registry index $index contains:\n";
        var_dump($value);
    }

## Constructing a Registry Object

In addition to accessing the static registry via static methods, you can create an instance directly and use it as an object.

The registry instance you access through the static methods is simply one such instance. It is for convenience that it is stored statically, so that it is accessible from anywhere in an application.

Use the traditional new operator to instantiate `Zend_Registry`. Instantiating `Zend_Registry` using its constructor also makes initializing the entries in the registry simple by taking an associative array as an argument.

### Example of Constructing a Registry

    $registry = new Zend_Registry(array('index' => $value));

Once such a `Zend_Registry` object is instantiated, you can use it by calling any array object method or by setting it as the singleton instance for `Zend_Registry` with the static method `setInstance()`.

### Example of Initializing the Singleton Registry

    $registry = new Zend_Registry(array('index' => $value));

    Zend_Registry::setInstance($registry);

The `setInstance()` method throws a `Zend_Exception` if the static registry has already been initialized.

## Accessing the Registry as an Array

If you have several values to get or set, you may find it convenient to access the registry with array notation.

### Example of Array Access

    $registry = Zend_Registry::getInstance();

    $registry['index'] = $value;

    var_dump( $registry['index'] );

## Accessing the Registry as an Object

You may also find it convenient to access the registry in an object-oriented fashion by using index names as object properties. You must specifically construct the registry object using the `ArrayObject::ARRAY_AS_PROPS` option and initialize the static instance to enable this functionality.

You must set the `ArrayObject::ARRAY_AS_PROPS` option before the static registry has been accessed for the first time.

### Known Issues with the ArrayObject::ARRAY_AS_PROPS Option

Some versions of PHP have proven very buggy when using the registry with the `ArrayObject::ARRAY_AS_PROPS` option.

### Example of Object Access

    // in your application bootstrap:
    $registry = new Zend_Registry(array(), ArrayObject::ARRAY_AS_PROPS)
    Zend_Registry::setInstance($registry);
    $registry->tree = 'apple';

    .
    .
    .

    // in a different function, elsewhere in your application:
    $registry = Zend_Registry::getInstance();

    echo $registry->tree; // echo's "apple"

    $registry->index = $value;

    var_dump($registry->index);

## Querying if an Index Exists

To find out if a particular index in the registry has been set, use the static method `isRegistered()`.

### Example of isRegistered() Method Usage

    if (Zend_Registry::isRegistered($index)) {
        $value = Zend_Registry::get($index);
    }

To find out if a particular index in a registry array or object has a value, use the `isset()` function as you would with an ordinary array.

### Example of isset() Method Usage

    $registry = Zend_Registry::getInstance();

    // using array access syntax
    if (isset($registry['index'])) {
        var_dump( $registry['index'] );
    }

    // using object access syntax
    if (isset($registry->index)) {
        var_dump( $registry->index );
    }

## Extending the Registry

The static registry is an instance of the class `Zend_Registry`. If you want to add functionality to the registry, you should create a class that extends `Zend_Registry` and specify this class to instantiate for the singleton in the static registry. Use the static method `setClassName()` to specify the class.

The class must be a subclass of `Zend_Registry`.

### Example of Specifying the Singleton Registry's Class Name

    Zend_Registry::setClassName('My_Registry');

    Zend_Registry::set('index', $value);

The registry throws a `Zend_Exception` if you attempt to set the classname after the registry has been accessed for the first time. It is therefore recommended that you specify the class name for your static registry in your application bootstrap.

## Unsetting the Static Registry

Although it is not normally necessary, you can unset the singleton instance of the registry, if desired. Use the static method `_unsetInstance()` to do so.

### Data Loss Risk

When you use `_unsetInstance()`, all data in the static registry are discarded and cannot be recovered.

You might use this method, for example, if you want to use `setInstance()` or `setClassName()` after the singleton registry object has been initialized. Unsetting the singleton instance allows you to use these methods even after the singleton registry object has been set. Using `Zend_Registry` in this manner is not recommended for typical applications and environments.

### Example of _unsetInstance() Method Usage

    Zend_Registry::set('index', $value);

    Zend_Registry::_unsetInstance();

    // change the class
    Zend_Registry::setClassName('My_Registry');

    Zend_Registry::set('index', $value);