ez components / documentation / installation guide

An Introduction to eZ Components

This guide provides a glimpse into the usage of the eZ Components for PHP 5. They are object oriented and reusable building blocks which will speed up development and deployment of enterprise applications based on PHP 5.

What is it?

eZ Components is an enterprise ready general purpose PHP components library. As a collection of high quality independent building blocks for PHP application development eZ Components will both speed up development and reduce risks. An application can use one or more components effortlessly as they all adhere to the same naming conventions and follow the same structure. All components are currently based on PHP 5.2.1.

The eZ Components in a nutshell:

  • Designed for enterprise PHP application development
  • Open source and licensed under the New BSD license
  • Clear intellectual property (IP) rights
  • Thoroughly documented
  • Developed, supported and maintained by eZ Systems

More general information about the eZ Components is available at the product page. Furthermore, there is a list of available components. Technical aspects of how the library is built-up are explained at the technical details page.


The purpose of the eZ Components is to hide complexity of routines behind an object oriented API. Regular tasks of programming become much easier, and due to the fact that complexity is being reduced, the risk of application development is minimized. In general, your development process will become more efficient.

For example, sending an email with the help of the eZ Mail component, looks like this:

   $transport = new ezcMailTransportSmtp( "" );
   $mail = new ezcMail();
   $mail->from = new ezcMailAddress( "", "Test" );
   $mail->addTo( new ezcMailAddress( "derick@tequila" ) );
   $mail->subject = "[Components test] SMTP test";
   $mail->body = new ezcMailText( "Content" );
   $transport->send( $mail );


catch ( Exception $e )
   echo "Failed: ", $e->getMessage(), "\n";

Of course you need to change the SMTP server's IP ( and definitely the email adresses in the sample code to fit your needs. For more examples of each of the eZ Components, take a look at the doc/ directory of each component where some sample code is provided.

Please notice that the eZ Components will only work on PHP 5.2.1 or higher. They can be used side-by-side with PEAR packages that as well run on PHP >= 5.2.1.


There are three ways how to make eZ components available for your PHP environment, please read the whole of this article before continuing with the practical part:

  • Use PEAR Installer for convenient installation via command line
  • Download eZ components packaged in an archive
  • Get the latest sources from SVN

Installing the eZ components with the help of the PEAR Installer is highly recommended, as it is the most convenient and safest way. The given instructions serve as guidelines on a Linux system, but are also useful for those who run PHP on Windows, of course they just need to adjust the paths accordingly.

PEAR Installer

After you have installed PHP 5.2.1 or a higher version, you will have the PEAR Installer available automatically. Simply issue the following commands in the shell:

pear channel-discover

This will let PEAR Installer connect to the server where the eZ components are stored for distribution:

pear install -a ezc/eZComponents

This final command will download and typically extract all eZ components to the directory where also the PEAR packages reside, but beneath the ezc/ subdirectory, with the absolute path being: /path/to/pear/ezc/

In case you already have installed the components before, you can simply do:

pear upgrade ezc/eZComponents

Download of Archives

The packaged releases of eZ components can be downloaded as .tar.bz2 or .zip archive from the download page. The bundles that we offer for download always include the whole library.


If you love to live on the edge and would like to work with the latest development version of the eZ components, you can get it from SVN. For a successful installation from SVN, procede in the given order.

First, create a directory where you want the eZ components to be placed.

Next, you should checkout the tree. To checkout, do:

svn co

When working with the SVN version, it is important to setup the environment for the eZ components. Hence, checkout the needed script with:

svn co

and execute it:


This will create the symlinks for autoload, which will of course not work on Windows.

From version 1.1 of the components there is also a script for Windows. Here you need to execute the following script instead:


This will create copies of necessary files for autoload.

Partial check out

It is of course also possible to check out from SVN per component. Again, you first have to create a directory again, something like:

mkdir /tmp/mydir/ezc
cd /tmp/mydir/ezc

Inside this directory, create the trunk directory:

mkdir trunk

Then check out the scripts directory and Base component:

svn co
svn co trunk/Base

