Path

ez.no / documentation / ez publish / upgrading / the system upgrade scripts


Caution: This documentation is for eZ Publish legacy, from version 3.x to 5.x.
For 5.x documentation covering Platform see eZ Documentation Center, for difference between legacy and Platform see 5.x Architecture overview.

The system upgrade scripts

This section reveals the list of the system upgrade scripts located either in the "update/common/scripts" or "bin/php" directory. The scripts are included in various eZ Publish 3 releases and intended to update the existing site data when upgrading the system from older versions. Please refer to the "Upgrading from 3.a.b to 3.x.y" section to learn how to figure out which scripts that should be run in each particular case. (Note that some of the scripts listed below, e.g. "updatesearchindex.php" and "updateniceurls.php" can be used at all times; not just during upgrades.)

The main scripts for system upgrading (v3.10)

Version

Script name

Description

3.10.0

updateniceurls.php

In eZ Publish 3.10, a new feature that makes it possible to use multi-lingual virtual URLs has been added. In order to use this functionality, you will have to set the desired type of URL transformation and run the "updateniceurls.php" script. It will go through all content objects stored in the database and create new virtual URLs for them in accordance with the selected type of transformation. Refer to the upgrade instructions for more information.

3.10.0

ezimportdbafile.php
updateisbn13.php

In eZ Publish 3.10, the different ranges are stored in the database, allowing the system to fix up incorrectly entered ISBN-13 codes. When upgrading, you need to import ranges to the database manually. This must be done even though your site does not use ISBN-13 numbers. You can either import ranges from the "db_data.dba" file located in the "kernel/classes/ezisbn/share/" directory using the "ezimportdbafile.php" script or download the latest "range.js" file and run the "updateisbn13.php" script. Refer to the upgrade instructions for more information.

3.10.0

ezconvert2isbn13.php

In order to use ISBN-13 numbers after upgrading to eZ Publish 3.10, you need to run the "ezconvert2isbn13.php" script. It will go through all content object attributes using the "ISBN" datatype and convert their values to valid ISBN-13 numbers. Refer to the upgrade instructions for more information.

3.10.0

updatemultioption.php

In eZ Publish 3.10, a new datatype called "Multi-option2" has been added as a replacement for the old "Multi-option" datatype. In order to be compatible with this datatype, you have to run the "updatemultioption.php" script. The script will go through all content object attributes that are using the old "Multi-option" datatype and make sure (by the way of conversion) that they are using the new "Multi-option2" datatype. Refer to the upgrade instructions for more information.

The main scripts for system upgrading (v3.9)

Version

Script name

Description

3.9.3

updatevatcountries.php

As a result of an important bugfix related to the handling of country dependent VATs, changes have been made in eZ Publish 3.9.3 (and in version 3.10.0 as well). If you are upgrading from version 3.9.2 or earlier, you need to run the "updatevatcountries.php" script. The script will go through all the VAT rules in the database and make them compatible with the introduced changes. Refer to the upgrade instructions for more information.

3.9.0

updateclasstranslations.php

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. In order to make sure that your site is compatible with this functionality, you will have to run the "updateclasstranslations.php" script. This step must be done even though your site has only one language. The script will check your content classes and content class attributes and re-initialize their names for missing translations.Refer to the upgrade instructions for more information.

3.9.0

correctxmltext.php

eZ Publish 3.9.0 supports using custom attributes in all XML tags. The names of the custom attributes must be added to the global (or siteaccess) "content.ini.append.php" configuration file. In order to be compatible with this feature, you will have to run the "correctxmltext.php" script. The script will go through the XML block attributes stored in the database, convert the deprecated "object" tags to "embed" tags, add missing settings for all custom classes and custom attributes used within XML tags. Note that this script has been improved in eZ Publish 3.9.1. If you are upgrading to 3.9.0, it is recommended to copy the script from 3.9.1. Refer to the upgrade instructions for more information.

3.9.0

updatetypedrelation.php

In eZ Publish 3.9.0, the object relations functionality has been improved. In order to be compatible with this feature, you will have to run the "updatetypedrelation.php" script. 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. Refer to the upgrade instructions for more information.

The main scripts for system upgrading (v3.8)

Version

Script name

Description

3.8.9

updatetipafriendpolicy.php

