General

  eZ Systems Website
  Editor documentation


  Developer documentation

  Back to the top

The documentation is moving!

We're moving our developer docs to Github and a new site.
The migration is still in progress, so please contact us in #documentation-contrib on eZ Community Slack if you have any questions or feedback.

This space will not be updated from now on except for critical fixes.

Versions Compared

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.

This page explains how to update eZ Platform to a new version.

In the instructions below, replace <version> with the version of eZ Platform you are updating to (for example: v1.7.0). If you are testing a release candidate, use the latest rc tag (for example: v1.7.1-rc1).

Version-specific steps

Note

Some versions introduce new features that require taking special steps; they are marked on this page with yellow tags.

If you intend to skip a version (for example, update directly from v1.3 to v1.5 without getting v1.4), remember to look at all the intermediate steps as well – this means you need to perform both the steps for v1.4 and v1.5.

Update procedure

1. Check out a version

1.1. From the project's root, create a new branch from the project's master, or from the branch you're updating on:

Code Block
languagebash
titleFrom your master branch
git checkout -b <branch_name>

This creates a new project branch for the update based on your current project branch, typically master. An example <branch_name> would be update-1.4.

1.2. If it's not there, add ezsystems/ezplatform (or ezsystems/ezplatform-ee, when updating an Enterprise installation) as an upstream remote:

Code Block
languagebash
titleFrom your new update branch
git remote add ezplatform http://github.com/ezsystems/ezplatform.git
or
git remote add ezplatform-ee http://github.com/ezsystems/ezplatform-ee.git

1.3. Then pull the tag into your branch.

Tip

If you are unsure which version to pull, run git ls-remote --tags to list all possible tags.

Code Block
languagebash
titleFrom your new update branch
git pull ezplatform <version>
or
git pull ezplatform-ee <version>

At this stage you may get conflicts, which are a normal part of the procedure and no reason to worry. The most common ones will be on composer.json and composer.lock.

The latter can be ignored, as it will be regenerated when we execute composer update later. The easiest is to checkout the version from the tag and add it to the changes:

Note

If you get a lot of conflicts (on the doc folder for instance), and eZ Platform was installed from the share.ez.no tarball, it might be because of incomplete history. You will have to run git fetch ezplatform --unshallow (or git fetch ezplatform-ee --unshallow) to load the full history, and run the merge again.

Code Block
languagebash
titleFrom your new update branch
git checkout --theirs composer.lock && git add composer.lock

If you do not keep a copy in the branch, you may also run:

Code Block
languagebash
titleFrom your new update branch
git rm composer.lock

2. Merge composer.json

Manual merging

Conflicts in composer.json need to be fixed manually. If you're not familiar with the diff output, you may checkout the tag's version and inspect the changes. It should be readable for most:

Code Block
languagebash
titleFrom your new update branch
git checkout --theirs composer.json && git diff HEAD composer.json

You should see what was changed, as compared to your own version, in the diff output. The update changes the requirements for all of the ezsystems/ packages. Those changes should be left untouched. All of the other changes will be removals of what you added for your own project. Use git checkout -p to selectively cancel those changes:

Code Block
git checkout -p composer.json

Answer no (do not discard) to the requirement changes of ezsystems dependencies. Answer yes (discard) to removals of your changes.

Once you are done, inspect the file, either using an editor or by running git diff composer.json. You may also test the file's sanity with composer validate, and test the dependencies by running composer update --dry-run. (will output what it would do to dependencies, without applying the changes.

Once finished, run git add composer.json and commit.

Fixing other conflicts (if any)

Depending on the local changes you have done, you may get other conflicts on configuration files, kernel, etc.

There shouldn't be many, and you should be able to figure out which value is the right one for all of them:

  • Edit the file, and identify the conflicting changes. If a setting you have modified has also been changed by us, you should be able to figure out which value is the right one.
  • Run git add conflicting-file to add the changes

3. Update the app

At this point, you should have a composer.json file with the correct requirements. Run composer update to update the dependencies. 

Code Block
composer update
Tip

If you want to first test how the update proceeds without actually updating any packages, you can try the command with the --dry-run switch:

composer update --dry-run

Info
titleOn PHP conflict | 16.02 and later requires PHP 5.5 or higher

Because from release 16.02 onwards eZ Platform is compatible only with PHP 5.5 and higher, the update command above will fail if you use an older PHP version. Please update PHP to proceed.

Panel
bgColor#ffffff
titleBGColor#ffffff
titleAdding EzSystemsPlatformEEAssetsBundle

Status
colourYellow
titlev1.10

Status
colourYellow
titleenterprise

When upgrading to v1.10, you need to enable the new EzSystemsPlatformEEAssetsBundle by adding:

new EzSystems\PlatformEEAssetsBundle\EzSystemsPlatformEEAssetsBundle(),

in app/AppKernel.php.

 

4. Update database

This step is only relevant for some releases:

Panel
bgColor#ffffff
titleBGColor#ffffff
titlecontent/publish permission

Status
colourYellow
titlev1.8

v1.8.0 introduced a new content/publish permission separated out of the content/edit permission. edit now covers only editing content, without the right to publishing it. For that you need the publish permission. edit without publish can be used in conjunction with the Content review workflow to ensure that a user cannot publish content themselves, but must pass it on for review.