Then you can check out each component that you want with a command like:

svn co trunk/Mail

Make sure to checkout all dependencies as well, if they exist. You can find whether a component has dependencies in the DEPS file in the root of each component (f.e. trunk/Mail/DEPS).

After you've checked out all components, run the setup-env script again:





After installation of the eZ Components, either via PEAR Installer, downloading of the archives, or getting them from SVN, you need to do a bit of configuration:

  • Adjust the include path to have the eZ Components classes available via PHP
  • Create the autoload environment for calling eZ Components from your script

Include Path

The PHP include path should point to the directory where the eZ Components reside. You can either set it in the php.ini configuration file or with the set_include_path() function from within your script.

If you installed the components with the PEAR installer, then in most cases you do not have to make any changes as PHP's include path will already cover the default:


into which the PEAR installer will install the eZ Components. In case it is different, please set it at the top of your script with:

set_include_path( "/path/to/root/pear/directory" . PATH_SEPARATOR .  get_include_path());

In case you downloaded a bundle, or checked out the components from SVN, set the include path to the root of the checked out archive. For example with:

set_include_path( "/path/to/ezcomponents-1.0rc1" . PATH_SEPARATOR .  get_include_path());

Autoload Environment

The PHP classes of the eZ Components can be conveniently used from within your PHP script. You don't have to use any require or include statements for any of the eZ Components classes that you use, this is because of the integrated autoload mechanism which can locate the classes for you when you instantiate or use them otherwise.

There are three different ways of getting the autoload mechanism going.

Normal Autoload

With the first method, you require the ezcBase class, and defined your own autoload mechanism. You should add the following code on top of your PHP script:

require_once "Base/base.php"; // dependent on installation method, see below
function __autoload( $className )
        ezcBase::autoload( $className );
// your code here

Beware, that the require_once() statement is different depending on the installation method:

  • PEAR Installer:

  • Downloaded bundle and SVN:


Boot strap

In case you only have to use autoload for the eZ Components, and not for your application or another library, you can just simple include the ezc_bootstrap.php file. Again, the file to require depends on the installation method.

  • PEAR Installer:

    require 'ezc/Base/ezc_bootstrap.php';
  • Downloaded bundle and SVN:

    require 'Base/src/ezc_bootstrap.php';


SPL (Standard PHP Library) also allows autoloading to be set up through the spl_autoload_register function. In this case, you require() the base class, just like in the Normal Autoload method, but instead of defining an __autoload() function, you do:

spl_autoload_register( array( 'ezcBase', 'autoload' ) );

Worth knowing

Required extensions

eZ Components require as few extensions by default. Required by all components are:

Both of these are bundled with PHP and activated by default. So if you did not actively remove these from your PHP installation manually, you don't have to care about them.

Specific components may require additional extensions, for example the database related components (Database, DatabaseSchema, PersistentObject) rely on PDO being available. The components documentation will give a hint, if special extensions are required. You can find a full overview in the documentation.

Some components provide different drivers, which use different extensions or external programs. You can choose one of these to make the component use the backend that you have available. An example is the Graph component, which can use different extensions to render graphics in different formats.

Character encoding

If not stated otherwise in the documentation, eZ Components assumes that the data that you provide is UTF-8 encoded. In the same way, the output and return values generated by each are UTF-8 encoded as well.

If you need to work with data in different encodings, make sure to convert this data to UTF-8 before handing it into any of the components.

To perform binary safe operations, the iconv extension is used internally in eZ Components. As mentioned before, this extension is delivered with PHP and activated by default. We recommend that you use this extension also for potential encoding conversions.

Some components allow you to work with different encodings than UTF-8. For example, the Mail component can work with several different encodings in parallel. Such exceptions of the rule are clearly marked in the documentation.


Now you have a working environment which lets you integrate the object oriented eZ Components for efficient application development with PHP 5.2.1. Besides using the eZ Components for developing your own mission-critical applications, you can as well take a look at the source code to see how eZ Systems makes use of the new PHP 5 features for object oriented programming within the eZ Components. Have a lot of fun!