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.
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:
<?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 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.
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
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 http://svn.ez.no/svn/ezcomponents/trunk
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.
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 http://svn.ez.no/svn/ezcomponents/scripts
svn co http://svn.ez.no/svn/ezcomponents/trunk/Base trunk/Base
Then you can check out each component that you want with a command like:
svn co http://svn.ez.no/svn/ezcomponents/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
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
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
set_include_path( "/path/to/root/pear/directory:" . ini_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-1.0rc1:" . ini_get( "include_path" ) );
?>
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.
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:
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:
<?php
require 'ezc/Base/ezc_bootstrap.php';
?>
Downloaded bundle and SVN:
<?php
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:
<?php
spl_autoload_register( array( 'ezcBase', 'autoload' ) );
?>
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!