In order to make it possible to restrict access to the "Tip a friend" feature, changes have been made in eZ Publish 3.8.9 (and to versions 3.9.3 and 3.10.0 as well). Users (typically the anonymous role) need to have access to the "tipafriend" function of the "content" module in order to use the "Tip a friend" feature. You need to run the "updatetipafriendpolicy.php" script. The script will add a new role that grants access to the "Tip a friend" feature and ask for confirmation about assigning it to each user or user group located one level beneath the "Users" top level node. Refer to the upgrade instructions for more information.

3.8.1

correctxmltextclasses.php

In eZ Publish 3.8.0 and earlier versions, you could use custom classes in XML tags without having to specify them first. From 3.8.1, you have to specify the names of all custom classes that are used within XML tags. It is recommended (but not required) to run the "correctxmltextclasses.php" script when upgrading to 3.8.1 or later version. The script will go through the XML block attributes stored in the database, check which classes are in use and add missing settings (if any) to the "content.ini.append.php" configuration file. Refer to the upgrade instructions for more information.

3.8.0

updatemultilingual.php

The 3.8.0 version of eZ Publish introduces improved multi-language functionality. In order to make sure that your site is compatible with this feature, you will have to run the "updatemultilingual.php" script. This step must be done even though your site has only one language. Note that this script has been improved in eZ Publish 3.8.1. If you are upgrading to 3.8.0, it is recommended to copy the script from 3.8.1. Refer to the upgrade instructions for more information.

3.8.0

updaterssimport.php

The 3.8.0 version of eZ Publish introduces more generic RSS import that allows using custom RSS import definitions. If you are using the RSS import functionality on your site, you will have to run the "updaterssimport.php" script. Refer to the upgrade instructions for more information.

The main scripts for system upgrading (unsupported versions)

Version

Script name

Description

3.0-1

updatesearchindex.php

In eZ Publish 3.0-1, the built-in search engine has been improved (see the 3.0-1 changelog for more information) and thus you need to update the search index of your site when upgrading from 2.9-x. To do this, clear the search index tables in your database (these are called "ezsearch_word" and "ezsearch_object_word_link") and run the "updatesearchindex.php" script. The script must be run only once, not per siteaccess.

3.0-1

updateniceurls.php

In eZ Publish 3, the virtual URLs (nice URLs, URL aliases) are automatically generated and maintained for all nodes. The generated URL for a node is based on the node's location in the tree and the actual name of the object that the node encapsulates.

If you are upgrading from 2.9.x then you should run the "updateniceurls.php" script in order to generate virtual URLs for all your content nodes. This script only modifies the "ezurlalias" table in the database. It must be run only once, not per siteaccess.

Please note that this script has been improved in eZ Publish 3.2-2. If you are upgrading to a version prior to 3.2-2, it is recommended to copy the script from 3.2.-2.

3.0-1

updatexmltext.php

In eZ Publish 3.0-1, the "ezxmltext" datatype has been changed in order to store an XML code using UTF-8 encoding (see the 3.0-1 changelog for more information). If you are upgrading from 2.9.x then you should run the "updatexmltext.php" script for automatic conversion of your XML fields to new format. It is recommended to create a database backup before using this script. The script must be run only once, not per siteaccess.

3.1.0 rel 1

generateoverridesettings.php

In eZ Publish 3.1.0 release 1, the new template override subsystem that allows to use custom templates instead of the default/standard ones has been implemented (see the 3.1.0 rel1 changelog for more information). The template overrides must be defined in the "override.ini.append.php" file of a siteaccess.

If you are upgrading to 3.1.0 rel1 or later then you should run the "generateoverridesettings.php" script for each of your siteaccesses. The script will output a suggestion for the siteaccess "override.ini.append.php" file that needs to be created for the specified siteaccess. You should create a new file called "override.ini.append.php" in the "settings/siteaccess/example" directory (replace "example" by the actual name of your siteaccess) and copy the output provided by the script to this file.

Please note that this script has been improved in eZ Publish 3.2-1 (3.2.0 release 3). If you are upgrading to a version prior to 3.2-1, it is recommended to copy the script from 3.2-1.

3.2-1

updateattributefilter.php

eZ Publish 3.2-1 supports sorting and filtering on attribute level. It is possible to sort and/or filter a list of content objects based on the values of a specific attribute (see the 3.2-1 changelog for more information). The "list" and "tree" fetch functions support this functionality.

