Apache Zeta Components - high quality PHP components

An Introduction to Apache Zeta Components

This guide provides a glimpse into the usage of the Apache Zeta 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?

Apache Zeta Components is an enterprise ready general purpose PHP components library. As a collection of high quality independent building blocks for PHP application development Apache Zeta 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 Apache Zeta Components in a nutshell:

Designed for enterprise PHP application development
Open source and licensed under the Apache License, Version 2.0
Clear intellectual property (IP) rights
Thoroughly documented
Fully maintained by the open source community, initially developed by eZ Systems

Usage

The purpose of Apache Zeta 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 Zeta 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(), "\n";
}
?>

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

Furthermore, extensive API documentation and a tutorial are provided online in the docs section.

Please notice that the Apache Zeta Components will only work on PHP 5.2.1 or higher. They can be used side-by-side with, for example, PEAR packages and the Zend Framework, which as well run on PHP >= 5.2.1.

Installation

There are three ways how to make Apache Zeta 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 Apache Zeta Components packaged in an archive
Get the latest sources from SVN

There is no release of the project source as Apache Zeta Components, yet. We are working on making a release possible. In the mean while, please use the PEAR packages provided by the old eZ Components PEAR channel on components.ez.no, or download the full library package from the old eZ Components website. Apache Zeta Components are fully API compatible with eZ Components!

Installing the Apache Zeta 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

The following instructions still refer to the eZ Components PEAR channel, since Apache Zeta Components did not roll a release, yet. Apache Zeta Components are fully API compatible with the old (discontinued) eZ Components library.

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 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 following instructions still refer to the eZ Components download page, since Apache Zeta Components did not roll a release, yet. Apache Zeta Components are fully API compatible with the old (discontinued) eZ Components library.

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. You just need to extract the package and adjust your include_path directive.

SVN

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

First, create a directory where you want the Apache Zeta Components to be placed.

Next, you should checkout the trunk, which contains the latest development sources. To checkout, do:

svn co https://svn.apache.org/repos/asf/incubator/zetacomponents/trunk

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

svn co https://svn.apache.org/repos/asf/incubator/zetacomponents/scripts

and execute it:

./scripts/setup-env.sh

This will create the symlinks for autoload, which will of course not work on Windows. For this platform, the alternative script:

scripts\setup-env.bat

will create copies of necessary files for autoload. Note that you will need to re-run this script whenever you performed SVN up (and new class have been added) or if you added new classes yourself. This step is not necessary on *nix systems.

Partial check out

A per component check out from SVN is of course also possible. 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 https://svn.apache.org/repos/asf/incubator/zetacomponents/scripts
svn co https://svn.apache.org/repos/asf/incubator/zetacomponents/trunk/Base trunk/Base

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

svn co https://svn.apache.org/repos/asf/incubator/zetacomponents/trunk/Mail 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:

./scripts/setup-env.sh

or:

scripts\setup-env.bat

Configuration

After installation of Apache Zeta 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 Apache Zeta 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 Apache Zeta 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 Apache Zeta Components. In case it is different, please set it at the top of your script with:

    <?php
    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:

    <?php
    set_include_path(
    '/path/to/ezcomponents-version' . PATH_SEPARATOR .  get_include_path()
);
    ?>

Autoload Environment

The PHP classes of Apache Zeta 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 Apache Zeta 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, if you require a custom autoload function
Bootstrap file, if you only use Apache Zeta autoloading
SPL autoload, if you need to register several autoload functions

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:

<?php
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, due to the PEAR directory structure:

PEAR Installer:
ezc/Base/base.php
Downloaded bundle and SVN:
Base/src/base.php

Boot strap

In case you only have to use autoload for the Apache Zeta 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:
<?php require 'ezc/Base/ezc_bootstrap.php'; ?>
Downloaded bundle and SVN:
<?php require 'Base/src/ezc_bootstrap.php'; ?>

ezc_bootstrap.php basically contains the code seen in the Normal Autoload section.

SPL

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:

<?php
spl_autoload_register( array( 'ezcBase', 'autoload' ) );
?>

This way, you can register additional autoload functions for your own application or additional libraries.

Worth knowing

In following, we present some additional information on Apache Zeta Components, which you should know when starting to work with the library.

Required extensions

Apache Zeta 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.

Some components provide different drivers, which use different extensions or external programs. You can choose one of these to make the component use the back end 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, Apache Zeta Components assume 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 Apache Zeta 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.

Conclusion

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

Resources

General information page
List of available components
Browse the eZ Components source code online
Issues of eZ Components development are being discussed in the eZ Components developers mailinglist