from 3.8.x to 3.9.0
This section describes how to upgrade your existing eZ Publish 3.8.x installation to version 3.9.0. If you are upgrading from a version prior to eZ Publish 3.8.0, you need to first upgrade to 3.8.0 before you can upgrade to 3.9.0.
Important note
Before continuing, note that it is recommended to upgrade directly to the latest stable release in the 3.9 branch. (Refer to "Upgrading from 3.a.b to 3.x.y" and "Upgrading from 3.9.x to 3.9.y" to learn how this can be done.) Mainly, there are two reasons for this:
- The "correctxmltext.php" upgrade script in eZ Publish 3.9.0 contains a bug. It makes the script crash. This issue was fixed in 3.9.1. Refer to http://issues.ez.no/9952 for more information.
- There is a significant problem with eZ Publish 3.9.0-3.9.2. More precisely, the discount functionality of the shop module contains a security vulnerability. The issue has been fixed in version 3.9.3. Refer to the announcement and the upgrade instructions for details.
Overview
Make sure that you have a working backup of the site before you do the actual upgrade. The upgrade procedure consists of the following steps:
- Upgrading the distribution files to 3.9.0
- Upgrading the database to 3.9.0
- Running the 3.9.0 upgrade scripts
- Updating the system configuration
- Clearing the caches
Step 1: Upgrading the distribution files
The easiest way to upgrade the distribution files is to unpack eZ Publish 3.9.0 to a directory and then copy the directories that contain site-specific files from the existing installation. Make sure that you copy the following directories:
- design/example
- design/example_admin
- var
- settings/siteaccess
- settings/override
Replace "example" and "example_admin" with actual names used by your siteaccesses.
Custom extensions
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 (for example the "PayPal" extension).
Step 2: Upgrading the database
The following text describes how a 3.8.0 database can be upgraded to 3.9.0. Before reading on, note that some of the database changes from eZ Publish 3.8.0 to 3.9.0 have been included in eZ Publish versions 3.8.1 and 3.8.5 as well. If you are upgrading from a version later than 3.8.0, it is recommended to skip some parts of the database upgrade scripts (the sections that should be skipped are marked with "from 3.8.1" or "from 3.8.5" comments in the ".sql" file).
MySQL
- Navigate into the eZ Publish 3.9.0 directory.
- Run the database upgrade script:
mysql -u <username> -p<password> <database> < update/database/mysql/3.9/dbupdate-3.8.0-to-3.9.0.sql
Note that the CREATE TABLE statements in the database upgrade script do not specify which storage engine to use (no ENGINE or TYPE option), and thus the default storage engine will be used. Normally, it is MyISAM (starting from MySQL v.3.23). If you are using InnoDB, make sure the default storage engine is set to InnoDB before you run the database upgrade script (refer to MySQL documentation for information about how to set the default engine). If you were not able to change the MySQL configuration on your server, and the upgrade left you with a mix of table types, you can convert the newly created tables to InnoDB using the following SQL queries:
ALTER TABLE ezcontentobject_trash TYPE = innodb; ALTER TABLE ezcontentclass_name TYPE = innodb; ALTER TABLE ezsearch_search_phrase TYPE = innodb; ALTER TABLE ezsearch_return_count TYPE = innodb;
It is also possible to use the "bin/php/ezconvertmysqltabletype.php" script for database conversion.
PostgreSQL
- Navigate into the eZ Publish 3.9.0 directory.
- Run the database upgrade script:
psql -d <database> -U <dbowner> < update/database/postgresql/3.9/dbupdate-3.8.0-to-3.9.0.sql
Step 3: Running the 3.9.0 upgrade scripts
The 3.9.0 version of eZ Publish introduces a couple of new features. In order to make sure that your site is compatible with these features, you'll have to run a couple of upgrade scripts.
Translating names of classes and class attributes
In eZ Publish 3.9, a new feature has been added to the multi-language functionality that makes it possible to translate names of the eZ Publish content classes / class attributes (see this page for more information). In order to make sure that your site is compatible with this new functionality, you will have to run the "updateclasstranslations.php" script. This step must be done even though your site has only one language.
The "updateclasstranslations.php" script should be run for all siteaccesses that use different databases. It is strongly recommended that you only run the script once per database, otherwise your class and attribute names may be corrupted. If you only have a public and an administration siteaccess (which is the most typical/usual case), you will only need to run the script for one of the siteaccesses.
The "language" parameter tells the script which language your class / class attribute names currently exist in. Note that only one language can be specified using this parameter. If your classes are in different languages, it is recommended to specify the language that is used for most of them (for example, if 10 default class names are in English and 2 names of newly created custom classes are in Norwegian, you should use English as a parameter for the script and then edit the two custom classes manually). The following example shows how to run the script.
- Navigate into the eZ Publish 3.9.0 directory.
- Run the script (replace "example" with the actual name of your siteaccess, specify the original language instead of "eng-GB"):
php update/common/scripts/3.9/updateclasstranslations.php -s example --language=eng-GB
The script will check your content classes and content class attributes and re-initialize their names for missing translations.
Custom attributes for XML tags
eZ Publish 3.9.0 supports using custom attributes in all XML tags (see this page for more information). The names of the custom attributes must be added to the global (or siteaccess) "content.ini.append.php" configuration file. For example, if you wish to use a specific summary field in your tables, you can add a custom attribute called "summary" to the "table" XML tag by adding the following lines to the [table] section of your "content.ini.append.php" file:
CustomAttributes[] CustomAttributes[]=summary
In order to be compatible with this new feature, you will have to run the "correctxmltext.php" script. The following example shows how this can be done.
- Navigate into the eZ Publish 3.9.0 directory.
- If all your siteaccesses are using the same database, run the script with the "--global" option so that it will only update the "settings/override/content.ini.append.php" file:
php update/common/scripts/3.9/correctxmltext.php --global
Otherwise, run the script for each of your siteaccesses (replace "example" with the actual name of your siteaccess):php update/common/scripts/3.9/correctxmltext.php -s example
Use "--help" to view the additional options supported by this script.
Note that this script is faulty. Refer to http://issues.ez.no/9952 for more information about the problem and the solution.
The script will go through the XML block attributes stored in the database and do the following:
- Find all occurrences of the "object" tags (if any) and convert these to "embed" tags. (The "object" tag is deprecated and no longer used.)
- Check which custom classes are used within your XML tags and add missing "AvailableClasses[]" settings to your configuration file. (From 3.8.1, the names of all custom classes that are used within XML tags must be specified from within an override of the "content.ini" configuration file.)
- Check which custom attributes are used in your XML tags and add missing "CustomAttributes[]" settings (if any) to your configuration file.
Note that you can skip some of these tasks by using one of the options listed below:
Option | Description |
---|---|
--skip-objects |
Skip searching for deprecated "object" tags and converting them. |
--skip-classes |
Skip checking custom classes and modifying the "AvailableClasses[]" settings. |
--skip-custom |
Skip checking custom attributes and updating the "CustomAttributes[]" settings. |
If you do not wish to update your configuration file automatically, run the script like this:
php update/common/scripts/3.9/correctxmltext.php --classes-dump-only --custom-dump-only
The "--classes-dump-only" option allows you to view the list of missing classes instead of having your "AvailableClasses[]" settings automatically updated. The "--custom-dump-only" option allows to view the list of missing custom attributes without modifying the "CustomAttributes[]" settings.
Enhanced object relations
In eZ Publish 3.9.0, the object relations functionality has been improved (see this page for more information). The system will now use four types of object relations called "common", "XML linked", "XML embedded" and "by attribute". The first three types are relations at the object level while the last one is at the attribute level. The "XML embedded" type has been added in order to distinguish object relations created by inserting an embedded object in the XML block attribute from relations created by adding an object to the list of related objects (this type of relations is now called "common"). The "XML linked" type is used for new relations that are automatically created by the system when an internal link is inserted in an attribute of the XML block datatype. Note that "XML linked" relations are automatically removed when corresponding internal links are deleted. Same goes for "XML embedded" relations and their "embed" tags.
In order to be compatible with this new feature, you will have to run the "updatetypedrelation.php" script. This script should be run for all siteaccesses that use different databases. If you only have a public and an administration siteaccess (which is the most typical/usual case), you will only need to run the script for one of the siteaccesses. If the siteaccess is not specified, the default siteaccess will be used.
The following text shows how this can be done.
- Navigate into the eZ Publish 3.9.0 directory.
- Run the script (replace "example" with the actual name of your siteaccess):
php update/common/scripts/3.9/updatetypedrelation.php -s example
The script will go through the XML block attributes stored in the database and create object relations of the "XML linked" and "XML embedded" types if needed.
Step 4: Updating the system configuration
Updating INI settings for object relations
After running the upgrade scripts listed above you will need to configure how the object relations of the "XML linked" type will be handled on your site. From 3.9.0, inserting an internal link in the XML block attribute will lead to adding an "XML linked" relation. This behavior is controlled by the "ObjectRelationTyped" setting located in the "[BackwardCompatibilitySettings]" section of the "site.ini" configuration file. If you do not wish to use the "XML linked" type of relationships, make sure this setting is disabled.
Updating custom templates (optional)
In eZ Publish versions prior to 3.9, the "$node" variable might be present in the pagelayout when view caching is disabled. From 3.9, the "$node" variable is only available in node templates. This means that you will not be able to use this variable in the pagelayout (and other templates that are not related to the "view" view of the "content" module) even if view caching is disabled.
Enabling the Open Document Format extension (optional)
eZ Publish 3.9 includes the Open Document Format extension (previously known as "oo" and the "OpenOffice extension"). In order to use this extension, make sure your "settings/override/site.ini.append.php" file contains the following lines:
[ExtensionSettings] ActiveExtensions[]=ezodf
Note that it is also possible to enable this extension using the "Setup - Extensions" part of the administration interface as described here.
Updating INI settings for cronjobs (optional)
In eZ Publish 3.9.0, the default configuration of cronjobs has changed. The main set of cronjobs only contains tasks that should be run once a day. The tasks that should be executed frequently (workflow.php and notification.php) are now included in an additional set of cronjobs called "frequent". One more additional group of cronjobs called "infrequent" contains tasks that can be run once a week (linkcheck.php and basket_cleanup.php). The "ezpublish.cron" file is also updated. It is recommended to review your cronjob settings after upgrading.
Step 5: Clearing the 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:
- Navigate into the eZ Publish 3.9.0 directory.
- Run the clear cache script:
bin/shell/clearcache.sh --clear-all
Make sure that all caches are cleared. Sometimes the script is unable to clear caches because of restrictive file/directory permission settings. Make sure that all caches have been cleared by inspecting the contents of the various cache subdirectories within the "var" directory.
Svitlana Shatokhina (30/10/2006 10:52 am)
Julia Shymova (26/12/2007 3:13 pm)
Comments
Watch out with the upgrade scripts!
Thursday 21 December 2006 8:05:24 am
Kristof Coomans
2) Do not run the updateclasstranslations.php script more than one time! you'll get serialized PHP arrays as class and class attribute names!
Re: Watch out with the upgrade scripts!
Thursday 21 December 2006 9:19:17 am
Svitlana Shatokhina
Translation file .ts and locale.ini
Saturday 13 January 2007 2:48:00 pm
OOzypal
What language to use with updateclasstranslations?
Monday 15 January 2007 2:09:18 pm
Kristof Coomans
I must skip mysql update script sections "from 3.8.1" or "from 3.8.5" to success from 3.8.7
Monday 23 April 2007 3:26:46 pm
Lazaro Ferreira
Step 2: Upgrading the database
...please note that some of the database changes from eZ Publish 3.8.0 to 3.9.0 have been included in eZ Publish versions 3.8.1 and 3.8.5 as well. If you are upgrading from a version later than 3.8.0, it is recommended to skip the appropriate parts of the database upgrade scripts (these sections are marked with "from 3.8.1" or "from 3.8.5" comments in the ".sql" file)...
I would say that if you run the script from 3.8.7 (I guess 3.8.6 to) you MUST skip the parts mentioned above, other way it won't show your content and you will get a lot of database errors after upgrading to 3.9
Re: I must skip mysql update script sections "from 3.8.1" or "from 3.8.5" to success from 3.8.7
Wednesday 25 April 2007 12:35:46 pm
dl
The parts mentioned above has 'create index' queries. If you already have those indeces you'll get sql-error which say that indexes exists. nothing more. no data corruption.
i use mysql -f
Thursday 13 September 2007 10:34:03 am
vytis
The default setting for viewcaching is changed
Monday 25 February 2008 3:32:06 pm
Mauro
Exactly:
in eZ 3.8.x system site.ini viewcaching=enabled
in eZ 3.9.x system site.ini viewcaching=disabled
Re: The default setting for viewcaching is changed
Tuesday 26 February 2008 10:18:59 am
Svitlana Shatokhina
Thanks for pointing this out!
Script problem was fixed in 3.9.1
Wednesday 02 April 2008 6:32:52 am
Leif Arne Storset