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

__ http://www.apache.org/licenses/LICENSE-2.0
__ http://ez.no

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

__ /zetacomponents/documentation/trunk.html

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

__ http://pear.php.net
__ /zetacomponents/download

.. note:: 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!**

          __ http://ezcomponents.org/download

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

.. note:: 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
~~~~~~~~~~~~~~~~~~~~

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

__ http://ezcomponents.org/download

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.

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

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:

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

.. _Database: http://zetac.org/Database
.. _DatabaseSchema: http://zetac.org/DatabaseSchema
.. _PersistentObject: http://zetac.org/PersistentObject
.. _PDO: http://php.net/pdo

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.

.. _Graph: http://zetac.org/Graph

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. 

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

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.

.. _Mail: http://zetac.org/Mail

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

__ /zetacomponents/news.html
__ /zetacomponents/documentation/trunk.html
__ https://fisheye6.atlassian.com/browse/zetacomponents/trunk/
__ /zetacomponents/community/index.html#mailing-lists

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