Why?

We're planning on reducing the required components for the MVC and framework. Currently in v2, however, zend-mvc provides copious amounts of integrations with other components; removing them as dependencies means their factories, plugin managers, and event listeners will not be wired automatically. One proposed solution is to provide each component with a Module class that could provide those; however, one issue with that approach is ensuring that the components are then added to the list of enabled modules.

The approach this package takes is to provide Composer event hooks that will update the enabled module list when a package providing a module is installed or uninstalled. However, Composer has a few limitations with regards to such hook scripts:

• If the code is in a package on which the project depends, a warning is emitted for each package installed until the package containing the scripts is processed. This will likely raise a lot of support questions.
• If the event hook classes are present inside the project, they must be autoloadable. Additionally, the must always be autoloadable; you cannot define a autoload-dev rule for the classes/namespaces; only a production one will work.

These limitations are easily accommodated for new projects, as we can include them in project skeletons. However, for those migrating to ZF3, we want to provide a mechanism for adding the scripts.

The solution presented here is to provide a utility that will will copy the classfiles for the scripts into your project, and then manipulate the composer.json to add autoload rules for them, and to add entries for the event hook scripts.

You have two options: using a downloadable, self-updateable PHAR, or installation as a global Composer package.

---

Get the PHAR

• zend-component-installer.phar
• public OpenSSL key (to verify the PHAR)

You'll need to download both files, and they will need to reside together.

Once downloaded, make the PHAR executable, and execute zend-component-installer.phar help to verify that it works.

Using the PHAR

$ zend-component-installer.phar install
# Or specify a path to a project
$ zend-component-installer.phar install /path/to/my/project
    

Once installed, whenever your install a component that implements a module, it will update the config/application.config.php file to add the component to the module list. Components are always added to the top of the list, to ensure that your own modules can override any settings they introduce.

Keeping up-to-date

Periodically, we may make changes to the tool. To update, you can use the self-update command:

$ zend-component-installer.phar self-update
    

Two notes on this command:

• The self-update features require PHP 5.6 or above. This is due to the fact that it is doing SSL/TLS negotiation in order to both check for an update, as well as download the new PHAR file; PHP 5.6 is the first version of PHP that provides proper SSL/TLS negotiation with the shipped defaults. You can use the installer with 5.5, just not the self-updater.
• The command will put a copy of the previous version of the command in the sibling file zend-component-installer-old.phar. This allows you to rollback to the previous version should you detect a problem.

Rolling back

When using the PHAR, you can also rollback to a previously installed version, if you have kept the zend-component-installer-old.phar file:

$ zend-component-installer.phar rollback
    

---

Global Composer Installation

You can also install the utility as a global Composer package:

$ composer global require zendframework/zend-component-installer
    

This will install the package globally. In order to use it, the $COMPOSER_HOME/bin directory must be in your user's $PATH. From there, invocation is:

$ zend-component-installer installer []
    

Keeping up-to-date

To keep your utility up-to-date, periodically perform the following:

$ composer global update zendframework/zend-component-installer
    

---

Defining a component that implements a module

There are two things you must do to have your package opt-in to this workflow:

• The component must have a Module class in the namespace it defines.
• The composer.json must specify the component namespace in the extra.zf section:

  
    "extra": {
      "zf": {
        "component": "Some\Component"
      }
    }
          

Component modules are placed at the top of the module list, so that userland modules may override the defaults they provide.

Defining a userland module

There are two things you must do to have your package opt-in to this workflow:

• The module must have a Module class in the namespace it defines.
• The composer.json must specify the module namespace in the extra.zf section:

  
    "extra": {
      "zf": {
        "module": "Some\Component"
      }
    }
          

Userland modules are placed at the bottom of the module list, so that their settings may override component settings.