Learn / eZ Publish / An Introduction to eZ Components

An Introduction to eZ Components

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 based on PHP 5.1, except for the ones that require the new Unicode support in PHP 6.

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.

Roadmap

The future of the eZ Components are listed on a separate page .

Usage

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:

<?php<

try

{

   $transport = new ezcMailTransportSmtp( "smtp.example.com" );
   $mail = new ezcMail();
   $mail->from = new ezcMailAddress( "null@example.com", "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(), "
";
}
?>

Of course you need to change the SMTP server's IP ( smtp.example.com) 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.1.1 or higher. They can be used side-by-side with PEAR packages that as well run on PHP >= 5.1.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.1.1 or a higher version, you will have the PEAR Installer available automatically. Simply issue the following commands in the shell:

pear channel-discover components.ez.no

This will let PEAR Installer connect to the server components.ez.no 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.

SVN

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 http://svn.ez.no/svn/ezcomponents/trun

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 http://svn.ez.no/svn/ezcomponents/scripts

and execute it:

./scripts/setup-env.sh

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:

scripts\setup-env.bat

This will create copies of necessary files for autoload.

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

/usr/local/lib/php

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:

<?php
<a href="http://www.php.net/set_include_path" mce_href="http://www.php.net/set_include_path">set_include_path</a>("/path/to/root/pear/directory:" . <a href="http://www.php.net/ini_get" mce_href="http://www.php.net/ini_get">ini_get</a>( "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:

<?php
<a href="http://www.php.net/set_include_path" mce_href="http://www.php.net/set_include_path">set_include_path</a><span>("/path/to/ezcomponents-1.0rc1:" . <a href="http://www.php.net/ini_get" mce_href="http://www.php.net/ini_get">ini_get</a>( "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.

Therefore, you should add the following code on top of your PHP script:

<?php
require_once "Base/base.php"; // dependent on installation method, see below
     function __autoload( $className ){

        ezcBase::autoload($className );
}
// your code here
?>

The require_once statement is different depending on the installation method:

  • PEAR Installer:

    ezc/Base/base.php
  • Downloaded bundle:

    Base/src/base.php
  • SVN:

    Base/src/base.php

Do not forget to add these lines, otherwise the eZ Components will not function properly, because all of them use the autoload internally.

Now you have a working environment which lets you integrate the object oriented eZ Components for efficient application development with PHP 5.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!

Resources