Upgrade Notes for Pimcore 4.6.x to Pimcore 5.0

IMPORTANT!
This page only lists all the changes from version 4.6.x to 5.0.
If you're looking for step-by-step instructions for upgrading, please have a look at our migration guide.

System Requirements

• PHP >= 7.0 (please note that Pimcore 5.3 requires already PHP 7.1)
• intl

Database

• Pimcore is now using Doctrine DBAL.
• Zend_Db_Select is still supported with compatibility layer. Following changes are necessary:
  • If $db->select() was used to get Zend_Db_Select nothing has to be changed.
  • new \Zend_Db_Select() needs to be replaced with new \Pimcore\Db\ZendCompatibility\QueryBuilder().
  • new \Zend_Db_Expr() needs to be replaced new \Pimcore\Db\ZendCompatibility\Expression().
• $db->describeTable() not supported anymore.
• Signatures of $db->update() and $this->delete() where changed. Use $db->deleteWhere() and $db->updateWhere() instead for same functionality.
• If you experience the error "mysql server has gone away" consider using this code snippet
• Needed SQL updates are included in the pimcore-4-to-5.php update script which you should excute during the migration. See basic migration

System Settings

• Pimcore php configuration files moved to following directories
  • app/config/pimcore/ for files that are not editable within Pimcore admin interface.
  • var/config for files that can be edited within Pimcore admin interface.
• Configuration for HTTP basic auth was removed. Please configure HTTP auth directly through your web server or use the Security Configuration to configure authentication.
• Reconfigure following things:
  • Mail-Settings
  • HTTP Connectivity

Website Config

• Website config settings are not available via $this->config in controllers and views anymore, but exposed through view a websiteConfig()/pimcore_website_config() view helper/Twig tag. In controllers, the website config can be requested as action argument by type hinting the argument with \Pimcore\Config\Config $websiteConfig. See Website Settings for details.

Objects were renamed to Data Objects

The introduction of object type hints in PHP 7.2 forced us to rename several namespaces to be compliant with the PHP 7 reserved words.

• Namespace Pimcore\Model\Object was renamed to Pimcore\Model\DataObject
  • PHP classes of Data Objects are now also in the format eg. Pimcore\Model\DataObject\News
• There's a compatibility autoloader which enables you to still use the former namespace (< PHP 7.2), but you should migrate asap. to the new namespaces.
• Object Placeholders syntax changed to %DataObject()

Cache

• Pimcore is now using a PSR-6 compatible cache.
• The following backends are not supported any longer:
  • MongoDB
  • Memcache
• Pimcore uses a different configuration for the cache
• The former get parameter nocache for disabling the entire cache for a certain request, was renamed to pimcore_nocache.

Model Overrides in website/config/di.php

website/config/di.php isn't supported anymore. Custom class mappings / overrides are now configured in app/config/config.yml. Please have a look at Overriding Models.

Logging

