Installer eZ Components

Date de publication: le vendredi 9 décembre 2011 à 12h23
Dernière modification: par Pascal BOYER le vendredi 9 décembre 2011 à 23h46

Introduction à eZ Components

Source de l'article contrôlée le 10-12-2011

Ndt: vous pouvez également consulter l'article: Installer eZ Components : détails de l'installation sous Linux

An Introduction to eZ Components / Introduction à 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.
Ce guide propose un aperçu de l'utilisation de eZ Components avec PHP 5. Ce sont des blocs orientés objet réutilisables destinés à accélérer le développement et le déploiement d'applications professionnelles écrites en PHP 5

What is it? / Qu'est-ce donc ?

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.
eZ Components est un ensemble de librairies PHP générales prêtes à l'emploi (???). En tant que blocs indépendants de haute qualité destinés au développement d'applications PHP, eZ Components permet à la fois d'accélérer le développement d'applications et de réduire les risques afférents. Une application peut utiliser aussi simplement un ou plusieurs composants dans la mesure où ils adhèrent tous aux mêmes conventions de nommage et suivent tous la même structure. Actuellement, tous les composants sont basés sur PHP 5.2.1.

The eZ Components in a nutshell:
eZ Components en bref:

• Designed for enterprise PHP application development
  Créés pour le développement d'applications professionnelles en PHP

• Open source and licensed under the New BSD license
  Open source et sous Licence New BSD

• Clear intellectual property (IP) rights
  Exempts de droits de Propriété Intellectuelle

• Thoroughly documented
  Entièrement documentés

• Developed, supported and maintained by eZ systems
  Développés, supportés et maintenus par 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.
Vous trouverez des informations générales supplémentaires sur eZ Components sur la page qui lui est dédiée. Cette page présente également la liste des composants disponibles. Les aspects techniques liés à la création de la librairie sont expliqués sur la page dédiée aux détails techniques.

Usage / Utilisation

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.
Le but de eZ Components est de masquer la complexité des routines qui se trouvent derrière une API orientée objet. Les tâches courantes de programmation deviennent plus faciles et les risques liés au développement d'applications se trouvent minimisés puisque la complexité est elle-même réduite. En général, votre processus de développement devient plus efficient avec eZ Components.

For example, sending an email with the help of the eZ Mail component, looks like this:
Par exemple, le code d'envoi d'un e-mail basé sur l'utilisation du composant eZ Mail ressemble à ceci:

<?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.
Vous devez bien sûr modifier l'adresse IP du serveur SMTP ( smtp.example.com) et redéfinir à votre convenance, dans le code ci-dessus, l'adresse e-mail. D'autres exemples de code sont disponibles dans le répertoire /doc de chaque composant eZ Components.

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.
Retenez que les composants eZ ne fonctionnent qu'avec une version 5.2.1 ou supérieure de PHP et qu'ils peuvent être utilisés conjointement aux packages PEAR utilisant également une version 5.2.1 ou supérieure de PHP.

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:
Pour connaître les trois façons d'installer eZ Components dans votre environnement PHP et avant de vous lancer dans la phase pratique, lisez l'intégralité du présent article:

• Use PEAR Installer for convenient installation via command line
  Installation en ligne de commande avec PEAR Installer,

• Download eZ components packaged in an archive
  Téléchargement d'une archive contenant l'ensemble des composants eZ,

• Get the latest sources from SVN
  Récupération, via SVN, de la dernière version des sources.

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.
L'installation des composants eZ à l'aide de PEAR Installer est fortement recommandée puisqu'elle représente la technique la plus pratique et la plus sûre. Bien que les instructions ci-après concernent les systèmes Linux, elles sont tout à fait adaptées à ceux qui travaillent dans un environnement PHP sous windows (ils devront simplement adapter les chemins en conséquence).

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:
Après avoir installé une version 5.2.1 ou supérieure de PHP, vous disposerez automatiquement de PEAR Installer et n'aurez plus qu'à lancer les commandes suivantes:

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: 
Cette commande indique à PEAR Installer de se connecter au serveur components.ez.no hébergeant les composants:

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/
Cette dernière commande permet de télécharger et d'extraire les composants dans le répertoire où sont déjà placés les packages PEAR. Les composants seront en fait placés dans un sous-répertoire ezc/ du répertoire d'installation de PEAR.

