Global navigation

   Documentation Center
   eZ Studio & eZ Platform
     User Manual
     Technical Manual
     Glossary
   eZ Publish 4.x / legacy

 
eZ Publish (5.x)

eZ Publish 5.x | For eZ Platform & eZ Studio topics see Technical manual and User manual, for eZ Publish 4.x and Legacy topics see eZ Publish legacy

Versions Compared

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.
Excerpt
Note
titleeZ Publish Platform 5.3 and higher

This page only applies to eZ Publish Platform 5.3 and higher, for earlier versions of the Enterprise version of eZ Publish consult Service Portal user guide available for download at support.ez.no. This page is also generic about using Composer, for instructions specific to a release, see release notes.

 

Keeping your system up-to-date is important, to make sure your it is running optimally and securely. The update mechanism in eZ Publish Platform is using the de facto standard PHP packaging system called Composer.
This makes it easy to adapt package installs and updates to your workflow, allowing you to test new/updated packages in a development environment, put the changes in your version control system (git, Subversion, Mercurial, etc.), pull in those changes on a staging environment and, when approved, put it in production.

...

Excerpt Include
glossary:Composer
glossary:Composer
isConfiguredtrue
preferencesspaceName=Glossary&spaceKey=glossary&quickfind-space=Glossary&pageId=23528552&pageName=Composer&quickfind-page=Composer&isConfigured=true&refresh=false&showLink=false&isEditable=false
authoreZ Systems
quickfind-space
refreshfalse
pageId23528552
pageNameComposer
urlrest/gadgets/1.0/g/com.atlassian.confluence.plugins.gadgets:confluence-page-gadget/gadgets/confluence-page-gadget.xml
spaceNamespaceKeyglossary
spaceName
isEditablefalse
width50%
showLinktrue
quickfind-pageComposer

...

To get access to these updates log in to your service portal on support.ez.no. If your project is configured for eZ Publish Platform 5.3 or higher, you will see the following on the "Maintenance and Support agreement details" screen:

  1. Click "Create token" (This requires the "Portal administrator" access level.)
  2. Fill in a label describing the use of the token. This will allow you to revoke access later
    • Example, if you need to provide access to updates to a third party a good to example would be "53-upgrade-project-by-partner-x"
  3. Copy the password, you will not get access to this again!

...

as Password: the token password you retrieved in step 3. 

Info
titleSupport agreement expiry

If your Support agreement expires, your authentication token(s) will no longer work. They will become active again if the agreement is renewed, but this process may take up to 24 hours. (If the agreement is renewed before the expiry date, there will be no disruption of service.)

 

Optional: Save authentication information in auth.json to avoid repeatedly typing it

To avoid having to always fill your credentials, add an Composer will ask to do this for you on updates, however if it is disabled you can create auth.json file at your project root, next composer.json, or in your manually in one of the following ways:

Option A: Store your credentials in project directory:

Code Block
languagebash
composer config http-basic.updates.ez.no <installation-key> <token-password>

Option B: If you rather want to install it globally in COMPOSER_HOME directory for machine-wide use. The file looks like the following:

{ "config": { "basic-auth": { "
Code Block
languagejs
titleauth.json
bash
composer config --global http-basic.updates.ez.no": {
                "username": "<installation-key>",                 "password": "<token password>"
            }
        }
    }
}

The fine print: bundled with eZ Publish Platform is a Composer extension which makes it possible to store authentication information in that file.

Using composer

Update workflow

<token-password>

Update workflow Using composer

This section describes a best practice for use of composer, essentially it suggests treating updates like other code/configuration/* changes on your project tackling them on a development machine before staging them for roll out on staging/production.  

...

Info
titleTip
Tip: Here the importance of composer.lock comes in as this command will tell composer to install packages in exactly same version as defined in composer.lock. If you don't keep track of composer.lock it will instead just install always latests version of a package, hence not allow you to stage updates before moving it towards production.

General notes on use of composer

Installing additional eZ packages via composer

Also requiring eZ Publish Platform packages via composer is nothing different then requiring vanilla packages via Composer, and for illustration here is how you install a eZ package:

Code Block
titlecomposer install (package installation)
php -d memory_limit=-1 composer.phar require --prefer-dist ezsystems/ezfind-ls:5.3.*

Using Composer with Legacy

(eZ Publish) Legacy by design places all important customizable folders within it's own structure. This is not ideal with Composer, as installation and updates might cause them to become as provided by packages again.
To make sure you are safe from this, and to allow you to version these custom folders independently, it is recommended that you use symlinks and keep your custom settings, extensions and design outside of the ezpublish_legacy folder. To not have to manually deal with these symlinks it is recommended to use Composer post-install-cmd and post-update-command script commands to make this automated.

...

Note
This functionality is desirable to have out of the box in the future, so community contributions on this topic is welcome to find a good standard convention and script to handle it.

Dump autoload

Avoid to use the following command:

php -d memory_limit=-1 composer.phar dump-autoload --optimize

Note
titleWarning

It causes a PHP Warning "Ambiguous class resolution". For further information this issue to Stash Github repository.

The dumped file will be too big and can cause an overhead for any request, even Cache.

Common errors

Cloning failed using an ssh key

When dealing with updates.ez.no packages, you might get this if you somehow tell composer to download dev packages, or tell it to download from source. Currently our updates.ez.no service only support distribution packages in alpha stability or higher, so make sure to check what stability and avoid use of --prefer-source (this is the reason examples above are using --prefer-dist).

Best practice for Bundles

Best practice for Bundles is described in Symfony documentation under Best Practices for Reusable Bundles, with eZ bundles there is some notable exceptions:

Documentation
  • You may write your documentation using markdown (.md) if you prefer, however .rst is recommended if you plan to use writethedocs.org, as heavily used by many open source projects.
Composer Metadata
  • For defining "type", the following are at the moment known valid values:
    • ezpublish-legacy-extension | For standalone 4.x (legacy) extensions, to be used with ezpublish-legacy-installer
    • ezpublish-bundle | For eZ Publish Platform 5.x bundles, may optionally be a "legacy bundle".
    • symfony-bundle | Standard symfony bundles as described in Symfony doc.
  • For eZ Platform and eZ Studio there is also:
    • ezplatform-bundle | Symfony bundles that uses eZ Platform features (may also be used by bundles that work across 5.x and 6.x ezpublish-kernel)
    • ezstudio-bundle | Symfony bundles that uses eZ Studio features (and optionally also eZ Platform features)
      • Deprecated: Please use ezplatform-bundle and add dependencies on the ee packages you depend on instead.