3.2-4

updatetranslations.php

In eZ Publish 3.2-4, an important bug related to adding new object attributes has been fixed (see the 3.2-4 changelog for more information). Since that bug might lead to missing translated attributes on multi-lingual sites, it is recommended to run the "updatetranslations.php" script. The script will check your content objects and re-initialize attributes if their data is missing as a result of the bug.

3.4.0

updateremoteid.php

In eZ Publish 3.4.0, a new attribute called "remote_id" has been added to content objects, classes and nodes. This attribute stores a global unique ID for an object/class/node. The remote ID is an MD5 hash of the time when the object/class/node was created plus a random value. These IDs are used in order to avoid collisions of identical objects/classes/nodes when importing and exporting data from one site to another.

If you are upgrading to 3.4.0 then you should run the "updateremoteid.php" script in order to make sure that all your items that support the remote ID gets one generated. The script must be run only once, not per siteaccess.

3.4.0

updatesession.php

The eZ Publish session support is based on the PHP session functionality. Most of the session handling work is done by PHP; some eZ Publish specific functions are called for getting and storing the session data in the database. In eZ Publish 3.4.0, this functionality has been improved in order to relate a session to a user (see the 3.4.0 changelog for more information). The session data in the "ezsession" table now contain information about the session user. This allows to easily count the number of active registered users and anonymous users. When a user is being removed or disabled, the system will remove the corresponding session(s) in order to automatically log out invalid users.

If you are upgrading from 3.3-x to 3.4.0 then you should run the "updatesession.php" script in order to update the entries in the "ezsession" table. The script must be run only once, not per siteaccess.

3.4.0

updatetoplevel.php

In eZ Publish versions prior to 3.4, there were three top level nodes ("Content", "Media" and "Users"). Since in eZ Publish 3.4.0 a new one called "Setup" has been added, it is recommended to run the "updatetoplevel.php" script when upgrading. The script will check the top level nodes and match them with the values defined under the "[NodeSettings]" section of the "content.ini" configuration file or its override. If "content.ini" or its override contains incorrect IDs of the top level nodes, these will be automatically updated. If some of the top level nodes are missing, these will be created. The script must be run only once, not per siteaccess.

3.4.0

addorderemail.php

In eZ Publish 3.4.0, the webshop functionality has been improved (see the 3.4.0 changelog for more information). The list of orders that is stored in the "ezorder" database table now includes the customer's email for each order. If you are using the eZ Publish webshop functionality on your site and your order list is not empty, then you need to run the "addorderemail.php" script when upgrading to 3.4.0. The script will modify the "ezorder" table in the database. It must be run only once, not per siteaccess.

3.5.0

updateiscontainer.php

In eZ Publish 3.5.0, a new attribute called "is_container" has been added to content classes (see the feature doc for more information). The container flag controls whether an instance of the class should be allowed to have sub items (often called child nodes, children) or not.

If you are upgrading to 3.5.0 then you should run the "updateiscontainer.php" script in order to set this flag for those classes that are allowed to have subitems. The script must be run for each of your siteaccesses. Please note that the script can only modify the general purpose classes. You should manually set the container flag for your custom classes (if there are any), otherwise it won't be possible to create subitems.

3.5.0

updateniceurls.php

eZ Publish 3.5 includes the built-in transliteration feature that allows to automatically convert special characters to their equivalent in English letters when generating the virtual URLs (nice URLs, URL aliases). For example, the Norwegian characters "æ", "ø" and "å" are converted to "ae", "oe" and "aa" instead of underscores.

If you are upgrading to 3.5.0 or later then it is recommended (but not required) to run the "updateniceurls.php" script in order to make sure all your content nodes have their virtual URLs generated using a correct transformation of special characters. The script modifies the "ezurlalias" table in the database. It must be run only once, not per siteaccess.

3.5.0

updatesearchindex.php

eZ Publish 3.5.0 includes a few bug fixes related to the search index generation (see the 3.5.0 changelog for more information). It is recommended (but not required) to update the search index of your site when upgrading to 3.5.0. This can be done by running the "updatesearchindex.php" script with the "--clean" option. This option (added in eZ Publish 3.3-1) means that the existing search index data should be removed before starting indexing. The script must be run only once, not per siteaccess.