ndt: cette opération prend du temps car le nombre de composants téléchargés, désarchivés puis installés avoisine 40.

In case you already have installed the components before, you can simply do:
Si vous avez déjà installé les composants, procédez simplement à leur mise à jour:

pear upgrade ezc/eZComponents

Download of Archives / Télécharger les 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.
Les paquets eZ Components sont disponibles en téléchargement sous forme d'archives compressées .tar.bz2 ou .zip à partir de la page de téléchargement . Ces archives incluent toujours toutes les librairies.

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.
Si vous souhaitez travailler avec la dernière version de développement des composants, vous pouvez la récupérer depuis SVN. Pour cela, procédez dans l'ordre suivant:

First, create a directory where you want the eZ components to be placed.
Tout d'abord, créez le répertoire dans lequel vous placerez les composants.

Next, you should checkout the tree. To checkout, do:
Récupérez ensuite l'arborescence:

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:
Lorsque vous travaillez avec une version SVN des composants, il est important de paramétrer leur environnement. Pour cela, récupérez le script:

svn co http://svn.ez.no/svn/ezcomponents/scripts

and execute it:
puis exécutez-le:

./scripts/setup-env.sh

This will create the symlinks for autoload, which will of course not work on Windows.
Cela créera les liens symboliques pour la fonction autoload (qui bien sûr ne fonctionne pas sous windows).

From version 1.1 of the components there is also a script for Windows. Here you need to execute the following script instead:
Cependant, depuis la version 1.1 des composants il existe également un script pour windows. Vous devez alors exécuter à la place ce script-ci:

scripts\setup-env.bat

This will create copies of necessary files for autoload.
Cette commande créera une copie des fichiers nécessaires à autoload.

Partial check out / Récupération partielle

It is of course also possible to check out from SVN per component. Again, you first have to create a directory again, something like:
Il est également possible de récupérer depuis SVN chaque composant individuellement. A nouveau, vous devez tout d'abord créer un répertoire ressemblant à ceci:

mkdir /tmp/mydir/ezc

cd /tmp/mydir/ezc

Inside this directory, create the trunk directory:
Créez dans ce répertoire le répertoire trunk:

mkdir trunk

Then check out the scripts directory and Base component:
Récupérez le répertoire des scripts puis le composant Base:

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:
Vous pouvez dès lors récupérer chaque composantdont vous avez besoin avec une commande comme celle-ci:

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).
Assurez-vous de récupérer toutes les dépendences nécessaires si elles existent. Le fichier DEPS, situé à la racine de chaque composant, vous permet de savoir si ce dernier a des dépendences (par exemple, trunk/Mail/DEPS).

After you've checked out all components, run the setup-env script again:
Après avoir récupéré tous les composants, exécutez à nouveau le script setup-env:

./scripts/setup-env.sh

or/ou:

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:
Une fois l'installation des composants terminée, et quelque soit la méthode utilisée, vous devez procéder à quelques configurations:

• Adjust the include path to have the eZ Components classes available via PHP
  Adapter le chemin d'inclusion afin que les classes eZ Components soient disponibles pour PHP,

• Create the autoload environment for calling eZ Components from your script
  Créer l'environnement de la fonction autoload pour pouvoir appeler eZ Components à partir de votre script.

Include Path / Chemin d'inclusion

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.
Le chemin d'inclusion de PHP doit pointer vers le répertoire contenant les composants eZ. Vous pouvez le paramétrer soit dans votre fichier de configuration php.ini soit avec la fonction set_include_path() définie dans votre 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:
Si vous avez installé les composants à l'aide de PEAR Installer alors, dans la plupart des cas, vous n'avez aucune modification à apporter puisque le chemin d'inclusion de PHP pointera déjà par défaut vers le répertoire:

/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:
dans lequel PEAR Installer a installé les composants eZ. Dans tous les autres cas, définissez ainsi le chemin correct au tout début de votre script:

<?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:
Si vous avez opté pour l'installation via le téléchargement d'une archive ou via SVN, paramétrez le chemin d'inclusion pour qu'il pointe vers la racine de l'archive, par exemple, comme ceci:

