Date de publication: le mardi 19 février 2008 à 03h51
Dernière modification: par Pascal BOYER le jeudi 2 septembre 2010 à 11h35
« Article précédent: eZ Publish : mise à jour de 4.0.x vers 4.0.y

24/10/2008 10:08  

This section describes how to upgrade your existing eZ Publish 3.10.x installation to version 4.0.y. If you are upgrading from version 3.10.0 or earlier, you need to first upgrade to 3.10.1 before you can upgrade to 4.0. (Refer to either "Upgrading from 3.9.x to 3.10.y" or "Upgrading from 3.10.x to 3.10.y" depending on which version you are currently running.) 
Cet article décrit la mise à jour d'une version existante 3.10.x de eZ Publish vers une version 4.0.y. Si vous souhaitez faire une mise à jour depuis une version 3.10.0 ou antérieure alors vous devez procéder à la mise à jour vers la version 3.10.1 préalablement à une mise à jour vers une version 4.0.y. Référez-vous aux articles eZ Publish : mettre à jour de 3.9.x vers 3.10.y  ou eZ Publish : mettre à jour de 3.10.x vers 3.10.y  en fonction de la version de votre installation courante.

In order to benefit from the latest bug fixes, you should upgrade directly to the latest stable release in the 4.0 branch (4.0.1 at the time of writing). Refer to the changelogs and security advisories for more information about the issues that were fixed in the latest releases. Note that there is a significant problem with eZ Publish 4.0.0. More precisely, the "ezsmtp" class contains a bug that prevents the system from sending outgoing mails through an SMTP server. This bug was fixed in version 4.0.1. 
Afin de bénéficier des dernières corrections de bugs, vous devez faire une mise à jour directement vers la dernière version stable de la branche 4.0 (la version 4.0.1 à l'heure de rédaction de cet article). Référez-vous aux changelogs  et avis de sécurité  pour plus d'information sur les problèmes résolus par les dernières versions stables. Sachez que eZ Publish 4.0.0 est entaché d'un problème important, à savoir un bug  dans la classe ezsmtp empêchant le système d'envoyer des mails via un serveur SMTP. Ce bug est bien sûr résolu dans la version 4.0.1.

Note that in some cases, it is not possible or not recommended to upgrade from 3.10 to 4.0. Read the "Important notes" section in order to find out whether you can upgrade immediately or have to delay upgrading until new software releases are available. 
Retenez que dans certains cas il n'est pas possible ou non recommandé de passer d'une version 3.10 à une version 4.0. Lisez l'article Notes importantes  pour savoir si vous pouvez d'ors et déjà envisager ou non une telle mise à jour.

The upgrade procedure described below is generic and does not cover any specific cases (for example, running eZ Publish in a clustered environment). 
La procédure générique de mise à jour décrite ci-après ne couvre donc aucun cas spécifique (comme par exemple celui d'un environnement cluster).

Make sure that you have a working backup of the site before you do the actual upgrade. 
Assurez-vous d'être en possession d'une sauvegarde  fonctionnelle de votre site courant.

The procedure for upgrading directly from version 3.10.x to 4.0.y consists of the following steps: 
La procédure de mise à jour directe d'une version 3.10.x à une version 4.0.y consiste en les étapes suivantes:

1. Upgrading the distribution files to 4.0.y 
   Mettre à jour les fichiers de la version 3.10.x vers ceux de la version 4.0.y,
2. Upgrading the database to 4.0.y 
   Mettre à jour la base de données pour la rendre compatible avec la version 4.0.y de eZ Publish,
3. Running the system upgrade scripts for versions from 3.10.x to 4.0.y 
   Exécuter les scripts de mise à jour de la version 3.10.x vers 4.0.y,
4. Updating the system configuration 
   Mettre à jour la configuration du système,
5. Clearing the caches 
   Vider les caches.

Étape 1: Upgrading the distribution files / Mise à jour des fichiers de la distribution

The easiest way to upgrade the distribution files is to unpack eZ Publish 4.0.y to a separate directory and then copy the directories that contain site-specific files from the existing installation. Make sure that you copy the following directories: 
Le moyen le plus simple de mettre à jour les fichiers de la distribution consiste à extraire les fichiers de l'archive de eZ Publish 4.0.y dans un répertoire à part puis d'y copier les répertoires contenant les fichiers spécifiques de l'installation existante (celle à mettre à jour). Assurez-vous donc de copier, dans le répertoire de la version 4.0.y, les répertoires suivants du site existant:

• design/example
• design/example_admin
• var
• settings/siteaccess
• settings/override

Replace "example" and "example_admin" with actual names used by your siteaccesses. 
Remplacez example et example_admin par les vrais noms de vos siteaccess

Custom extensions / Extensions personnelles

If you are using custom extensions, the subdirectories inside the "extension" directory will also have to be copied. However, make sure that you do not overwrite any extensions that come with eZ Publish (currently "ezdhtml", "ezodf" and "ezurlaliasmigration"). 
Si vous utilisez des extensions personnelles, les sous-répertoires du répertoire extension devront également être copiés. Cependant, assurez-vous de n'écraser aucune des extensions présentes par défaut dans eZ Publish (à savoir les extensions ezdhtml, ezodf et ezurlaliasmigration).

If you are using the Website Interface front-end, you will need to upgrade the extension to version 1.3 as earlier versions are not compatible with eZ Publish 4. Refer to the "Upgrading the Website Interface" chapter of the Website interface installation guide for more information and instructions. 
Si vous utilisez l' interface Website  vous devez mettre à jour cette extension (website) vers la version 1.3 puisque les versions antérieures ne sont pas compatibles avec la version 4.0 de eZ Publish. Référez-vous au chapitre Upgrading the Website Interface du guide Website interface installation  pour de plus amples informations.

Switching to PHP 5 / Passer à PHP 5

After upgrading the distribution files, switch your site to use PHP 5 (make sure all the requirements are met). 
Après avoir mis à jour les fichiers de la distribution, vous devez faire en sorte que votre site utilise PHP 5 (assurez-vous que tous les prérequis  soient remplis).

Note that you need to set the "date.timezone" value in the "php.ini" configuration file. If this setting is not specified, you will most likely receive error messages like "It is not safe to rely on the system's timezone settings" when running eZ Publish on PHP 5. The following example shows how the corresponding line in "php.ini" looks like: 
Retenez que vous devez régler la valeur du paramètre date.timezone  du fichier de configuration php.ini. Si ce paramètre n'est pas renseigné, vous obtiendrez vraisemblablement des messages d'erreur du type It is not safe to rely on the system's timezone settings lorsque vous ferrez tourner eZ Publish avec PHP 5. L'exemple ci-dessous montre à quoi doit ressembler la ligne du fichier php.ini:

date.timezone = <timezone>

Refer to the PHP documentation for the list of supported timezones. Don't forget to restart Apache after editing "php.ini". 
Référez-vous à la documentation de PHP  pour connaître la liste des fuseaux horaires supportés. N'oubliez pas de redémarrer Apache après avoir modifié le fichier php.ini

Étape 2: Upgrading the database / Mise à jour de la base de données

The following text describes how to upgrade your eZ Publish database from version 3.10.x to 4.0.y. 
Ce qui suit décrit la procédure de mise à jour de la base de données d'une version 3.10.x vers une version 4.0.y de eZ Publish.

Switching to UTF-8 / Passer à UTF-8

eZ Publish 4 requires UTF-8 as the character set. If your site makes use of another character set, you must switch to UTF-8. To find out about the current character set in your database, you can run the following command using the MySQL command-line tool (replace "db_name" with the actual name of your database): 
eZ Publish 4 requière le jeu de caractères UTF-8 et si votre site en utilise un autre alors vous devez passer à UTF-8. Pour contrôler le jeu de caractères utilisé par votre base de données, vous pouvez exécuter la ligne de commande suivante qui utilise l' outil de ligne de commande de MySQL  (remplacez « db_name» par le vrai nom de votre base de données):

mysql> SHOW CREATE DATABASE db_name;

PostgreSQL users can view the list of available databases along with their character sets by running the following command from within the system shell: 
Les utilisateurs de PostgreSQL peuvent afficher la liste des bases de données et les jeux de caractères associés avec la ligne de commande suivante:

psql -l

In eZ Publish 4.0.1, the "bin/php/ezconvertdbcharset.php" script was added in order to convert databases to use UTF-8. (Refer to the developer documentation for more information and troubleshooting tips). 
Le script bin/php/ ezconvertdbcharset.php a été ajouté à eZ Publish 4.0.1 afin de convertir les bases de données à l'usage de UTF-8 (Référez-vous à la documentation des developpeurs  pour de plus amples informations et conseils de dépannage).

This script should be run once for each database, specifying one siteaccess per database. If you only have a public and an administration siteaccess that share the same database (which is the most typical/usual case), you only need to run the script for one of the siteaccesses. If the siteaccess isn't specified, the default siteaccess will be used. 
Ce script doit être exécuté une fois pour chaque base de données et en spécifiant un siteaccess pour chacune d'elles. Si vous n'avez qu'un siteaccess public et d'administration partageant la même base de données (ce qui reste le cas le plus fréquent), vous ne devez exécuter le script que pour l'un des deux siteaccess. Et si ce dernier n'est pas mentionné alors le siteacces par défaut  sera utilisé.

Before running the script, make sure that eZ Publish knows the current character set in the database. Basically, the script will rely on the "Charset" setting located in the "[DatabaseSettings]" section of "settings/override/site.ini.append.php" or "settings/siteaccess/<your_siteacess>/site.ini.append.php". If this setting is empty, the value of the "Charset" setting located in the [CharacterSettings] section of "i18n.ini" (or an override) will be used. 
Avant d'exécuter le script, assurez-vous que eZ Publish connaisse le jeu de caractères courant associé à votre base de données. Le script se base sur le paramètre Charset  de la section [DatabaseSettings] du fichier settings/override/ site.ini.append.php ou settings/siteaccess/<votre_siteacess>/ site.ini.append.php. Si ce paramètre est vide, c'est la valeur du paramètre Charset  de la section [CharacterSettings] du fichier i18n.ini (ou de l'une de ses surcharges) qui est utilisée.

The following example shows how to run the script: 
L'exemple suivant explique comment exécuter ce script:

1. Navigate into the eZ Publish 4.0.1 directory. 
   Placez-vous dans le répertoire d'installation de eZ Publish 4.0.1
2. Run the script (replace "example" with the actual name of your siteaccess): 
   Exécutez le script (remplacez « example» par le vrai nom de votre siteaccess):

php bin/php/ezconvertdbcharset.php -s example

The script will convert the database to use UTF-8 as the character set. 
Le script convertira la base de données afin qu'elle utilise le jeu de caractères UTF-8.

After running the script, make sure that eZ Publish knows about the database's new character set by editing the setting mentioned above: 
Après l'exécution du script, assurez-vous, en éditant le paramètres mentionné ci-dessus, que eZ Publish reconnaisse bien le nouveau jeu de caractères:

Charset=utf-8

Switching to InnoDB (MySQL only) / Passer au moteur de stockage InnoDB (uniquement pour MySQL)

If you are using MySQL, note that the recommended storage engine is InnoDB. This storage engine is used by default during the installation process when the setup wizard initializes the database structure for eZ Publish. In addition, InnoDB will most likely be required for future versions of eZ Publish to run on MySQL. Contact your database administrator if you are unsure about whether InnoDB is available on your server. 
Retenez que si vous utilisez MySQL alors le moteur de stockage recommandé est InnoDB . Ce dernier est utilisé par défaut lors du processus d'installation lorsque l'assistant d'installation initialise la structure de la base de données de eZ Publish. Par ailleurs, InnoDB sera certainement requis pour les futures versions de eZ Publish liées à un serveur MySQL. En cas de doute, contactez l'administrateur de votre base de données pour savoir si InnoDB est disponible sur votre serveur.

In eZ Publish 4.0.1, the database upgrade scripts use the InnoDB storage engine when creating new tables. Before running these scripts, it is recommended (but not required) to make sure that all existing tables in your database use InnoDB. If you want to use the MyISAM (or another) storage engine instead, all existing tables in your database must use this engine. In addition, you will have to replace "InnoDB" with "MyISAM" in the database upgrade scripts before running them. Read the following text for more detailed instructions. 
Avec eZ Publish 4.0.1, les scripts de mise à jour de la base de données utilisent le moteur de stockage InnoDB lors de la création de nouvelles tables. Avant d'exécuter ces scripts, il est recommandé (mais non obligatoire) de s'assurer que toutes les tables de votre base de données utilisent InnoDB. Si vous souhaitez utiliser le moteur de stockage MyISAM (ou tout autre moteur) alors toutes les tables de votre base de données doivent l'utiliser. De plus, vous devrez remplacer « InnoDB» par « MyISAM» dans les cripts de mise à jour avant de les exécuter. Les lignes suivantes vous apportent des instructions détaillées.

To find out about the current storage engine in your database, navigate into the eZ Publish directory and run the "bin/php/ezconvertmysqltabletype.php" script with the "--list" parameter: 
Pour connaître le moteur de stockage utilisé par votre base de données, placez-vous dans le répertoire d'installation de eZ Publish puis exécutez le script bin/php/ ezconvertmysqltabletype.php avec le paramètre --list:

php bin/php/ezconvertmysqltabletype.php --list

The script will output the list of tables in the database along with the name of the storage engine for each table. 
Ce script va renvoyer la liste des tables de la base de données ainsi que le nom du moteur de stockage associé à chacune d'elles.

With the command above, the script will check the table types in the database that is used by the default siteaccess. If your site makes use of two or more databases, you need to run the script once for each database, specifying one siteaccess per database. Use the "-s" parameter to specify the target siteaccess as shown below (replace "example" with the actual name of your siteaccess): 
Avec la ligne de commande ci-dessus, le script va rechercher, dans la base de données, les types de tables utilisées par le siteacces par défaut . Si votre site utilise deux bases de données ou plus, vous devez alors exécuter ce script pour chacune d'elles en spécifiant un siteaccess par base de données. Utilisez, comme le montre l'exemple ci-dessous, le paramètre -s pour indiquer le siteaccess cible (remplacez « example» par le vrai nom de votre siteaccess):

php bin/php/ezconvertmysqltabletype.php --list -s example

If all tables in your eZ Publish database use the InnoDB storage engine, no changes are needed. If some tables use MyISAM or another storage engine, it is recommended (but not required) to convert them to InnoDB. To do this, run the script with the "--newtype" parameter as shown below: 
Si toutes les tables de votre base de données utilisent le moteur InnoDB, aucune modification n'est alors nécessaire. Si quelques tables utilisent MyISAM ou un autre moteur, il est alors recommandé (mais non obligatoire) de les convertir à InnoDB. Pour cela, exéutez le script, comme indiqué ci-dessous, avec le paramètre --newtype:

php bin/php/ezconvertmysqltabletype.php --newtype=innodb -s example

The script will convert all tables in your database to InnoDB. Note that the script will automatically skip the tables that already use the InnoDB storage engine from before (if any). 
Ce script convertira toutes les tables de votre base de données afin qu'elles utilisent InnoDB. Retenez que ce script n'aura aucune action sur les tables utilisant déjà le moteur InnoDB.

You can also convert tables individually by using the following SQL query for each table: 
Vous pouvez également convertir individuellement chaque table grâce à la requête SQL suivante:

ALTER TABLE <name_of_table> TYPE = innodb;

If you wish to use a storage engine other than InnoDB, make sure that all tables in your database use this engine. In addition, you will have to change the engine specified in the first line of the database upgrade scripts before running them (otherwise, the upgrade will leave you with a mix of table types). 
Si vous envisagez d'utiliser un autre moteur de stockage que InnoDB, assurez-vous que toutes les tables de votre base de données utilisent ce moteur. De plus, vous devrez modifier le nom du moteur de stockage spécifié dans la première ligne des scripts de mise à jour avant d'exécuter ces derniers (sous peine de vous retrouver, la mise à jour terminée, avec un mélange de types de tables)

You will find the database upgrade scripts in the "update/database/mysql/4.0/" directory. Each database upgrade script that creates new tables contains the following line in the beginning: 
Vous trouverez les scripts de mise à jour de la base de données dans le répertoire update/database/mysql/4.0/. Chaque script créant de nouvelles tables contient, au début, la ligne suivante:

SET storage_engine=INNODB;

Before you run such a script, replace "INNODB" with the name of your storage engine. For example, if all existing tables in your database use MyISAM, you need to modify the first line as shown below: 
Avant d'exécuter ces scripts, remplacez INNODB par le nom du moteur de stockage que vous souhaitez utiliser. Par exemple, si toutes les tables utilisent MyISAM, modifiez ainsi cette première ligne:

SET storage_engine=MYISAM;

This will make the database upgrade script use MyISAM instead of InnoDB when creating new tables. 
Ainsi, le script de mise à jour de la base de données utilisera, lors de la création des nouvelles tables, le moteur MyISAM en lieu et place du moteur InnoDB.

Running the database upgrade scripts / Exécuter les scripts de mise à jour de la base de données

To upgrade your database from version 3.10.1 to 4.0.1, you need to navigate into the eZ Publish 4.0.1 directory and run the following database upgrade scripts one after another: 
Pour mettre à jour votre base de données d'une version 3.10.1 à une version 4.0.1 vous devez vous placer à la racine du répertoire d'installation de eZ Publish 4.0.1 puis exécuter les scripts suivants les uns après les autres:

1. dbupdate-3.10.0-to-4.0.0.sql
2. dbupdate-4.0.0-to-4.0.1.sql

Note that some of the database changes from eZ Publish 3.10.0 to 4.0.1 have been included in the 3.10.1 release as well. This means that you need to skip some parts of the database upgrade scripts when upgrading from version 3.10.1 to 4.0.1. These are marked with "from 3.10.1" comments in the ".sql" files. 
Retenez que certaines modifications apportées par le passage de eZ Publish 3.10.0 à 4.0.1 ont été incluses dans la version 3.10.1, ce qui signifie que vous ne devez pas prendre en compte certaines parties de ces scripts lors du passage de 3.10.1 à 4.0.1. Ces parties sont marquées de commentaires from 3.10.1 dans les fichier .sql.

MySQL

The database upgrade scripts are located in the "update/database/mysql/4.0/" directory of your eZ Publish installation. Each of these scripts can be launched using the following shell command (replace "script_name" with the actual name of the script): 
Les scripts de mise à jour sont placés dans le répertoire update/database/mysql/4.0/. Chacun de ces scripts peut être exécuté par la ligne de commande suivante (remplacez script_name par le vrai nom du script):

mysql -u <username> -p<password> <database> < update/database/mysql/4.0/script_name.sql

PostgreSQL

The database upgrade scripts are located in the "update/database/postgresql/4.0/" directory of your eZ Publish installation. Each of these scripts can be launched using the following shell command (replace "script_name" with the actual name of the script): 
Les scripts de mise à jour sont placés dans le répertoire update/database/postgresql/4.0/. Chacun de ces scripts peut être exécuté par la ligne de commande suivante (remplacez « script_name» par le vrai nom du script):

psql -d <database> -U <dbowner> < update/database/mysql/4.0/script_name.sql

Étape 3: Running the system upgrade scripts / Exécuter les scripts de mise à jour du système

You are not required to run any system upgrade scripts when upgrading from 3.10.1 to 4.0.1. 
Vous n'avez à exécuter aucun script de mise à jour lors du passage d'une version 3.10.1 à une version 4.0.1

Étape 4: Updating the system configuration / Mettre à jour la configuration du système

In eZ Publish versions prior to 4.0.0, the order of design resourses used by the "ezdesign" and "ezimage" template operators was not the same as used by the "include" template function and eZTemplate::fetch(). This might lead to problems with overriding templates in extensions (refer to http://issues.ez.no/9595 for more information). This issue was fixed in eZ Publish 4.0.0. 
Dans les versions antérieures à la version 4.0.0, l'ordre des designs utilisé par les opérateurs de template ezdesign  et ezimage  n'était pas le même que celui utilisé par la fonction de template include  et par eZTemplate::fetch(). Cela pouvait conduire à des problèmes avec les templates de surcharge des extensions (référez-vous à la page http://issues.ez.no/9595  pour de plus amples informations). Ce bug est corrigé dans la version 4.0.0 de eZ Publish.

In eZ Publish 4.0, templates that override default ones must be placed in the "override/templates" directory of your design. If you are not sure about the location of override templates in your eZ Publish installation, review the settings in your "override.ini.append.php" configuration file. (Refer to "The template override system" for more information.) The names of the override templates are specified using the "MatchFile" directive, which makes it possible to find the corresponding files on a file system. 
Dans eZ Publish 4.0, les templates de surcharge doivent être placés dans le répertoire override/templates/ du désign utilisé. Si vous avez des doutes sur l'emplacement des templates de surcharge de votre installation, consultez les paramètres de votre fichier de configuration override.ini.append.php. (référez-vous à la documentation sur le système de surcharge de template  pour de plus amples informations). Les noms des templates de surcharge sont spécifiés par la directive MatchFile qui vous indiquera l'emplacement, dans le système, des fichiers correspondants.

Note that custom templates that are not connected with the override system must be placed in the "templates" directory of a custom design. 
Retenez que les templates personnalisés qui ne sont pas connectés au système de surcharge doivent être placés dans le répertoire templates du design.

Étape 5: Clearing the caches / Vider les caches

Whenever an eZ Publish solution is upgraded, all caches must be cleared in a proper way. This should be done from within a system shell: 
Chaque fois qu'un site eZ Publish est mis à jour, tous les caches doivent être correctement vidés avec la commande suivante:

1. Navigate into the eZ Publish 4.0 directory. 
   Placez-vous dans le répertoire d'installation de eZ Publish 4.0
2. Run the script using the following shell command: 
   Exécutez le script pour vider les caches:

php bin/php/ezcache.php --clear-all --purge

Purging ensures that the caches are physically removed. When the "--purge" parameter is not specified, the caches will be expired but not removed (refer to this page for more information). 
Vider les caches permet de s'assurer qu'ils ont été physiquement supprimés. Sans l'option --purge, les caches expireront mais ne seront pas supprimés (repportez-vous à cette page  pour de plus amples informations).

Sometimes the script is unable to clear all cache files because of restrictive file/directory permission settings. Make sure that all cache files have been cleared by inspecting the contents of the various cache subdirectories within the "var" directory (typically the "var/cache/" and "var/<name_of_siteaccess>/cache/" directories). If there are any cache files left, you need to remove them manually. 
Il arrive que le script ne puisse vider correctement tous les caches en raison de droits d'accès insuffisants sur des fichiers et répertoires. Assurez-vous qu'ils soient vidés en contrôlant le contenu des nombreux sous-répertoires de cache du répertoire var/ (typiquement, les répertoires var/cache/ et var/<nom_du_siteaccess>/cache/). S'il reste des fichiers cachés supprimez-les manuellement.

Commentaires