Path

7x / documentation / ez publish / upgrading / upgrading to 3.10 / from 3.9.x to 3.10.0 (depre...


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

from 3.9.x to 3.10.0 (deprecated)

This documentation page is deprecated and no longer maintained. Refer to the following documentation pages for upgrade instructions:

This section describes how to upgrade your existing eZ Publish 3.9.x installation to version 3.10.0. If you are upgrading from a version prior to eZ Publish 3.9.0, you need to first upgrade to 3.9.0 before you can upgrade to 3.10.

The upgrade procedure described below is generic and does not cover any specific cases. If you are running eZ Publish in a clustered environment, refer to the developer documentation for upgrade instructions. In case the eZ Publish Extension for Oracle® Database is used, refer to the documentation of the database extension.

Important note

Before continuing, note that eZ Publish 3.10.0 does not support wildcard based URL forwarding anymore. If your site makes use of this functionality, it is strongly recommended to delay upgrading until eZ Publish 3.10.1 is released.

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:

  1. Upgrading the distribution files to 3.10
  2. Upgrading the database to 3.10
  3. Running the 3.10 upgrade scripts
  4. Updating the system configuration
  5. Clearing the caches

Step 1: Upgrading the distribution files

The easiest way to upgrade the distribution files is to unpack eZ Publish 3.10 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.

Important bug fix for the "user" module

In eZ Publish 3.10.0, the "register" view of the "user" module contains a bug. It prevents the system from registering new users when the "VerifyUserEmail" setting is enabled (it is enabled by default). The same bug exists in eZ Publish 3.8.10 and 3.9.4 (refer to http://issues.ez.no/11598 for more information). This issue will be fixed in the upcoming eZ Publish 3.9.5 and 3.10.1 releases. In order to make your user registration mechanism work properly in 3.10.0, you have to download the updated version of "kernel/user/register.php" from http://pubsvn.ez.no and replace the corresponding file in your installation.

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

If you are using the Website Interface front-end, make sure you copied the "extension/ezwebin/" directory. It is also possible to upgrade the Website Interface extension to a newer version (you can find more information and instructions in the "Upgrading the Website Interface" chapter of the Website Interface installation guide).

Translations

eZ Publish 3.10.0 has less translations than 3.9 releases because not all of the translation contributors have submitted a CLA yet. If you are using a multilingual site the possible workarounds in that case can be either to use the 3.9.x translations or to download translations from http://ez.no/developer/translations. It would also be highly appreciated if translators for existing translations send us the CLA so that we can include the translations in future 3.10 releases.

Step 2: Upgrading the database

The following text describes how a 3.9.x database can be upgraded to 3.10.0.

Before reading on, note that some of the database changes from eZ Publish 3.9.0 to 3.10.0 have been included in other 3.9 releases. If you are upgrading from a version later than 3.9.0, it is recommended to skip some parts of the database upgrade script. These are marked with "from 3.9.z" comments in the ".sql" file; make sure you skip all sections with "z" less than or equal to the last digit in your current version number. For example, if you are upgrading from 3.9.3, skip sections marked with "from 3.9.1", "from 3.9.2" and "from 3.9.3" comments (if any).

MySQL

  1. Navigate into the eZ Publish 3.10.0 directory.
  2. Run the database upgrade script:

    mysql -u <username> -p<password> <database> < update/database/mysql/3.10/dbupdate-3.9.0-to-3.10.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 the 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 ezisbn_group TYPE = innodb;
ALTER TABLE ezisbn_group_range TYPE = innodb;
ALTER TABLE ezisbn_registrant_range TYPE = innodb;
ALTER TABLE ezurlalias_ml TYPE = innodb;

It is also possible to use the "bin/php/ezconvertmysqltabletype.php" script for database conversion.

PostgreSQL

  1. Navigate into the eZ Publish 3.10.0 directory.
  2. Run the database upgrade script:

    psql -d <database> -U <dbowner> < update/database/postgresql/3.10/dbupdate-3.9.0-to-3.10.0.sql
    

Step 3: Running the system upgrade scripts

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

Multi-language support for URL aliases

In eZ Publish 3.10, a new feature has been added that makes it possible to use multi-lingual virtual URLs (also known as nice URLs or URL aliases). In order to use this new functionality, you will have to specify the desired type of URL transformation using the "TransformationGroup" setting located in the [URLTranslator] section of an override for "site.ini" and run the "updateniceurls.php" script as described below.

Note that this script has been sufficiently improved in eZ Publish 4.0.0 and the upcoming version 3.10.1. In addition, these versions of eZ Publish will support wildcard based URL forwarding (This feature was removed when implementing the multilingual URLs functionality for eZ Publish 3.10.0 and then re-added in later versions.) If you are planning to upgrade from 3.9.x to 4.0.0, it is recommended to skip running the "updateniceurls.php" script when upgrading to 3.10.0, and run the updated version of the script at a later stage (when upgrading from 3.10.0 to 4.0.0). If you are going to use multilingual URLs in eZ Publish 3.10, it is recommended to delay upgrading until the upcoming 3.10.1 version is out.

It is also possible to choose which word separator should be used in the URLs. This can be done by setting the "WordSeparator" configuration directive also located in the [URLTranslator] section to either "dash", "underscore" or "space". Note that this setting will be ignored when the "urlalias_compat" transformation is used (it only supports underscores as separators).

Before running the script, make sure that you have specified the same transformation settings for all siteaccesses that are using the same database. If all your siteaccesses are using the same database (which is the most typical/usual case), you can set the "TransformationGroup" and "WordSeparator" directives in "settings/override/site.ini.append.php". Otherwise, you will have to configure URL transformation from within "settings/siteaccess/example/site.ini.append.php" (where "example" should be replaced by the actual name of your siteaccess) for each siteaccess.

The "updateniceurls.php" 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, you 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 example shows how to run the script.

  1. Navigate into the eZ Publish 3.10.0 directory.
  2. Run the script (replace "example" with the actual name of your siteaccess):
    php bin/php/updateniceurls.php -s example
    

The script will go through all content objects stored in the database and create new virtual URLs for them in accordance with the specified transformation settings. Old virtual URLs will be transferred to the new system and stored as history entries. Note that new URL aliases will be generated for all the languages of your site regardless if they are available or not for the specified siteaccess. The time it takes to update all URL aliases is proportional to the number of nodes on your site. Newly generated URL aliases are stored in a database table called "ezurlalias_ml".

Refer to "Multi-language support for URL aliases" for more information about this feature.

ISBN datatype enhancements

In eZ Publish 3.10, the handling of ISBN-13 numbers has been significantly improved (refer to the ISBN datatype documentation for details). The different ranges are now stored in the database, allowing the system to fix up incorrectly entered ISBN-13 codes (codes with misplaced or missing dashes). When a new version of eZ Publish is released, the latest information about the different ranges is downloaded from http://www.isbn-international.org/converter/ranges.js and stored in a ".dba" file. During the installation process, the setup wizard imports this information to the database. 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 ".dba" file using the "ezimportdbafile.php" script or download the latest "range.js" file and run the "updateisbn13.php" script.

The following example shows how to import ranges from the ".dba" file:

  1. Navigate into the eZ Publish 3.10.0 directory.
  2. Run the script (replace "example" with the actual name of your siteaccess):
    php bin/php/ezimportdbafile.php --datatype=ezisbn -s example
    

The "datatype" parameter tells the script which datatype the data should be imported for.

The next example shows how to get the latest ranges from the ISBN International website.

Note that due to a bug in eZ Publish 3.10.0, you need to download the updated version of the "updateisbn13.php" script from http://pubsvn.ez.no and replace the corresponding file in your installation before running the script. The updated version of the script is included in eZ Publish 4.0.0 and the upcoming 3.10.1 release.

  1. Download a ".js" file containing the list of ranges using the following link: http://www.isbn-international.org/converter/ranges.js
  2. Navigate into the eZ Publish 3.10.0 directory and copy the downloaded file there.
  3. Run the "updateisbn13.php" script using the following shell command:
    php bin/php/updateisbn13.php --file=ranges.js
    

The script will import information from the "range.js" file to the database.

In order to use ISBN-13 numbers on your site after upgrading, you need to do the following:

  1. Make sure that the "ISBN-13 format" checkbox in the class attribute edit interface for the corresponding attribute is enabled (it is off by default).
  2. Navigate into the eZ Publish 3.10.0 directory.
  3. Run the "ezconvert2isbn13.php" script (replace "example" with the actual name of your siteaccess):
    php bin/php/ezconvert2isbn13.php -s example
    

The script will go through all content object attributes using the "ISBN" datatype in the database and convert their values into valid ISBN-13 numbers. The following table reveals the available options for this script.

Option

Description

--class-id=value

The script will only update attributes of content objects that belong to the specified class. You need to replace "value" with the actual ID number of the class.

--attribute-id=value

The script will only update content object attributes that correspond to the specified content class attribute. You need to replace "value" with the actual ID number of the class attribute.

--all-classes

The script will go through all content objects.

--force

The script will update all attributes of the "ISBN" datatype regardless if the "ISBN-13 format" checkbox is enabled for the class attribute. It will also enable this setting at the class attribute level where it was previously disabled.

These scripts 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, you only need to run the scripts for one of the siteaccesses. If the siteaccess is not specified, the default siteaccess will be used.

Enhanced Multi-option datatype

In eZ Publish 3.10, a new datatype called "Multi-option2" has been added in order to replace the old "Multi-option" datatype. The new datatype allows option selections and makes it possible to create multiple and distinctive groups of multi-options for each content object. In addition, it supports rules and provides a handful of new and interesting features. Note that the old "Multi-option" datatype is deprecated and should no longer be used (it will be removed in the future).

In order to be compatible with the new datatype, you will have to run the "updatemultioption.php" script. 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, you 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 example shows how to run the script:

  1. Navigate into the eZ Publish 3.10.0 directory.
  2. Run the script (replace "example" with the actual name of your siteaccess):
    php update/common/scripts/3.10/updatemultioption.php -s example
    

The script will go through all content object attributes that are using the old "Multi-option" datatype in the database. The content object attributes will be modified (converted) so that they use the new "Multi-option2" datatype.

The following table reveals the available options for this script.

Option

Description

--all-classes

The script will go through all types of content objects.

--contentclass=value

The script will only update objects of the specified class. You need to replace "value" with the actual identifier of the class.

Note: overridden templates of the public siteaccess for the "Multi-option" datatype will also need to be updated (manually).

Changes to roles and policies

In eZ Publish 3.9.3 and later versions, users (typically those to which the anonymous role applies) need to have access to the "tipafriend" function of the "content" module in order to use the "Tip a friend" feature. If you are upgrading from a version prior to 3.9.3, you need to run the "updatetipafriendpolicy.php" script as described below.

If you are running eZ Publish on Windows, note that in eZ Publish 3.10.0 there is a bug in the ?updatetipafriendpolicy.php? script that prevents it from granting access to the "Tip a friend" feature to the users. You need to download the updated version of the "updatetipafriendpolicy.php" script from http://pubsvn.ez.no and replace the corresponding file in your installation before running the script. The same bug exists in eZ Publish 3.9.3 - 3.9.4 (refer to http://issues.ez.no/11663 for more information). The updated version of the script is included in eZ Publish 4.0.0 and the upcoming eZ Publish 3.10.1 and 3.9.5 releases.

The following example shows how to run the script:

  1. Navigate into the eZ Publish 3.10.0 directory.
  2. Run the script using the following shell command:
    php update/common/scripts/3.10/updatetipafriendpolicy.php -s example_admin -l login -p password
    

Replace "example_admin" with the actual name of your admin siteaccess and use the administrator's login and password instead of "login" and "password".

The script will add a new role that grants access to the "Tip a friend" feature and ask for confirmation about assigning this role to each user or user group located one level beneath the "Users" top level node.

Improved handling of country dependent VATs

In eZ Publish version 3.10, the handling of country dependent VATs has been improved. Because of compatibility reasons, you need to run the "updatevatcountries.php" script.

Note that due to a bug in eZ Publish 3.10.0, you need to download the updated version of the "updatevatcountries.php" script from http://pubsvn.ez.no and replace the corresponding file in your installation before running the script. The same bug exists in eZ Publish 3.9.4 and 3.9.3 (refer to http://issues.ez.no/11955 for more information). The updated version of the script is included in eZ Publish 4.0.0 and the upcoming eZ Publish 3.10.1 and 3.9.5 releases.

The "updatevatcountries.php" 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, you only need to run the script for one of the siteaccesses. If the siteaccess isn't specified, the default siteaccess will be used.

The following example shows how to run the script:

  1. Navigate into the eZ Publish 3.10.0 directory.
  2. Run the "updatevatcountries.php" script (replace "example" with the actual name of your siteaccess):
    php update/common/scripts/3.10/updatevatcountries.php -s example
    

The script will go through all the VAT rules in the database and make them compatible with the newly introduced changes.

Step 4: Updating the system configuration

Updating INI settings that use URL aliases

If your site makes use of the "urlalias" or "urlalias_iri" transformation method, read this part carefully. If you have specified "urlalias_compat" in the "TransformationGroup" configuration setting in step 3, skip this part.

After running the "updateniceurls.php" script in step 3, you need to review your configuration settings and update the URL aliases that are used in configuration files. For example, if your site makes use of the "PathPrefix" and "PathPrefixExclude" settings, this functionality might stop working if the specified URL aliases have changed (which will likely be the case because the virtual URLs are re-generated in accordance with the "TransformationGroup" and "WordSeparator" directives). Even though the old virtual URLs are stored as history entries and redirect to new ones when being accessed on the actual site, configuration settings do not work with URL history entries, i.e. you need to specify correct URL aliases there.

Also, you need to review the configuration settings in your "override.ini.append.php" file(s), otherwise your override templates activated by the "url_alias" condition will most likely stop working. For each line in the "override.ini.append.php" file that contains something like this:

Match[url_alias]=<virtual_url>

make sure that the correct virtual URL is specified.

Note that for multi-language sites, you need to specify URL aliases in the most prioritized language (controlled by the "SiteLanguageList" configuration array located under the "[RegionalSettings]" section of "site.ini.append.php").

Treemenu configuration

In eZ Publish versions prior to 3.10, the left treemenu in the administration interface didn't scale very well (refer to the specifications for details). This has been significantly improved in 3.10. The newly added implementation is called "dynamic content structure menu". It makes use of the AJAX technology, which is supported by all modern browsers. The old implementation is still available and enabled after upgrading. It is however recommended to switch to the new implementation, specially for large sites with many nodes. This will make the treemenu work much faster and decrease the usage of network bandwidth. (Note that new sites created from scratch using the setup wizard will have "dynamic" treemenu in the administration interface.)

If you want to use the new implementation of the treemenu, do the following:

  1. Open the "contentstructuremenu.ini.append.php" configuration file located in the "settings/siteaccess/example_admin" directory (replace "example_admin" with the actual name of your admin siteaccess) and edit it. If the file does not exist, create it.
  2. Add the following lines under the "[TreeMenu]" section:
    [TreeMenu]
    Dynamic=enabled
    

Updating Apache configuration (optional)

The following rewrite rules are added into ".htaccess_root" file by default.

RewriteRule content/treemenu/?$ index_treemenu.php
RewriteRule index_treemenu.php - [L]

If the ".htaccess_root" file isn't used, it is strongly recommended to update the Apache configuration file. You can do this by adding the following line above the other / already existing rewrite rules for eZ Publish:

RewriteRule content/treemenu/?$ /index_treemenu.php [L]

This will instruct Apache to use "index_treemenu.php" instead of "index.php" when accessing the "treemenu" view of the "content" module (this is an optimized script that only takes care about a specific case and thus it works faster than the regular "index.php").

Anchors within headings in Online Editor

eZ Publish 3.10.0 comes with 4.2.4 of the Online Editor extension. In this version, the "AnchorAsAttribute" setting located in the [header] section of the "extension/ezdhtml/settings/content.ini.append" configuration file is disabled by default. The above mentioned setting controls whether the usage of the "anchor_name" attribute for the "header" XML tag should be allowed or not. If XML content on your site is using this attribute, you need to make sure that the "AnchorAsAttribute" setting is enabled.

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:

  1. Navigate into the eZ Publish 3.10 directory.
  2. Run the script using the following shell command:
    php bin/php/ezcache.php --clear-all --purge
    

Purging allows to make sure the caches are physically removed. Without the "--purge" option, the caches will be expired but not removed.

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 (typically "var/cache/" and "var/<name_of_siteaccess>/cache/" directories). If there are caches left, you need to remove them manually.

Svitlana Shatokhina (23/07/2007 7:44 am)

Sarah Haïm-Lubczanski (01/08/2014 3:59 pm)

Svitlana Shatokhina, Julia Shymova, Sarah Haïm-Lubczanski


Comments

  • after updateniceurls most links in google and users' bookmarkes will not work

    after updateniceurls most links in google and users' bookmarkes will not work, because of default setting of "TransformationGroup" .
    There is said "Old virtual URLs will be transferred to the new system and stored as history entries.", but old links will not work.
    • Re: after updateniceurls most links in google and users' bookmarkes will not work

      'History entries' are all the old urls in the system, so if you had 'news/my_cool_article' in 3.9 and you upgraded it would be placed in the history. If you then enter the old url in the browser (or from bookmark/google) the system will redirect you to the new and correct url/name. This also happens if you rename an object, the old name is kept around for redirecting purposes. If it doesn't work as described here, please file an issue on http://issues.ez.no

      Note: if you want to use the old-style URLs, change the TransformationGroup and WordSeparator settings accordingly and re-run the script.
  • Upgrade sql also has sections already done by 3.9.4 upgrade.

    If upgrading from 3.9.4 or later, take care when commenting out the unneeded sections in the upgrade sql as described above. There is also a section that was done in the 3.9.3-to-3.9.4 upgrade, and should also be commented out. This section is not marked as such in the 3.9.0-to-3.10.0.sql. It is the following lines:

    ALTER table ezsearch_word ADD KEY ezsearch_word_obj_count(object_count);

    DROP INDEX ezurl_url ON ezurl;
    ALTER TABLE ezurl MODIFY url longtext;
    ALTER table ezurl ADD KEY ezurl_url( url(255) );

    If upgrading from 3.9.4 or later, those lines should be commented out. The instructions under step 2 should read as follows:

    See also this bug:

    http://issues.ez.no/11782
  • Hints about Nice URLs.

    Here are a few things I stumbled upon in the hope it might help other users:

    Nice URLs:
    Originally I used the InnoDB Storage Engine. After upgrading from 3.9.1 to 3.10.0 my nice URLs were replaced by numbers. I've started over and changed all tables to MyISAM before running the updateniceurls script and now my URLs were OK.

    Patch 'URL alias name pattern':
    I've patched 3.9.1 with this patch: http://ezpedia.org/wiki/en/ez/url_alias_name_pattern.
    Since the patch already created a column called 'url_alias_name' in the table 'ezcontentclass' I had to remove the following lines from dbupdate-3.9.0-to-3.10.0.sql:

    -- URL alias name pattern
    ALTER TABLE ezcontentclass ADD COLUMN url_alias_name VARCHAR(255) AFTER contentobject_name;
  • Clear Cache deletes images

    Hello.

    I did an update from version 3.9.0. to 3.10.0. All the steps in the upgrading documentation were finished successfully and my site looks very well after upgrading.

    BUT if I clear all caches using the clear cache button in the backend all the images in page will be deleted.

    If I clear caches using the shell

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


    my images won't be deleted...


    I have no idea what caused this problem and would be appreciated if someone could help me.

    Thanks a lot,
    Philip
    • Re: Clear Cache deletes images

      This is now reported here: http://issues.ez.no/12237.
  • updateniceurls.php - check if remote_id's exisits

    Hi,

    if you have path problems after running the updateniceurls.php script, check if all remote_id's were set.

    http://issues.ez.no/IssueView.php?Id=12231&activeItem=1

    Best wishes,
    Georg.
  • updateniceurls.php - run with import flag

    If you get URLs like example.org/folder2 for something that should be example.org/folder1/folder2 after the upgrade from 3.9 to 3.10, you might want to add the import flag when updating the nice URLs:

    bin/php/updateniceurls.php -s <siteaccess> --import
    


    This fixed the issue for me. Thanks for the hint, Matthew. ;)
  • iri crap

  • where is fixed updateniceurls.php ?

    You acknowledge that updateniceurls coming with this package is broken.
    You acknowledge that fixed version exists.
    WHY ON EARTH DONT YOU LINK TO FIXED SCRIPT?
    So right now everyone either have to keep sitting on their thumbs waiting for 3.10.1 coming up in some bright future or have to go hunting in mad hierarchies of svn.
    By the way, contrary to what you say 4.0 does not have that script.
    • Re: where is fixed updateniceurls.php ?

      Me bad, it is in 4.0 but of course that one is unusable as its for php5.
    • Re: where is fixed updateniceurls.php ?

      The updated script for 3.10.1 is available at http://pubsvn.ez.no/nextgen/stable/3.10/bin/php/updateniceurls.php but it's not double tested so I don't think we can recommend using it when upgrading to 3.10.0.
  • no ezwebin upgrade instructions

    Quote:
    ""It is also possible to upgrade the Website Interface extension to a newer version (you can find more information and instructions in the "Upgrading the Website Interface" chapter of the Website Interface installation guide).""

    There is no "Upgrading the Website Interface" chapter on that page.
    • Re: no ezwebin upgrade instructions

      Please have a look once again. You need to download the Website Interface installation guide for the corresponding version of ezwebin from the given link, it is a PDF file. You will find the "Upgrading the Website Interface" chapter there on page 8.