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.

.. _`New BSD License`: /overview/license
.. _`eZ Systems`: http://ez.no

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(), "\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.

Installation
------------

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

.. _`PEAR Installer`: http://pear.php.net
.. _download: /download

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 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/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.

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 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


Configuration
-------------

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

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

* 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 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
```
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' ) );
	?>

.. _spl_autoload_register: http://php.net/manual/en/function.spl-autoload-register.php


Worth knowing
-------------

Required extensions
~~~~~~~~~~~~~~~~~~~

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

- SPL_
- iconv_

.. _SPL: http://php.net/spl
.. _iconv: http://php.net/iconv

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__.

.. _Database: /s/Database
.. _DatabaseSchema: /s/DatabaseSchema
.. _PersistentObject: /s/PersistentObject
.. _PDO: http://php.net/pdo
__ /introduction/requirements

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.

.. _Graph: /s/Graph

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. 

.. __: http://en.wikipedia.org/wiki/Utf-8

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.

.. _Mail: http://ezcomponents.org/s/Mail

Conclusion
----------

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!

Resources
---------

* `General information page <http://ez.no/products/ez_components>`_
* `List of available components </overview>`_
* Browse the eZ Components `source code online <http://svn.ez.no/svn/ezcomponents>`_
* Issues of eZ Components development are being discussed in the `eZ Components developers mailinglist </support/mailinglist>`_


..
   Local Variables:
   mode: rst
   fill-column: 79
   End: 
   vim: et syn=rst tw=79