This section describes how to upgrade your existing eZ Publish 4.3 installation directly to version 4.7. Make sure that you have a working backup of the site before you do the actual upgrade, and make sure the installation you are performing the upgrade on is offline.

Important upgrade notes:

The procedure for upgrading directly from version 4.3 to 4.7 consists of the following steps:

• Upgrade the distribution files to 4.7
• Upgrade custom extensions

  • 4.3.to 4.4
  • 4.4 to 4.5
  • 4.5 to 4.6
  • 4.6 to 4.7
• Upgrade the database to 4.7

  • 4.3 to 4.4
  • 4.4 to 4.5
  • 4.5 to 4.6
  • 4.6 to 4.7
• Regenerate the autoload array for extensions
• Run the system upgrade scripts for 4.7

  • 4.3 to 4.4
  • 4.4 to 4.5
  • 4.5 to 4.6
  • 4.6 to 4.7
• Additional upgrade step
• Enable ezjscore
• Enable admin2-design for back-end
• Clear the caches
• Upgrade extensions

Check for requirements

The eZ Components and PHP requirements

The minimum version required of eZ Components with eZ Publish 4.7 is "ezcomponents-ezp47", containing a fix to the package. This version is bundled in eZ Publish 4.7 Enterprise. eZ Publish 4.7 is compatible with PHP version 5.3 and above, but certified on RHEL 6 and Debian 6, PHP 5.3.x distros. See eZ Publish Requirements for more info.

Step 1: Upgrade the distribution files

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

• design/example
• design/example_admin
• var
• settings/siteaccess
• settings/override
• index_cluster.php if running cluster mode
   

Note: if your cluster index file is named this way, copy it under a new, temporary  name. Migration of this file is explained later in the procedure.

Replace "example" and "example_admin" with the actual names of your site accesses.

Important note: Because the new directory has replaced the original directory, the directory permissions need to be fixed. You have the choice between Shell commands or Alternative shell commands.

Use the following commands to do this:

• Shell commands

These shell commands will give proper permission to the web server:

cd </path/to/your/eZ/Publish/directory>
chmod -R a+rwx design extension settings var

• Alternative shell commands

 These commands will setup the permission more correctly, but require knowledge about the running web server (change 'nouser' to http server user).

cd </path/to/your/eZ/Publish/directory>
chmod -R og+rwx design extension settings var
chown -R nouser:nouser design extension settings var

Step 2: Upgrade custom extensions

If you are using custom extensions, the sub-directories inside the "extension" directory will also have to be copied. However, make sure that you do not overwrite any extensions that are included in eZ Publish, which currently are eZ Flow (2.x), eZ Online Editor (5.x), eZ OpenOffice Document format (2.x), eZ JSCore (1.x), eZ Image Editor (1.x), eZ Comments (1.x), eZ Multiupload (1.x), eZ MB Password Expiry (1.x), eZ Network (1.x), eZ REST API Provider (1.x), eZ Script Monitor (1.x), eZ SI, eZ Find (2.x). Note that upgrading the distribution files will overwrite the autoload arrays for extensions. You will need to regenerate the autoload arrays for active extensions later.

See the dedicated upgrade instructions for eZ Flow and Website Interface below.

The updated versions of eZ Flow and Website Interface will also install the following extensions:

• eZ Website Toolbar
• eZ Star Rating
• eZ Google Maps Location

Note: For eZ Online Editor 5.x and eZ JS Core you will need to replace the following rewrite rules when using Virtual Hosts:

RewriteRule ^/var/cache/texttoimage/.* - [L]
RewriteRule ^/var/[^/]+/cache/(texttoimage|public)/.* - [L]

with:

RewriteRule ^/var/([^/]+/)?cache/(texttoimage|public)/.* - [L]

For more detailed instructions, see the dedicated eZ OE and eZ JS Core doc pages.

Step 3: Upgrade the database

The update script for the database is located in the following locations. Skip the ones that don't apply to the version your upgrading from:

