loading external libraries in extensions

Often you need to include external 3rd party libraries or your own libraries in the extensions (like for example a SOAP library). The problem comes when you have to include the same library in several extensions.

Here is how to do it without having to copy the same library in every extension directory.

The Problem

When using non official eZ extensions or those developed on your own, there's often a need to include other 3rd party libraries (for example a SOAP library) or some of your own libraries. The most simple way is to copy the library to your extension directory and include it in your PHP sources.

But the problem comes when you need to use the same library in several extensions. If you copy the library to the all extension directories then you have to update all the copies when a new version of a library comes, or when you make changes to some of your libraries. Also you could have problems with your include() directives if you change the folder in which your extension resides.

The Solution

Fortunately since eZ 4 there's an autoload mechanism that allows you to include your libraries without having to include() them in your PHP scripts. You just generate the autoload file and include it in you PHP script. This is how you do it...

1. In the extension folder create a folder where you will put all the needed libraries. For example, named "external_libraries". Note, that you will not enable it as an extension, you just have to put it in the extension folder so that it will be parsed by the autoload generation script.

2. In all your PHP scripts include the autoload.php:

require_once('autoload.php');

3. Regenerate the autoload arrays from shell:

php bin/php/ezpgenerateautoloads.php

or by clicking the "Regenerate autoloads" button in the "Extensions" section of admin.

Optionally you can generate autoload array only for extensions:

php bin/php/ezpgenerateautoloads.php --extension

Note: All this only works for libraries in which you use PHP classes, objects and methods. It doesn't work if you want to call a normal PHP function from a library.

For advanced users

If you are an advanced user, you can even include libraries that are outside of your eZP installation. It goes like this:

1. Build the autoload array for the external folder

php bin/php/ezpgenerateautoloads.php --target=autoload /path/to/external/folder/library_name

This creates a file named "library_name_autoload.php" in the autload folder of your eZ installation

2. Create a PHP script with a custom autoload class and method, that will load the autload array from "library_name_autoload.php". For example see the ezpAutoloader class in autoload.php script of your eZP installation. The script should register the created autoload class and method at the end:

spl_autoload_register( array( 'myAutoloadClas', 'myAutoloadMethod' ) );

3. Include your autoload script in your PHP scripts.

I didn't test this advanced usage, but it should work. If anyone tries, post your feedback here.