The definitive guide of Symfony 1.0

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/myapp/lib/
  • myproject/apps/myapp/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_data_dir/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-2 shows the locations used by default and the file syntax.

Listing 19-2 - Default Autoloading Configuration, in $sf_symfony_data_dir/config/autoload.yml


  # symfony core
    name:           symfony
    path:           %SF_SYMFONY_LIB_DIR%
    recursive:      on
    exclude:        [vendor]

    name:           propel
    path:           %SF_SYMFONY_LIB_DIR%/vendor/propel
    recursive:      on

    name:           creole
    path:           %SF_SYMFONY_LIB_DIR%/vendor/creole
    recursive:      on

    name:           propel addon
      Propel:       %SF_SYMFONY_LIB_DIR%/addon/propel/sfPropelAutoload.php

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

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

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

    name:           project model
    path:           %SF_MODEL_LIB_DIR%
    recursive:      on

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

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

A rule path can contain wildcards and use the file path parameters from the constants.php file (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. This is possible through the autoloading_functions parameter in the settings.yml file. It expects an array of callables as a value, as follows:

    - [myToolkit, autoload]

When symfony encounters a new class, it will first try its own autoloading system (and use the locations defined in autoload.yml). If it doesn't find a class definition, it will then try the other autoloading functions from settings.yml, 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).