To make sure existing users will be able to both edit and publish content, those with the content/edit permission will be given the content/publish permission by the following database update script:

Code Block
mysql -u <username> -p <password> <database_name> < vendor/ezsystems/ezpublish-kernel/data/update/mysql/dbupdate-6.7.0-to-6.8.0.sql
Panel
bgColor#ffffff
titleBGColor#ffffff
titleSolr Bundle 1.4: Index time boosting

Status
colourYellow
titlev1.10 / v1.9.1 / v1.7.4

Solr Bundle v1.10.0 4 introduced among other things index time boosting feature in Solr Bundle v1.4, this involves a slight change to the solr config scheme that will need to be applied to your config.

To make sure indexing continues to work, apply the following change, restart solr and reindex your content:

Code Block
languagediff
diff --git a/lib/Resources/config/solr/schema.xml b/lib/Resources/config/solr/schema.xml
index 49a17a9..80c4cd7 100644
--- a/lib/Resources/config/solr/schema.xml
+++ b/lib/Resources/config/solr/schema.xml
@@ -92,7 +92,7 @@ should not remove or drastically change the existing definitions.
     <dynamicField name="*_s" type="string" indexed="true" stored="true"/>
     <dynamicField name="*_ms" type="string" indexed="true" stored="true" multiValued="true"/>
     <dynamicField name="*_l" type="long" indexed="true" stored="true"/>
-    <dynamicField name="*_t" type="text" indexed="true" stored="true"/>
+    <dynamicField name="*_t" type="text" indexed="true" stored="true" multiValued="true" omitNorms="false"/>
     <dynamicField name="*_b" type="boolean" indexed="true" stored="true"/>
     <dynamicField name="*_mb" type="boolean" indexed="true" stored="true" multiValued="true"/>
     <dynamicField name="*_f" type="float" indexed="true" stored="true"/>
@@ -104,13 +104,6 @@ should not remove or drastically change the existing definitions.
     <dynamicField name="*_c" type="currency" indexed="true" stored="true"/>
 
     <!--
-      Full text field is indexed through proxy fields matching '*_fulltext' pattern.
-    -->
-    <field name="text" type="text" indexed="true" multiValued="true" stored="false"/>
-    <dynamicField name="*_fulltext" type="text" indexed="false" multiValued="true" stored="false"/>
-    <copyField source="*_fulltext" dest="text" />
-
-    <!--
       This field is required since Solr 4
     -->
     <field name="_version_" type="long" indexed="true" stored="true" multiValued="false" />
Panel
bgColor#ffffff
titleBGColor#ffffff
titleForm Builder

Status
colourYellow
titlev1.7

Status
colourYellow
titleez enterprise

To enable the Form Builder feature in eZ Platform Enterprise Edition, import the following file:

Code Block
mysql -p -u <database_user> <database_name> < vendor/ezsystems/ezstudio-form-builder/bundle/Resources/install/form_builder.sql
Panel
bgColor#ffffff
titleBGColor#ffffff
titleDate Based Publisher

Status
colourYellow
titlev1.7

Status
colourYellow
titleez enterprise

To enable the Date-Based Publisher feature in Enterprise, import the following file:

Code Block
mysql -p -u <database_user> <database_name> < vendor/ezsystems/date-based-publisher/bundle/Resources/install/datebasedpublisher_scheduled_version.sql

In order to activate Date-Based Publisher open console (terminal) and use:

Code Block
languagebash
crontab -e

and add below configuration at the end of edited file.

For production environment:

Code Block
* * * * *   (cd /path/to/your/ezplatform-ee-project && app/console ezpublish:cron:run -e=prod)

For development environment:

Code Block
* * * * *   (cd /path/to/your/ezplatform-ee-project && app/console ezpublish:cron:run -e=dev)
Panel
bgColor#ffffff
titleBGColor#ffffff
titleFolder for form-uploaded files

Status
colourYellow
titlev1.8

Status
colourYellow
titleez enterprise

Note

To complete this step you have to dump assets first.

Since v1.8 you can add a File field to the Form block on a Landing Page. Files uploaded through such a form will be automatically placed in a specific folder in the repository.

If you are upgrading to v1.8 you need to create this folder and assign it to a new specific Section. Then, add them in the config (for example, in app/config/default_parameters.yml, depending on how your configuration is set up):

Code Block
languagenone
    #Location id of the root for form uploads
    form_builder.upload_folder.location_id: <folder location id>

    #Section identifier for form uploads
    form_builder.upload_folder.section_identifier: <section identifier>

5. Dump assets

The web assets must be dumped again if you are using the prod environment. In dev this happens automatically:

Code Block
php app/console assetic:dump -e=prod

If you encounter problems, additionally clear the cache and install assets:

Code Block
php app/console cache:clear -e=prod
php app/console assets:install --symlink -e=prod
php app/console assetic:dump -e=prod

6. Commit, test and merge

Once all the conflicts have been resolved, and composer.lock updated, the merge can be committed. Note that you may or may not keep composer.lock, depending on your version management workflow. If you do not wish to keep it, run git reset HEAD <file> to remove it from the changes. Run git commit, and adapt the message if necessary. You can now verify the project and once the update has been approved, go back to master, and merge your update branch:

Code Block
git checkout master
git merge <branch_name>

 

Your eZ Platform should now be up-to-date with the chosen version!

 

Related:

In this topic:

Table of Contents
maxLevel3