<eZ Publish root>/update/database/<mysql|postgresql>/4.4/dbupdate-4.3.0-to-4.4.0.sql
<eZ Publish root>/update/database/<mysql|postgresql>/4.5/dbupdate-4.4.0-to-4.5.0.sql
<eZ Publish root>/update/database/<mysql|postgresql>/4.6/dbupdate-4.5.0-to-4.6.0.sql
<eZ Publish root>/update/database/<mysql|postgresql>/4.6/dbupdate-4.6.0-to-4.7.0.sql

You can run these with the appropriate sql command line tool or application.

If you are using a DFS cluster, you must run the following query:

ALTER TABLE `ezdfsfile` CHANGE `datatype` `datatype` VARCHAR(255);

and if you are using a DB cluster, you ust run the following query:

ALTER TABLE `ezdbfile` CHANGE `datatype` `datatype` VARCHAR(255);

MySQL

The "ezmysql" database driver has been deprecated in 4.5 and it is recommended to use the "ezmysqli" driver instead. This requires that the "mysqli" extension in PHP is enabled and can be archived by changing the driver in your override or siteaccesses "site.ini.append.php" settings to:

[DatabaseSettings]
DatabaseImplementation=ezmysqli

Cluster

In version 4.7, the way the eZ Publish cluster is configured has completely changed. Until this version, a custom index_cluster.php file that contained the configuration had to be created, and included the file actually delivering the assets. This method is deprecated. index_cluster.php now exists by default in the distribution, and cluster configuration is done in the custom config.cluster.php file (or config.php).

Upgrading will be as simple as replicating the configuration variables (up to a dozen) previously defined in index_cluster.php, and put them in config.cluster.php.

More details about these directives can be found in the DFS or DB clusters configuration instructions, and more in-depth information about the configuration directives can be found in the cluster configuration settings documentation.

Step 4: Regenerate the autoload array for extensions

The autoload system also has some changes, for example the autoload array for extensions is now placed in var/autoload of your eZ Publish installation (along the class changes in extensions itself).

To regenerate the autoload array, execute the following script from the root of your eZ Publish directory: 

php bin/php/ezpgenerateautoloads.php --extension

Step 5: Run the system upgrade scripts

4.3 to 4.4

The update script for this version contained a bug and is repeated in 4.4 to 4.5 below, thus it is not needed in this instruction.

4.4 to 4.5

For eZ Publish 4.4 which was upgraded from 4.3, run the following command from the root of your eZ Publish directory:

php update/common/scripts/4.5/updatesectionidentifier.php -s $SITE_ACCESS

Note: Skip this step if your 4.4 installation is not an upgrade from 4.3. If you are uncertain, please run the script.

4.5 to 4.6

There are two system upgrade scripts that can be run for the eZ Publish 4.6 upgrade, "removetrashedimages.php" and "updateordernumber.php".