• PHP Errors are logged automatically to /var/logs/ENV.log
• Email logs, see: [http://symfony.com/doc/3.4/logging/monolog_email.html]
• Logging levels are specified in Symfony config
• \Logger::log($message, $loglevel) is not supported anymore

Document Editables

• Areabricks have a new format and now depend on a brick class registered as service. For details see Areabrick Documentation
• Renderlet controllers do not recieve the element, object, and document parameters anymore (document is present, but references the content document the renderlet belongs to). To fetch the linked object, please use the type and id parameters.
• Document editables now use a different naming format for nested editables. Please see the upgrade notes regarding build 54 in the upgrade within V5 upgrade notes documentation and add the configuration entry for the legacy naming to your config or execute the naming migration script. Details on the migration can be found in Editable Naming Strategies.

Document Templates

• Set Layout only in view template possible and implemented with extend, details see layout docs.

$this->extend('Appbundle::layout.html.php')

• Extend always bound to view template (cannot be switched on/off). As a result if a template that contains a $this->extend is included with $this->template into another template, that contains a $this->extend by itself, the layout is rendered twice

• $this->template needs echo to print included template

echo $this->template("Appbundle:Snippets:standard-teaser.html.php", ["myparam" => "foo"]);

• When template is included with $this->template following parameter names cannot be used with $this->parameterName notation
  • current
  • container
  • loader
  • helpers
  • parents
  • stach
  • charset
  • cache
  • escapers
  • globals
  • parser
  • evalTemplate
  • evalParameter

Controller Plugins

• Replaced by Kernel Events

• Replaced by Routes

Translations (Shared + Admin)

• Use of Standard Symfony Translation Component

• Supporting domains / bundles, ...

• Translations are now case sensitive by default. You can reconfigure Pimcore to handle website and admin translations as case insensitive. However, as this implies a performance hit (translations might be looked up twice) and it does not conform with Symfony's translators you're encouraged to reference translation keys with the same casing as they were saved. You can turn case insensitive handling on by setting the following config setting (see #2005):

  pimcore:
      translations:
          case_insensitive: true
  

• Dot-separated fallback notation isn't supported anymore

E-Mail

• Pimcore\Mail now extends Swift_Message instead of Zend_Mail
• The most common methods should be as they were, following method signature changes are significant:
  • __construct($subject = null, $body = null, $contentType = null, $charset = null)
  • addAttachment(\Swift_Mime_Attachment $attachment)
  • createAttachment($data, $mimeType = null, $filename = null, $disposition = null)
  • send(\Swift_Mailer $mailer = null) & sendWithoutRendering(\Swift_Mailer $mailer = null)
• check all usages of Pimcore\Mail

Thumbnails

• PicturePolyfill isn't included automatically anymore when Pimcore uses the <picture> HTML-tag. Include it manually in your layout if you need IE support.

Custom Routes

All parameters needed for assembly url (mentioned in reverse) must be listed in variables.

Events

The Event Manager got replaced by Symfony framework event dispatcher. There is a compatibility layer for the Pimcore 4 event manager events though. Except the listed events below, you still could use the Pimcore 4 events.

But it's recommended to use the new event constants instead. For details see event docs.

From Plugins to Bundles

• With Pimcore 5 Pimcore Plugins became default Symfony Bundles. See our bundles docs for more details.

Adding Object Data Types via Extensions

• Object Data and Layout Types are configured in pimcore.objects.class_definitions.data.map and pimcore.objects.class_definitions.layout.map in Symfony configuration files.
• As fallback namespace/name matching are still available and configurable via pimcore.objects.class_definitions.data.prefixes and pimcore.objects.class_definitions.layout.prefixes
• Plugins/Bundles can add new data types by adding their data types to the configuration entries above

Console Commands

• Console Commands need to be in the Console namespace and their class name needs to end with Console. See Symfony Console Documentation.
• The function $application->addAutoloadNamespace() does not exist any more.
• The --environment option was dropped as it is already existing as --env in all Symfony commands.
• For more details see console docs.
• The following commands were moved under a pimcore: prefix, but are still available as aliases under their old names. The aliases might be removed in later versions, so please use the new names.

| maintenance | pimcore:maintenance | | mysql-tools | pimcore:mysql-tools | | reset-password | pimcore:user:reset-password | | search-backend-reindex | pimcore:search-backend-reindex | | update | pimcore:update |

• pimcore:user:reset-password command has a new signature, now accepting the user as first argument instead of the -u option.

Cron Jobs

Please check your Crontab, especially the maintenance command.

*/5 * * * * /your/project/bin/console maintenance

Also double-check the Installation Guide.

Zend Registry

• Replaced by \Pimcore\Cache\Runtime, interface compatible with Zend_Registry

\Pimcore\Cache\Runtime // (interface compatible with Zend_Registry)
// or
$this->get(\Pimcore\Cache\Runtime::class) // service container

Pimcore\Tool::getHttpClient()

• Is only available if Compatibility Bridge is available.
• Now returns GuzzleHttp\Client instead of Zend_Http_Client.
• New http client is also available on container with ID pimcore.http_client - should be used for new implementations.

Sessions

• If you need sessions, please use the native session handling provided by Symfony (configured through the framework.session config). For details see sessions docs.
• Pimcore adds the possibility to configure sessions before they are started through SessionConfiguratorInterface registered as service with the pimcore.session.configurator tag.
• Admin sessions Pimcore\Tool\Session::get/getReadonly() now return an AttributeBagInterface´ instead of a ´Zend_Session_Namespace. Calls to the bag need to be adapted as Symfony's bags do not support magic setters/getters as the Zend namespace did.
• Admin sessions are not handled in a custom isolated session from the frontend session anymore. Previous versions used to close an opened frontend session when opening an admin session. This logic was removed in favor of simpler session logic in one configurable session setup.
• The session ID for the admin session (and for sessions in general) can't be set via GET parameter anymore. This was possbile in previous Pimcore versions to support Flash based file uploaders but was obsolete.

International Number and Date Formatting

• Added a Service for international number and date formatting. For details see docs page.

Functionalities only available when using PimcoreLegacyBundle

• Legacy Underscore Naming Convention of old Pimcore class names like Object_Abstract, Document_Page, Asset_Image, ...

Deprecated Constants

Removed Features and Services

• ExtJs 3.4 Support: Support for ExtJS 3.4 has been finally removed as announced earlier. The current version in use is 6.0.0. Please double-check your extensions in advance!
• Object Key-Value Store: Use the Classification-Store instead.
• Whoops Error Handler: Got replaced by Symfony default error handler.
• startup.php not supported anymore: Use boot() function in AppKernel or AppBundle instead
• Removed Pimcore\Tool\XmlWriter Service
• Removed \Pimcore\File\Transfer* Classes
• Controller Plugins
  • \Pimcore\Controller\Plugin\CssCombine
  • \Pimcore\Controller\Plugin\CDN
  • \Pimcore\Controller\Plugin\Less

E-Commerce Framework

For migration of E-Commerce-Framework have a look at the breaking changes section.

Newsletter Source Adapter

Newsletter Source Adapter implementation has been changed to be able to register them using configuration. It is very easy to migrate your Adapter to Pimcore 5. Since nothing really changed, you only need to create a factory service that creates your AddressSourceAdapter

• If you are using a very simple Adapter Source, you can use the DefaultFactory

app.document.newsletter.factory.myAdapter:
    class: Pimcore\Document\Newsletter\DefaultAddressSourceAdapterFactory
    arguments:
      - 'App\Document\Newsletter\AddressSourceAdapter\MyAdapter'

• If you are using a more complex Source Adapter, you can create your own Factory by implementing the interface Pimcore\Document\Newsletter\Factory\AddressSourceAdapterFactoryInterface
• Add your Adapter Factory to the configuration:

pimcore:
    newsletter:
        source_adapters:
            myAdapter: app.document.newsletter.factory.myAdapter

Custom Report Adapter

Custom Report Adapter implementation has been changed to be able to register them using configuration. It is very easy to migrate your Adapter to Pimcore 5. Since nothing really changed, you only need to create a factory service that creates your CustomReportAdapterInterface

• If you are using a very simple Adapter Source, you can use the DefaultFactory

app.custom_report.adapter.factory.custom:
    class: Pimcore\Model\Tool\CustomReport\Adapter\DefaultCustomReportAdapterFactory
    arguments:
      - 'App\CustomReport\Adapter\Custom'

• If you are using a more complex Adapter, you can create your own Factory by implementing the interface Pimcore\Model\Tool\CustomReport\Adapter\CustomReportAdapterFactoryInterface
• Add your Adapter Factory to the configuration:

pimcore:
    custom_report:
        adapters:
            myAdapter: app.custom_report.adapter.factory.custom