diff --git a/docs/book/intro.md b/docs/book/intro.md index a21c221..dd8562c 100644 --- a/docs/book/intro.md +++ b/docs/book/intro.md @@ -15,10 +15,6 @@ CSS, and JavaScript. The possibilities are endless. The module system is made up of the following: -- [The Module Autoloader](https://docs.zendframework.com/zend-loader/module-autoloader/) - - `Zend\Loader\ModuleAutoloader` is a specialized autoloader that is responsible - for the locating and loading of modules' `Module` classes from a variety of - sources. - [The Module Manager](module-manager.md) - `Zend\ModuleManager\ModuleManager` takes an array of module names and fires a sequence of events for each one, allowing the behavior of the module system to be defined entirely by the @@ -34,14 +30,10 @@ The module system is made up of the following: > [PHP namespace](http://php.net/namespaces), and must follow all of the same > rules for naming. -The recommended structure for an MVC-oriented ZF2 module is as follows: +The recommended structure for a zend-mvc oriented module is as follows: ```text module_root/ - Module.php - autoload_classmap.php - autoload_function.php - autoload_register.php config/ module.config.php public/ @@ -49,32 +41,20 @@ module_root/ css/ js/ src/ - / - + Module.php + test/ - phpunit.xml - bootstrap.php - / - + view/ / / <.phtml files> + phpunit.xml.dist + composer.json ``` -## The autoload\_\*.php Files +## Autoloading -The three `autoload_*.php` files are not required, but recommended. They provide the following: - -- `autoload_classmap.php` should return an array classmap of class name/filename - pairs (with the filenames resolved via the `__DIR__` magic constant). -- `autoload_function.php` should return a PHP callback that can be passed to - `spl_autoload_register()`. Typically, this callback should utilize the map - returned by `autoload_classmap.php`. -- `autoload_register.php` should register a PHP callback (typically that - returned by `autoload_function.php` with `spl_autoload_register()`. - -The purpose of these three files is to provide reasonable default mechanisms for -autoloading the classes contained in the module, thus providing a trivial way to -consume the module without requiring zend-modulemanager` (e.g., for use outside -a ZF2 application). +Since version 3, zend-modulemanager does not provide own autoloading mechanisms +and instead relies on [Composer dependency manager](https://getcomposer.org/) +to provide autoloading. diff --git a/docs/book/migration/to-v3-0.md b/docs/book/migration/to-v3-0.md new file mode 100644 index 0000000..f103bad --- /dev/null +++ b/docs/book/migration/to-v3-0.md @@ -0,0 +1,84 @@ +# Upgrading to 3.0 + +## Module autoloading + +zend-modulemanager originates from before the Composer was created, where each +framework had to provide its own autoloading implementation. +Since then Composer became the de-facto standard in managing dependencies and +autoloading for the php projects. +In light of that, zend-servicemanager removes ModuleLoader and autoload +providers support in version 3.0 in favor of +[Composer dependency manager](https://getcomposer.org/). + +### Application local modules + +Autoloading rules for application local modules should now be defined in +application's composer.json + +Before: +```php +namespace Application; + +class Module +{ + public function getAutoloaderConfig() + { + return [ + 'Zend\Loader\StandardAutoloader' => [ + 'namespaces' => [ + __NAMESPACE__ => __DIR__ . '/src/' . __NAMESPACE__, + ], + ], + ]; + } +} +``` +and after: +```json +{ + "name": "zendframework/skeleton-application", + "description": "Skeleton Application for Zend Framework zend-mvc applications", + "type": "project", + ... + "autoload": { + "psr-4": { + "Application\\": "module/Application/src/" + } + }, + "autoload-dev": { + "psr-4": { + "ApplicationTest\\": "module/Application/test/" + } + } +} +``` + +[zf-composer-autoloading](https://github.com/zfcampus/zf-composer-autoloading) +provides a handy tool to easily add and remove autoloading rules for local modules to +application's composer.json + +After autoloading rules were updated, composer will need to update autoloader: + +```console +$ composer dump-autoload +``` + +### Composer installed modules + +For composer installed modules, autoloading rules will be automatically picked +by composer from the module's composer.json and no extra effort is needed: +```json +{ + "name": "acme/my-module", + "description": "Module for use with zend-mvc applications.", + "type": "library", + "require": { + "php": "^7.1" + }, + "autoload": { + "psr-4": { + "Acme\\MyModule\\": "src/" + } + } +} +``` diff --git a/docs/book/module-autoloader.md b/docs/book/module-autoloader.md deleted file mode 100644 index dcbc689..0000000 --- a/docs/book/module-autoloader.md +++ /dev/null @@ -1,161 +0,0 @@ -# The Module Autoloader - -zend-modulemanager ships with the default module autoloader -`Zend\Loader\ModuleAutoloader`. It is a specialized autoloader responsible for -locating and on-demand loading of, the `Module` classes from a variety of -sources. - -## Module Autoloader Usage - -By default, the provided `Zend\ModuleManager\Listener\DefaultListenerAggregate` -sets up the `ModuleAutoloader`; as a developer, you need only provide an array -of module paths, either absolute or relative to the application's root, for the -`ModuleAutoloader` to check when loading modules. The `DefaultListenerAggregate` -will take care of instantiating and registering the `ModuleAutoloader` for you. - -> ### Must be in application root -> -> In order for paths relative to your application directory to work, you must -> have the directive `chdir(dirname(__DIR__));` in your `public/index.php` file. - -### Registering module paths with the `DefaultListenerAggregate` - -The following example will search for modules in three different `module_paths`. -Two are local directories of this application and the third is a system-wide -shared directory. - -```php -// 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([ - 'module_paths' => [ - './module', - './vendor', - '/usr/share/zfmodules', - ] -]); -$defaultListeners = new Listener\DefaultListenerAggregate($listenerOptions); - -// Instantiate the module manager -$moduleManager = new ModuleManager([ - 'Application', - 'FooModule', - 'BarModule', -]); - -// Attach the default listener aggregate and load the modules -$moduleManager->getEventManager()->attachAggregate($defaultListeners); -$moduleManager->loadModules(); -``` - -> ### Module paths are FIFO -> -> Module paths behave very similar to PHP's `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. - -> ### Disabling the ModuleAutoloader -> -> - Since 2.8.0 -> -> If you are using Composer to autoload, you may not need to use the -> `ModuleAutoloader`. As such, you can disable it by passing the following -> option to the `ListenerOptions` class: -> -> ```php -> 'use_zend_loader' => false, -> ``` -> -> If your project was begun from the [skeleton application](https://github.com/zendframework/ZendSkeletonApplication), -> place the above within the `module_listener_options` configuration of your -> `config/application.config.php` file: -> -> ```php -> return [ -> /* ... */ -> 'module_listener_options' => [ -> 'use_zend_loader' => false, -> /* ... */ -> ], -> /* ... */ -> ]; -> ``` - -## 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. - -```php -// ./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([ - 'module_paths' => [ - './module', - './vendor', - '/usr/share/zfmodules', - 'MyModule' => '/path/to/mymoduledir-v1.2', - ] -]); -$defaultListeners = new Listener\DefaultListenerAggregate($listenerOptions); - -/** - * Without DefaultListenerAggregate: - * - * $moduleAutoloader = new ModuleAutoloader([ - * './module', - * './vendor', - * '/usr/share/zfmodules', - * 'MyModule' => '/path/to/mymoduledir-v1.2', - * ]); - * $moduleAutoloader->register(); - * - */ - -// Instantiate the module manager -$moduleManager = new ModuleManager([ - '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](http://php.net/phar). 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. - -Package your module by performing a tar the module directory. You can then -replace the `MyModule/` directory with `MyModule.tar`, and it should still be -autoloaded without any additional changes! - -> ### Avoid compression -> -> If possible, avoid using any type of compression (bz2, gz, zip) on your phar -> archives, as it introduces unnecessary CPU overhead to each request. diff --git a/docs/book/module-class.md b/docs/book/module-class.md index 4b4d8cb..80ab80b 100644 --- a/docs/book/module-class.md +++ b/docs/book/module-class.md @@ -9,9 +9,7 @@ of `{moduleName}\Module` for each enabled module. As an example, provided the module name "MyModule", `Zend\ModuleManager\Listener\ModuleResolverListener` will expect the class -`MyModule\Module` to be available. It relies on a registered autoloader -(typically `Zend\Loader\ModuleAutoloader`) to find and include the -`MyModule\Module` class if it isn't already available. +`MyModule\Module` to be available. > ### Module classes > @@ -26,7 +24,8 @@ something like this: ```text MyModule/ - Module.php + src/ + Module.php ``` Within `Module.php`, you define your `MyModule\Module` class: @@ -46,7 +45,7 @@ module system! This `Module` class serves as the single entry point for `ModuleManager` listeners to interact with a module. From within this class, modules can override or provide additional application configuration, perform initialization -tasks such as registering autoloader(s), services and event listeners, declaring +tasks such as registering services and event listeners, declaring dependencies, and much more. ## A Typical Module Class @@ -58,20 +57,6 @@ namespace MyModule; class Module { - public function getAutoloaderConfig() - { - return [ - 'Zend\Loader\ClassMapAutoloader' => [ - __DIR__ . '/autoload_classmap.php', - ], - 'Zend\Loader\StandardAutoloader' => [ - 'namespaces' => [ - __NAMESPACE__ => __DIR__ . '/src/' . __NAMESPACE__, - ], - ], - ]; - } - public function getConfig() { return include __DIR__ . '/config/module.config.php'; @@ -79,8 +64,9 @@ class Module } ``` -For a list of the provided module manager listeners and the interfaces and methods that `Module` -classes may implement in order to interact with the module manager and application, see the +For a list of the provided module manager listeners and the interfaces and +methods that `Module` classes may implement in order to interact with the +module manager and application, see the [module manager listeners](module-manager.md#module-manager-listeners) and the [module mananger events](module-manager.md#module-manager-events) documentation. diff --git a/docs/book/module-manager.md b/docs/book/module-manager.md index 798b50f..4c7a133 100644 --- a/docs/book/module-manager.md +++ b/docs/book/module-manager.md @@ -63,20 +63,12 @@ shipped listeners are in the `Zend\ModuleManager\Listener` namespace. ### DefaultListenerAggregate -To address the most common use case of the module manager, ZF2 provides +To address the most common use case of the module manager, zend-modulemanager provides this default aggregate listener. In most cases, this will be the only listener you will need to attach to use the module manager, as it will take care of properly attaching the requisite listeners (those listed below) for the module system to function properly. -### AutoloaderListener - -This listener checks each module to see if it has implemented -`Zend\ModuleManager\Feature\AutoloaderProviderInterface` or defined the -`getAutoloaderConfig()` method. If so, it calls the `getAutoloaderConfig()` -method on the module class and passes the returned array to -`Zend\Loader\AutoloaderFactory`. - ### ModuleDependencyCheckerListener This listener checks each module to verify if all the modules it depends on were diff --git a/mkdocs.yml b/mkdocs.yml index b2c89a8..404b2e5 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -6,8 +6,9 @@ nav: - Reference: - "The Module Manager": module-manager.md - "The Module Class": module-class.md - - "The Module Autoloader": module-autoloader.md - "Best Practices when Creating Modules": best-practices.md + - Migration: + - "v2.X to v3.0": migration/to-v3-0.md site_name: zend-modulemanager site_description: "Modular application system for zend-mvc applications" repo_url: 'https://github.com/zendframework/zend-modulemanager'