19.2. Extending the Autoloading Feature

The autoloading feature, briefly explained in Chapter 2, exempts you from requiring classes in your code if they are located in specific directories. This means that you can just let the framework do the job for you, allowing it to load only the necessary classes at the appropriate time, and only when needed.

The autoload.yml file lists the paths in which autoloaded classes are stored. The first time this configuration file is processed, symfony parses all the directories referenced in the file. Each time a file ending with .php is found in one of these directories, the file path and the class names found in this file are added to an internal list of autoloading classes. This list is saved in the cache, in a file called config/config_autoload.yml.php. Then, at runtime, when a class is used, symfony looks in this list for the class path and includes the .php file automatically.

Autoloading works for all .php files containing classes and/or interfaces.

By default, classes stored in the following directories in your projects benefit from the autoloading automatically:

• myproject/lib/
• myproject/lib/model
• myproject/apps/frontend/lib/
• myproject/apps/frontend/modules/mymodule/lib

There is no autoload.yml file in the default application configuration directory. If you want to modify the framework settings — for instance, to autoload classes stored somewhere else in your file structure — create an empty autoload.yml file and override the settings of $sf_symfony_lib_dir/config/config/autoload.yml or add your own.

The autoload.yml file must start with an autoload: key and list the locations where symfony should look for classes. Each location requires a label; this gives you the ability to override symfony's entries. For each location, provide a name (it will appear as a comment in config_autoload.yml.php) and an absolute path. Then define if the search must be recursive, which directs symfony to look in all the subdirectories for .php files, and exclude the subdirectories you want. Listing 19-4 shows the locations used by default and the file syntax.

Listing 19-4 - Default Autoloading Configuration, in $sf_symfony_lib_dir/config/config/autoload.yml

autoload:
  # plugins
  plugins_lib:
    name:           plugins lib
    path:           %SF_PLUGINS_DIR%/*/lib
    recursive:      on

  plugins_module_lib:
    name:           plugins module lib
    path:           %SF_PLUGINS_DIR%/*/modules/*/lib
    prefix:         2
    recursive:      on

  # project
  project:
    name:           project
    path:           %SF_LIB_DIR%
    recursive:      on
    exclude:        [model, symfony]

  project_model:
    name:           project model
    path:           %SF_LIB_DIR%/model
    recursive:      on

  # application
  application:
    name:           application
    path:           %SF_APP_LIB_DIR%
    recursive:      on

  modules:
    name:           module
    path:           %SF_APP_DIR%/modules/*/lib
    prefix:         1
    recursive:      on

A rule path can contain wildcards and use the file path parameters defined in the configuration classes (see the next section). If you use these parameters in the configuration file, they must appear in uppercase and begin and end with %.

Editing your own autoload.yml will add new locations to symfony's autoloading, but you may want to extend this mechanism and add your own autoloading handler to symfony's handler. As symfony uses the standard spl_autoload_register() function to manage class autoloading, you can register more callbacks in the application configuration class:

class frontendConfiguration extends sfApplicationConfiguration
{
  public function initialize()
  {
    parent::initialize(); // load symfony autoloading first

    // insert your own autoloading callables here
    spl_autoload_register(array('myToolkit', 'autoload'));
  }
}

When the PHP autoloading system encounters a new class, it will first try the symfony autoloading method (and use the locations defined in autoload.yml). If it doesn't find a class definition, all the other callables registered with spl_autoload_register() will be called, until the class is found. So you can add as many autoloading mechanisms as you want — for instance, to provide a bridge to other framework components (see Chapter 17).