How does configuration work in ZF2?

As ZF2 increases the beta count and draws nearer to RC I’ve noticed more questions popping up in IRC regarding configuration. Questions like:

“How do I setup XXX?”
“Where do I add module options?” 

So, I decided to write up a quick blog explaining how configuration works in ZF2. By default, there are three types of configurations.

  • config/application.config.php – This configuration file is at the “lowest-level” and is primarily responsible for setting up the service manager and module manager (see index.php). This is the file you will add modules to but, beyond that, will have little interaction with.
  • module/{ModuleName}/config/module.config.php - These configuration files are “middle-level” and are used to configure a specific module. The general rule of thumb is that any module living in vendor/ should not be modified – this includes the configuration! Since I know you want to reuse code and reduce duplication you should have plenty of vendor/ modules. Feel free to edit the configuration in your own modules but keep a goal in the back of your mind to get to a point where the configuration changes only for application specific options!
  • /config/autoload/{,*.}{global,local}.php – Woah, Spiffy, what’s up with that crazy path? Well, that’s a glob pattern and it’s used to determine which configuration files to load as well as the order to load them in. These files are considered the “highest-level.” By default, the glob is exactly as I pasted it and that pattern will load any file in config/autoload/ that ends with global.php or local.php. You’ll notice that global is listed before local which is important because it means that your local configuration files will override your global configuration files. This is a good thing! It means you can have development/staging/whatever configuration files in *.local.php which will override your global production files. It’s important to remember not to commit your local config files!

The reason I assigned levels to the files above is to help illustrate how these files are loaded. The application.config.php file is loaded on bootstrap and, after that, is not used. The module configuration files are merged through magic into a condensed merged config which is available from the module manager as well as the service manager under the Configuration service.

The load order for modules is as follows:

  1. Merge together all modules configurations into one array. In general, the order of modules does not matter but it’s possible that you may have a situation where one module overwrites another. If this happens, you need to make sure you list the modules in application.config.php in the correct order. At the time of this writing, I know of no third-party modules where ordering in application.config.php matters so I don’t have a concrete example for you.
  2. Resolve the files from the glob pattern and merge those files in order with the module configuration.

To summarize:

  • There are three primary configurations by default: application.config.php, module config, and autoloaded configuration.
  • The order is: modules -> config/autoload/*.global.php -> config/autoload/*.local.php => merged configuration
  • If you want to override module settings to do it in the autoload/ files! Just remember that you should not commit your local configuration files.
  • The glob pattern is specified in the application.config.php file if you want to modify the default.

5 Responses to “How does configuration work in ZF2?”

  1. [...] Hier eine Liste mit Beiträgen aus den letzten Tagen: How does configuration work in ZF2? [...]

  2. Maciej says:

    Maybe You could help me :) , I dont understand the concept of module config merging, it really sucks, for example if I have two modules with same layout file – the first config would be overwritten by the second one, So I have to put whole module config to separate local file, am I right ?

  3. Ryan says:

    So – let’s say I have development.local.php, staging.local.php, production.local.php, testing.local.php under my autoload directory – how would ZF2 knowwhich one to use?

  4. [...] Zend Framework 2 introduced the concept of local and global config files (learn more about this here). To be short, those files are saved in your autoload folder, and allow to configure a module. [...]

  5. demonkoryu says:

    I don’t know what you mean with “layout file”, but the configuration arrays are merged recursively, ie. they are mostly added to and overwritten only in the case of leaf (config) values; in the order in which the modules appear in the application.config.php.

Leave a Reply