<?php
set_include_path( "/path/to/ezcomponents-1.0rc1:" . ini_get( "include_path" ) );
?>

Autoload Environment / Environnement de la fonction autoload

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.
Les classes PHP des composants eZ peuvent être efficacement utilisées dans votre script PHP. Pour cela il n'est pas nécessaire d'employer les déclarations require ou include puisque le mécanisme autoload intégré localise les classes à votre place lorsque vous les instanciez ou les utilisez.

There are three different ways of getting the autoload mechanism going.
Il existe trois façons différentes de faire fonctionner (???) le mécanisme autoload.

Normal Autoload / Autoload normal

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:
Avec la première méthode, vous avez besoin de la classe ezcBase et de définir votre propre mécanisme autoload. Vous devez ajouter le code suivant au sommet de votre script PHP:

<?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:
Soyez attentifs à la déclaration require_once() qui diffère en fonction de la méthode d'installation:

• PEAR Installer:

ezc/Base/base.php

• Downloaded bundle and SVN:
  Paquet téléchargé et 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.
Dans le cas où vous ne devez utiliser autoload que pour les composants eZ et non pour les applications ou pour d'autres librairies, vous pouvez simplement inclure le fichier ezc_bootstrap.php. A nouveau, le fichier requis dépend de la méthode d'installation.

• PEAR Installer:

<?php
require 'ezc/Base/ezc_bootstrap.php';
?>

• Downloaded bundle and SVN:
  Paquet téléchargé et 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:
SPL (Standard PHP Library / bibliothèque PHP Standard) permet également de paramétrer l'auto-chargement par le biais de la fonction spl_autoload_register . Dans ce cas, vous avez besoin, comme pour la méthode Autoload normal, de la classe base mais au lieu de définir une fonction __autoload() vous écrivez:

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

Worth knowing / Bon à savoir

Required extensions / Extensions requises

eZ Components require as few extensions by default. Required by all components are:
eZ Components ne nécessite que quelques extensions par défaut. Celles nécessaires à tous les composants sont:

• SPL

• 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.
Les extensions ci-dessus sont toutes deux livrées avec PHP et activées par défaut. Par conséquent, à moins de les supprimer expressément de votre installation PHP, vous n'avez pas à vous préoccuper de leur présence.

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.
Des composants particuliers peuvent requérir des extensions supplémentaires comme par exemple les composants liés à la base de données (Database, DatabaseSchema, PersistentObject) qui s'appuient sur les PDO disponibles (PHP Data Objects). La documentation des composants indique lorsque des extensions particulières sont nécessaires. Vous trouverez un aperçu complet dans la documentation

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.
Certains composants fournissent des drivers différents utilisant des extensions ou des programmes externes différents. Vus pouvez choisir l'un d'eux afin que le composant utilise le backend que vous avez rendu disponible. Un exemple est le composant Graph qui peut utiliser différentes extensions pour rendre des graphes dans différents formats.

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.
Sauf indication contraire de la documentation, eZ Components suppose que vous fournissiez des données encodées en UTF-8. De même, la sortie et les valeurs retournées générées par chaque composant seront également encodées en UTF-8.

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.
Si vous devez travailler avec des données présentant des encodages divers, assurez-vous de les convertir préalablement en UTF-8 avant de les transmettre aux composants.

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.
Afin de réaliser des opérations binaires en toute sécurité, l'extension iconv est utilisée en interne par eZ Components. Comme nous le mentionnons plus haut, cette extension est fournie avec PHP et activée par défaut. Nous vous recommandons donc l'usage de cette extension pour les conversions d'encodage.

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.
Certains composants vous permettent de travailler avec des encodages autres que UTF-8. C'est le cas, par exemple, du composant Mail qui autorise l'utilisation de différents encodages en parallèle. De telles exceptions à la règle sont toujours clairement indiquées par la documentation.

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!
Vous disposez à présent d'un environnement vous permettant d'intégrer, dans le cadre du développement d'applicactions écrites en PHP 5.2.1, des composants orientés objet. En plus d'utiliser les eZ Components pour le développement de vos applications, vous pouvez étudier leur code source afin de comprendre comment eZ Systems utilise les nouvelles fonctions de PHP 5 pour la programmation orientée objet dans les composants. Allez-y, éclatez-vous !

Commentaires