# Loading Files and Classes Dynamically

The `Zend_Loader` class includes methods to help you load files dynamically.

## Zend_Loader vs. require_once()

The `Zend_Loader` methods are best used if the filename you need to load is variable. For example, if it is based on a parameter from user input or method argument. If you are loading a file or a class whose name is constant, there is no benefit to using `Zend_Loader` over using traditional PHP functions such as `require_once()`.

## Loading Files

The static method `Zend_Loader::loadFile()` loads a PHP file. The file loaded may contain any PHP code. The method is a wrapper for the PHP function `include()`. This method returns boolean false on failure, for example if the specified file does not exist.

### Example of the loadFile() Method

    Zend_Loader::loadFile($filename, $dirs=null, $once=false);

The `$filename` argument specifies the filename to load, which must not contain any path information. A security check is performed on `$filename`. The `$filename` may only contain alphanumeric characters, dashes ("-"), underscores ("_"), or periods ("."). No such restriction is placed on the `$dirs` argument.

The `$dirs` argument specifies which directories to search for the file in. If the value is `NULL`, only the `include_path` is searched; if the value is a string or an array, the directory or directories specified will be searched, followed by the `include_path`.

The `$once` argument is a boolean. If `TRUE`, `Zend_Loader::loadFile()` uses the PHP function `include_once()` for loading the file, otherwise the PHP function `include()` is used.

## Loading Classes

The static method `Zend_Loader::loadClass($class, $dirs)` loads a PHP file and then checks for the existence of the class.

### Example of the loadClass() Method

    Zend_Loader::loadClass('Container_Tree',
        array(
            '/home/production/mylib',
            '/home/production/myapp'
        )
    );

The string specifying the class is converted to a relative path by substituting underscores with directory separators for your OS, and appending '.php'. In the example above, 'Container_Tree' becomes 'Container\\Tree.php' on Windows.

If `$dirs` is a string or an array, `Zend_Loader::loadClass()` searches the directories in the order supplied. The first matching file is loaded. If the file does not exist in the specified `$dirs`, then the `include_path` for the PHP environment is searched.

If the file is not found or the class does not exist after the load, `Zend_Loader::loadClass()` throws a `Zend_Exception`.

`Zend_Loader::loadFile()` is used for loading, so the class name may only contain alphanumeric characters and the hyphen ('-'), underscore ('_'), and period ('.').

## Testing if a File is Readable

The static method `Zend_Loader::isReadable($pathname)` returns `TRUE` if a file at the specified pathname exists and is readable, `FALSE` otherwise.

### Example of isReadable() method

    if (Zend_Loader::isReadable($filename)) {
        // do something with $filename
    }

The `$filename` argument specifies the filename to check. This may contain path information. This method is a wrapper for the PHP function `is_readable()`. The PHP function does not search the `include_path`, while `Zend_Loader::isReadable()` does.

## Using the Autoloader

The `Zend_Loader` class contains a method you can register with the PHP SPL autoloader. `Zend_Loader::autoload()` is the callback method. As a convenience, `Zend_Loader` provides the `registerAutoload()` function to register its `autoload()` method. If the `spl_autoload` extension is not present in your PHP environment, then the `registerAutoload()` method throws a `Zend_Exception`.

### Example of registering the autoloader callback method

    Zend_Loader::registerAutoload();

After registering the Zend Framework autoload callback, you can reference classes from Zend Framework without having to load them explicitly. The `autoload()` method uses `Zend_Loader::loadClass()` automatically when you reference a class.

If you have extended the `Zend_Loader` class, you can give an optional argument to `registerAutoload()`, to specify the class from which to register an `autoload()` method.

### Example of registering the autoload callback method from an extended class

Because of the semantics of static function references in PHP, you must implement code for both `loadClass()` and `autoload()`, and the `autoload()` must call `self::loadClass()`. If your `autoload()` method delegates to its parent to call `self::loadClass()`, then it calls the method of that name in the parent class, not the subclass.

    class My_Loader extends Zend_Loader
    {
        public static function loadClass($class, $dirs = null)
        {
            parent::loadClass($class, $dirs);
        }

        public static function autoload($class)
        {
            try {
                self::loadClass($class);
                return $class;
            } catch (Exception $e) {
                return false;
            }
        }
    }

    Zend_Loader::registerAutoload('My_Loader');

You can remove an autoload callback. The `registerAutoload()` has an optional second argument, which is `TRUE` by default. If this argument is `FALSE`, the autoload callback is unregistered from the SPL autoload stack.