3.5.1

updatetoplevel.php

eZ Publish versions prior to 3.5.1 suppose that there are four top level nodes ("Content", "Media", "Users" and "Setup"). In eZ Publish 3.5.1 a new one called "Design" has been added.

If you are upgrading to 3.5.1 then you should run the "updatetoplevel.php" script for your admin siteaccess. The script will check the top level nodes and match them with the values defined in the "menu.ini" configuration file or its override. (From 3.5.0, the main menu in the admin interface can be configured using "menu.ini".) If "menu.ini" or its override contains incorrect information about the top level nodes, it will be automatically updated. If some of the top level nodes are missing, these will be created.

Please note that this script has been improved in eZ Publish 3.5.2. If you are upgrading to a version prior to 3.5.2, it is recommended to copy the script from 3.5.2.

3.5.3

updateeztimetype.php

In eZ Publish 3.5.3, the "Time" datatype has been modified in order to make it possible to interpret the value of hours and minutes properly and independently from DST and GMT transformations (see the feature doc for more information).

If you are upgrading to 3.5.3 or later, then you should run the "updateeztimetype.php" script in order to convert the attributes of the "eztime" datatype from GMT to the server local time. You need to create a database backup before using this script. The script must be run for each siteaccess.

3.5.8

updatecrc32.php

Since some PHP functions (like crc32 and ip2long) work in different ways on 64bit and 32bit servers, changes has been made in eZ Publish 3.5.8 (and to versions 3.6.5, 3.7.3 and 3.8.0 as well) in order to avoid problems when migrating from 32bit to 64bit architecture. You need to run the "updatecrc32.php" script when upgrading even if you don't have a 64bit machine. (The script will update old signed to unsigned values in the database.) It is also recommended to specify "64bitCompatibilityMode=enabled" in your "site.ini.append.php" configuration file.

3.6.0

convertxmllinks.php

In eZ Publish 3.6, new XML tags called "link" and "embed" that replace and extend functionality of the old "object" tag have been introduced (see this page for more information). In order to be compatible with this feature, you will have to run the "convertxmllinks.php" script. The script will update the tags in the attributes of the "ezxmltext" datatype. It 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), then you only need to run the script for one of the siteaccesses. If the siteaccess isn't specified, the default siteaccess will be used.

3.6.0

updaterelatedobjectslinks.php

In eZ Publish 3.6, the related objects functionality has been improved (see this page for more information). In order to be compatible with this feature, you will have to run the "updaterelatedobjectslinks.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), then you only need to run the script for one of the siteaccesses.

The additional scripts (tools for data updating)

Version

Script name

Description

3.3-1

cleanup.php

eZ Publish 3.3-1 includes a new script called "cleanup.php". It allows to clean up the database in order to get rid of various data that should not be included in release (see the 3.3-1 changelog for more information). The script can be used to remove outdated sessions, information related to user preferences, workflows, collaboration system, notifications etc.

3.3-1

flatten.php

The "flatten.php" script has been added in eZ Publish 3.3-1 and moved from the "update/common/scripts" directory to "bin/php" in 3.5 (rev. 13488). This script allows to remove the data that is not considered currently in use from the database. This script will remove any non-published version, leaving only the one with the PUBLISHED status. In this case, you will probably need to run the "flatten.php" script in order to delete unneeded versions from the previously published objects. This script is often used to clean the database at the end of the development process before launching the site.

3.5.0

updatecontentobjectname.php

In eZ Publish versions prior to 3.5, updating the object name pattern of a class affected only new objects of this class. To update the names of the existing objects of this class accordingly, you had to re-publish each of them. In eZ Publish 3.5, a new script called "updatecontentobjectname.php" has been added for automatic update of the names of the content objects. After changing the object name pattern for a class, you can update the names of the existing content objects by running this script for your siteaccess. It is recommended to create a database backup before using this script. You may also need to update your nice URLs and search index using the "updateniceurls.php" and "updatesearchindex.php" scripts.

Svitlana Shatokhina (11/09/2006 1:24 pm)

Geir Arne Waaler (12/08/2010 10:32 am)

Svitlana Shatokhina, Julia Shymova, Geir Arne Waaler


Comments

There are no comments.