17.3. Bridges to Other Framework's Components

If you need capabilities provided by a third-party class, and if you don't want to copy this class in one of the symfony lib/ dirs, you will probably install it outside of the usual places where symfony looks for files. In that case, using this class will imply a manual require in your code, unless you use the symfony bridge to take advantage of the autoloading.

Symfony doesn't (yet) provide tools for everything. If you need a PDF generator, an API to Google Maps, or a PHP implementation of the Lucene search engine, you will probably need a few libraries from the Zend Framework. If you want to manipulate images directly in PHP, connect to a POP3 account to read e-mails, or design a console interface, you might choose the libraries from eZcomponents. Fortunately, if you define the right settings, the components from both these libraries will work out of the box in symfony.

The first thing that you need to declare (unless you installed the third-party libraries via PEAR) is the path to the root directory of the libraries. This is to be done in the application settings.yml:

.settings:
  zend_lib_dir:   /usr/local/zend/library/
  ez_lib_dir:     /usr/local/ezcomponents/

Then, extend the autoload routine by specifying which library to consider when the autoloading fails with symfony:

.settings:
  autoloading_functions:
    - [sfZendFrameworkBridge, autoload]
    - [sfEzComponentsBridge,  autoload]

Note that this setting is distinct from the rules defined in autoload.yml (see Chapter 19 for more information about this file). The autoloading_functions setting specifies bridge classes, and autoload.yml specifies paths and rules for searching. The following describes what will happen when you create a new object of an unloaded class:

1. The symfony autoloading function (sfCore::splAutoload()) first looks for a class in the paths declared in the autoload.yml file.
2. If none is found, the callback methods declared in the sf_autoloading_functions setting will be called one after the other, until one of them returns true:
3. sfZendFrameworkBridge::autoload()
4. sfEzComponentsBridge::autoload()
5. If these also return false, if you use PHP 5.0.X, symfony will throw an exception saying that the class doesn't exist. Starting with PHP 5.1, the error will be generated by PHP itself.

This means that the other framework components benefit from the autoload mechanism, and you can use them even more easily than within their own environment. For instance, if you want to use the Zend_Search component in the Zend Framework to implement an equivalent of the Lucene search engine in PHP, you have to write this:

require_once 'Zend/Search/Lucene.php';
$doc = new Zend_Search_Lucene_Document();
$doc->addField(Zend_Search_Lucene_Field::Text('url', $docUrl));
...

With symfony and the Zend Framework bridge, it is simpler. Just write this:

$doc = new Zend_Search_Lucene_Document(); // The class is autoloaded
$doc->addField(Zend_Search_Lucene_Field::Text('url', $docUrl));
...

The available bridges are stored in the $sf_symfony_lib_dir/addon/bridge/ directory.