from 3.4.4 to 3.5.0

This section describes how to upgrade your existing eZ publish 3.4.4 installation to version 3.5.0. If you are upgrading from a version prior to eZ publish 3.4.4, you need to first upgrade to 3.4.4 before you can upgrade to 3.5.0.

Please 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.5.0
Upgrading the database to 3.5.0
Running the 3.5.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.5.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 then 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.4.4 database can be upgraded to 3.5.0.

MySQL

Navigate into the eZ publish 3.5.0 directory.

Run the database upgrade script:

mysql -u <username> -p<password> <database> < update/database/mysql/3.5/dbupdate-3.4.4-to-3.5.0.sql

PostgreSQL

Navigate into the eZ publish 3.5.0 directory.

Run the database upgrade script:

psql -d <database> -U <dbowner> < update/database/postgresql/3.5/dbupdate-3.4.4-to-3.5.0.sql

Step 3: Running the 3.5.0 upgrade scripts

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

Content class structure changes

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. In order to be compatible with this functionality, you will have to run the "updateiscontainer.php" script 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 will only need to run the script for one of the siteaccesses:

Navigate into the eZ publish 3.5.0 directory.
Run the script (replace "example" with the name of your siteaccess(es)):
```
php update/common/scripts/updateiscontainer.php -s example
```

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.

Updating the nice URLs (optional)

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. It is recommended (but not required) to run the "updateniceurls.php" script in order to update your nice URLs:

Navigate into the eZ publish 3.5.0 directory.

Run the script:

php update/common/scripts/updateniceurls.php

Updating the search index (optional)

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 run the "updatesearchindex.php" script with the "--clean" option in order to update the search index of your site:

Navigate into the eZ publish 3.5.0 directory.

Run the script:

php update/common/scripts/updatesearchindex.php --clean

The "--clean" option (added in eZ publish 3.3-1) means that the existing search index data should be removed before starting indexing.

Step 4: Updating the system configuration

Administration interface changes

The administration interface has been completely renewed in 3.5.0, and it requires two new override files. These are created automatically for new installations but should be copied manually when upgrading:

cp settings/siteaccess/admin/override.ini.append.php settings/siteaccess/example_admin/
 
cp settings/siteaccess/admin/icon.ini.append settings/siteaccess/example_admin/

Replace "example_admin" with the actual name of your admin siteaccess.
In order to be compatible with new functionality, you will also need to specify the "CachedViewPreferences" setting in the "site.ini.append.php" configuration file of your admin siteaccess:

[ContentSettings]
CachedViewPreferences[full]=admin_navigation_content=0;admin_navigation_details=0;admin_navigation_languages=0;admin_navigation_locations=0;admin_navigation_relations=
0;admin_navigation_roles=0;admin_navigation_policies=0;admin_navigation_content=0;admin_navigation_translations=0;admin_children_viewmode=list;admin_list_limit=1;admin
_edit_show_locations=0;admin_url_list_limit=10;admin_url_view_limit=10;admin_section_list_limit=1;admin_orderlist_sortfield=user_name;admin_orderlist_sortorder=desc;ad
min_search_stats_limit=1;admin_treemenu=1;admin_bookmarkmenu=1;admin_left_menu_width=13

If you have a large site that contains a lot of content objects, then it may be useful to reduce the number of objects shown in the left tree menu in the administration interface. It is possible to configure the tree menu limitations so that it for example only shows certain types of nodes, only goes to a certain depth and so on. Configuration should be done by creating an override for the "contentstructuremenu.ini" file.

Configuring the smart viewcache cleaning system (optional)

If you have not configured the smart viewcache cleaning system before (this feature is available from version 3.4.2), then you will probably need to do this. This feature allows to determine which additional nodes the system should clear the caches for when the content of an object is changed (by default, the view cache will be cleared for all published nodes of this object, their parent nodes, nodes of reverse related objects and nodes of objects with the same keyword). Please note that this step is only required if you are running a complex site or if you have cache problems after upgrading (for example, if your changes to content are not visible on some pages).

New folders under the "Media" top level node

You need to create three new folders called "Files", "Images" and "Multimedia" under the "Media" top level node. These will be used for autoplacement of uploaded files.

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.5.0 directory.
Run the clear cache script:
```
bin/shell/clearcache.sh --clear-all
```

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