The Module Autoloader

Zend Framework 2 ships with a default module autoloader. Zend\Loader\ModuleAutoloader is a specialized autoloader that is responsible for location of, and on-demand loading of, the Module classes from a variety of sources.

Module Autoloader Usage

If you are using the provided Zend\ModuleManager\Listener\DefaultListenerAggregate, then it is very simple to set up the module autoloader. You simply need to provide an array of module paths, either absolute or relative to the application’s root, for the module autoloader to check when loading modules. The default listener aggregate will take care of instantiating and registering the module autoloader for you.

Keep in mind that in order for paths relative to your application directory to work, you must have the directive chdir(dirname(__DIR__)); in your public/index.php.

Registering module paths with the default listener aggregate

The following example will search for modules in three different paths. Two are local directories for this application, and the third is a system-wide shared directory.

 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
// public/index.php
use Zend\ModuleManager\Listener;
use Zend\ModuleManager\ModuleManager;

chdir(dirname(__DIR__));

// Instantiate and configure the default listener aggregate
$listenerOptions = new Listener\ListenerOptions(array(
    'module_paths' => array(
        './module',
        './vendor',
        '/usr/share/zfmodules',
    )
));
$defaultListeners = new Listener\DefaultListenerAggregate($listenerOptions);

// Instantiate the module manager
$moduleManager = new ModuleManager(array(
    'Application',
    'FooModule',
    'BarModule',
));

// Attach the default listener aggregate and load the modules
$moduleManager->getEventManager()->attachAggregate($defaultListeners);
$moduleManager->loadModules();

Note

Module paths behave very similar to the PHP include path, and are searched in the order they are defined. If you have modules with the same name in more than one registered module path, the module autoloader will return the first one it finds.

Non-Standard / Explicit Module Paths

Sometimes you may want to specify exactly where a module is instead of having Zend\Loader\ModuleAutoloader try to find it in the registered paths.

Registering a Non-Standard / Explicit Module Path

In this example, the autoloader will first check for MyModule\Module in /path/to/mymoduledir-v1.2/Module.php. If it’s not found, then it will fall back to searching any other registered module paths.

 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
// ./public/index.php
use Zend\Loader\ModuleAutoloader;
use Zend\ModuleManager\Listener;
use Zend\ModuleManager\ModuleManager;

chdir(dirname(__DIR__));

// Instantiate and configure the default listener aggregate
$listenerOptions = new Listener\ListenerOptions(array(
    'module_paths' => array(
        './module',
        './vendor',
        '/usr/share/zfmodules',
        'MyModule' => '/path/to/mymoduledir-v1.2',
    )
));
$defaultListeners = new Listener\DefaultListenerAggregate($listenerOptions);

/**
 * Without DefaultListenerAggregate:
 *
 * $moduleAutoloader = new ModuleAutoloader(array(
 *     './module',
 *     './vendor',
 *     '/usr/share/zfmodules',
 *     'MyModule' => '/path/to/mymoduledir-v1.2',
 * ));
 * $moduleAutoloader->register();
 *
 */

// Instantiate the module manager
$moduleManager = new ModuleManager(array(
    'MyModule',
    'FooModule',
    'BarModule',
));

// Attach the default listener aggregate and load the modules
$moduleManager->getEventManager()->attachAggregate($defaultListeners);
$moduleManager->loadModules();

This same method works if you provide the path to a phar archive.

Packaging Modules with Phar

If you prefer, you may easily package your module as a phar archive. The module autoloader is able to autoload modules in the following archive formats: .phar, .phar.gz, .phar.bz2, .phar.tar, .phar.tar.gz, .phar.tar.bz2, .phar.zip, .tar, .tar.gz, .tar.bz2, and .zip.

The easiest way to package your module is to simply tar the module directory. You can then replace the MyModule/ directory with MyModule.tar, and it should still be autoloaded without any additional changes!

Note

If possible, avoid using any type of compression (bz2, gz, zip) on your phar archives, as it introduces unnecessary CPU overhead to each request.

Project Versions

Table Of Contents

Previous topic

The Module Class

Next topic

Best Practices when Creating Modules

This Page

Note: You need to stay logged into your GitHub account to contribute to the documentation.

Edit this document

Edit this document

The source code of this file is hosted on GitHub. Everyone can update and fix errors in this document with few clicks - no downloads needed.

  1. Login with your GitHub account.
  2. Go to The Module Autoloader on GitHub.
  3. Edit file contents using GitHub's text editor in your web browser
  4. Fill in the Commit message text box at the end of the page telling why you did the changes. Press Propose file change button next to it when done.
  5. On Send a pull request page you don't need to fill in text anymore. Just press Send pull request button.
  6. Your changes are now queued for review under project's Pull requests tab on GitHub.