Script 1: If you want to ensure that no trashed images remain on your setup because of image aliases not being restored when restoring object from trash (issue #017781), you must do the following:

1. Make sure that no items remain in trash for any users (images from objects in trash would be impossible to restore not doing so)
2. Run the following cleanup script by executing this command:

$ php update/common/scripts/4.6/removetrashedimages.php

Note: It is safe to skip this test, this is only to free extra space.

Script 2: You need to run an upgrade script to update webshop order numbers issue (#018233) by running:

$ php update/common/scripts/4.6/updateordernumber.php

Note: If you don’t have a webshop or if you don’t have orders (table "ezorder") in your eZ Publish, you don’t have to run this script.

4.6 to 4.7

Mobile device detection

When upgrading from eZ Publish 4.6 to 4.7 and you are using eZ Flow, you can benefit from the new mobile device detection feature. Put the following settings in your "settings/override/site.ini.append.php" file:

[SiteAccessSettings]
 [...]
 DetectMobileDevice=enabled
 MobileSiteAccessURL=http://example.com/iphoneMobileSiteAccessList[]
 MobileSiteAccessList[]=iphone
 [...]

An "iphone" siteaccess is provided out-of-the-box with your eZ Flow installation. Make sure that the MobileSiteAccessURL= points to the "iphone" site access. Note that this is a full URL and needs to include the http:// part.

The new object edit form in the Administration interface

While upgrading eZ Flow to the next release, you will have to replace the following override condition in "settings/siteaccess/<admin siteaccess>/override.ini.append.php". This is to adjust to the changes in the object edit form in the Administration interface.

[edit_frontpage]
Source=content/edit.tpl
MatchFile=edit/frontpage.tpl
Subdir=templates
Match[class_identifier]=frontpage

with this new one

[add_to_block_frontpage]
Source=content/parts/add_to_block.tpl
MatchFile=content/parts/add_to_block_frontpage.tpl
Subdir=templates
Match[class_identifier]=frontpage

The same operation may have to be done if the same override condition has been added for other class_identifier than "frontpage".

Step 6: Additional upgrade steps

Update "override.ini.append.php"

Content panes are not visible on the "User accounts" tab in the back-end. To fix it on an already-installed eZ Publish, remove the following rules from your "override.ini.append.php" for your admin siteaccess:

[window_controls]
Source=window_controls.tpl
MatchFile=window_controls_user.tpl
Subdir=templates
Match[navigation_part_identifier]=ezusernavigationpart
 
[windows]
Source=windows.tpl
MatchFile=windows_user.tpl
Subdir=templates
Match[navigation_part_identifier]=ezusernavigationpart

Deprecated function (ezi18n()) in eZ Starrating

There is a deprecated function (ezi18n()) in extension eZ Starrating for eZ Publish versions 4.2, 4.3, 4.4.

This will generate an error if you try to clear the cache, when doing a direct upgrade to 4.7.

You need to manually disable this extension:

edit settings/override/site.ini.append.php and remove or comment the following line
ActiveExtensions[]=ezstarrating

You need to activate the extension again after upgrading the respective packages

... and clear the cache after disabling it. See separate step below.

Step 7: Clear 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 4.5 directory.
2. Run the script using the following shell command:

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.

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 sub-directories 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.

Step 8: Upgrade extensions

When upgrading from eZ Publish 4.6 to 4.7 and you are using eZ Flow, you can benefit from the new mobile device detection feature. Put the following settings in your "settings/override/site.ini.append.php" file:

[SiteAccessSettings]
[...]
DetectMobileDevice=enabled
MobileSiteAccessURL=http://example.com/iphone
MobileSiteAccessList[]
MobileSiteAccessList[]=iphone
[...]

An "iphone" siteaccess is provided out-of-the-box with your eZ Flow installation. Make sure that the MobileSiteAccessURL= points to the "iphone" site access. Note that this is a full URL and needs to include the http:// part.

New object edit form in the Administration interface

While upgrading eZ Flow to the next release, you will have to replace the following override condition in "settings/siteaccess/<admin siteaccess>/override.ini.append.php". This is to adjust to the changes in the object edit form in the Administration interface.

[edit_frontpage]
Source=content/edit.tpl
MatchFile=edit/frontpage.tpl
Subdir=templates
Match[class_identifier]=frontpage

with this new one

[add_to_block_frontpage]
Source=content/parts/add_to_block.tpl
MatchFile=content/parts/add_to_block_frontpage.tpl
Subdir=templates
Match[class_identifier]=frontpage

The same operation may have to be done if the same override condition has been added for other class_identifier than "frontpage".

eZ Flow & eZ Webin

When using eZ Webin and eZ Flow, these extensions will also need to be updated. Follow the dedicated upgrade instructions, depending on what version you are upgrading from.

4.3 to 4.4

eZ Webin 1.6 to 1.7
eZ Flow 2.1 to 2.2

4.4 to 4.5

eZ Webin 1.7 to 1.8
eZ Flow 2.2 to 2.3

4.4 to 4.5

eZ Webin 1.8 to 1.9
eZ Flow 2.3 to 2.4

4.6 to 4.7

eZ Webin 1.9 to 2.0
eZ Flow 2.4 to 2.5