Was ist neu in Contao 5.0

Der LTS-Version 4.13 folgt ein großer Sprung auf die Version 5.0.

Erst vor wenigen Monaten - genau genommen im Februar 2022 - erschien das letzte Update auf eine neue LTS-Version, Contao 4.13. Jetzt ist es August und Contao 5.* steht vor der Tür. Es handelt sich aber noch nicht um eine LTS-Version. Diese erscheint voraussichtlich im August 2024 mit der Contao 5.3 LTS.

Wir möchten euch hier wieder einen Überblick über die wichtigsten Änderungen geben. Wer sich detailliert alle Änderungen und Bugfixes ansehen möchte, findet diese in den Milesones und der UPGRADE.md.

Beim Upgrade auf die Version 5.0 liegt der Schwerpunkt auf der weiteren Integration von Contao an das Framework Symfony. Daher bestehen die Änderungen im Wesentlichen aus dem Entfernen von Code. Kurz gesagt: Das Upgrade ist eine Aufräumaktion.

Dieser Feature-Bericht hat zwei Abschnitte. Zuerst findet ihr Infos für Redakteur:Innen und danach für Entwickler:Innen.

Letztes Update am 10.08.2022

Neues für Redakteur:Innen

• das Install-Tool wurde entfernt
  Die URL contao/install ist in Contao 5.* nicht mehr vorhanden. Redakteur:Innen und Admins sollten jetzt das contao-command contao:migrate nutzen. Details siehe:
  PR: Remove the Contao 4 migrations
  PR: Remove the install tool
  
  Die bisher bekannten Migrationen wurden in veränderter Weise in den Contao-Manager integriert. Es ist jetzt leider nicht mehr möglich, bei der Migration einzelne Tabellen zu aktivieren/deaktivieren. Alle wartenden Migrationen werden immer in einem Stück ausgeführt.
  
  
  

ACHTUNG! Ein Upgrade auf Contao 5 kann nur von Contao 4.13 aus durchgeführt werden!
Bitte stellt sicher, dass ihr eure Installation zuerst auf Contao 4.13 aktualisiert habt und erst danach das Upgrade auf Conto 5.0 ausführt!

• Das Menü »Inhalte« (content) wurde überarbeitet.
  Es ist jetzt bezüglich der Inhaltselemente klarer geordnet. Daher wurde auch der Link »Seiten« (pages) ganz oben angeordnet. Darunter folgen dann die »Artikel« (article). Wer den Link Dateiverwaltung unter System sucht: Dieser wurde ebenfalls nach »Inhalte« verschoben und befindet sich jetzt unterhalb von »Artikel«.
  
  
  
  
• das Modul »Automatischer Logout« wurde entfernt.
  Das bisher häufig verwendete Modul »Automatischer Logout« wurde entfernt. Stattdessen solltet ihr die Seite des Typs: »Abmelden« (logout) verwenden.
  
  
  
  
• Folgende Inhaltselemente werden durch Fragment-Controller bereitgestellt und verwenden daher nun Twig-Templates.
  Das ist bei der Verwendung eigener Templates für die Redakteur:Innen von Bedeutung. Wer sich genauer informieren möchte, der suche in den Milestones (Link siehe oben) nach »Modern Fragements«. Folgende Inhaltselemente wurden überarbeitet:
  
  code (ce_code → content_element/code)
  headline (ce_headline → content_element/headline)
  html (ce_html → content_element/html)
  list (ce_list → content_element/list)
  text (ce_text → content_element/text)
  table (ce_table → content_element/table)
  hyperlink (ce_hyperlink → content_element/hyperlink)
  toplink (ce_toplink → content_element/toplink)
  image (ce_image → content_element/image)
  gallery (ce_gallery → content_element/gallery)
  youtube (ce_youtube → content_element/youtube)
  vimeo (ce_vimeo → content_element/vimeo)
  
  Die bisherigen html5-Templates werden aber erst in Contao 6 entfernt und sind noch vorhanden. Wer die neuen Twig-Templates noch nicht nutzen möchte, kann die Nutzung der html5-Templates durch folgende Zeilen in der contao/config/config.php erzwingen:
  
  

  // Restore legacy content elements
  
  $GLOBALS['TL_CTE']['texts']['code'] = \Contao\ContentCode::class;
  $GLOBALS['TL_CTE']['texts']['headline'] = \Contao\ContentHeadline::class;
  $GLOBALS['TL_CTE']['texts']['html'] = \Contao\ContentHtml::class;
  $GLOBALS['TL_CTE']['texts']['list'] = \Contao\ContentList::class;
  $GLOBALS['TL_CTE']['texts']['text'] = \Contao\ContentText::class;
  $GLOBALS['TL_CTE']['texts']['table'] = \Contao\ContentTable::class;
  $GLOBALS['TL_CTE']['links']['hyperlink'] = \Contao\ContentHyperlink::class;
  $GLOBALS['TL_CTE']['links']['toplink'] = \Contao\ContentToplink::class;
  $GLOBALS['TL_CTE']['media']['image'] = \Contao\ContentImage::class;
  $GLOBALS['TL_CTE']['media']['gallery'] = \Contao\ContentGallery::class;
  $GLOBALS['TL_CTE']['media']['youtube'] = \Contao\ContentYouTube::class;
  $GLOBALS['TL_CTE']['media']['vimeo'] = \Contao\ContentVimeo::class;

• Folgende CSS-Klassen wurden entfernt:
  first, last, even, odd, row_* und col_*. Diese müsst ihr jetzt selbst definieren.

• Die Templates für ce_list und ce_table wurden geändert.
  Das führt bei einem Upgrade zu veränderten Darstellungen in Tabellen.
  
  
• Das Insert-Tag {{post::*}} wurde entfernt.
  Mit diesem Insert-Tag konnte man POST-Parameter eines Formulars anzeigen. Um zukünftig auf Formulardaten zuzugreifen, kann man das neue Insert-Tag {{form_session_data::*}} verwenden.
  
  
• Der interne CSS-Editor wurde entfernt.
  Vor einem Upgrade solltet ihr die CSS-Dateien exportieren und dann im Contao 5 in der Dateiverwaltung wieder importieren. Schließlich müsst Ihr die so importierte Datei im Layout als externe CSS-Datei referenzieren.

Für Entwickler:Innen

Für Entwickler und Entwicklerinnen hat sich einiges geändert. Der wesentliche Anteil der ca. 300 Änderungen bezieht sich nämlich auf den Contao Core. Wir haben hier nur die wichtigsten Änderungen aufgeführt. Ausführlichere Angaben findet ihr hier in den Milestones 5.0.

• Contao 5 kann jetzt mit Symfony 6 verwendet werden.
  
  
• PHP 8.1 ist mindestens erforderlich.
  
  
• PHP 8 Attribute werden jetzt überall unterstützt.
  Die sog. Annotations sollten nicht mehr verwendet werden. Sie sind zwar noch nicht entfernt worden, stattdessen können alle Annotaions jetzt auch mit nativen PHP-8-Attributen notiert werden. Die Dokumentation wurde bereits angepasst. Dort findet ihr Beispiele.
  
  
• Der Support von runonce-Dateien wurde entfernt.
  Verwendet bitte zukünftig das Migration-Framework.
  
  
• Der Eintrittspunkt app.php wurde entfernt
  In Zukunft wird ausschließlich der Eintrittspunkt index.php verwendet.
  
  
• Der Schlüssel 'exclude' in DCA 'fields' wird künftig beim Laden eines Modules nicht mehr initialisiert
  Die Entwickler:Innen haben dafür zu sorgen, dass dass Benutzer gewisse Rechte für ein Feld haben. Das kann zukünftig mit der Konstante? ContaoCorePermission::USER_CAN_EDIT_FIELD_OF_TABLE realisiert werden. Ein Beispiel findet Ihr hier in tl_news.php.
  
  
• Folgende Hooks wurden entfernt
  
  checkCredentials - ihr solltet stattdessen das CheckPassportEvent verwenden,
  postLogin - ihr solltet stattdessen das LoginSuccessEvent verwenden,
  importUser - eine alternative Lösung ist hier die Implenetierung eines eigenen UserProvider service,
  postAuthenticate - ihr solltet stattdessen das LoginSuccessEvent verwenden,
  postLogout - ihr solltet stattdessen das LogoutEvent verwenden
  
  
• DCA-Callbacks mit Ausführungspriorität 0
  DCA-Callbacks, die über das service tagging mit der priority=0 registriert wurden, werden jetzt nach den bereits definierten Callbacks ausgeführt, anstatt wie bisher davor.
  
  
• Das Flag |uncached  für Insert-Tags wurde entfernt
  ihr solltet stattdessen das Insert-Tag {{fragment::*}} verwenden
• unbekannte Insert-Tags werden nun nicht mehr in Leerstrings umgewandelt
  stattdessen bleiben sie erhalten und werden ins Markup übernommen, sie werden also am Frontend sichtbar.
  
  
• der Parameter $cache wird nicht mehr an die Hooks replaceInsertTags() und insertTagFlags() übergeben.
  Stattdessen wird ein leeres Array übergeben.
  
  
• Image-Studio Figure Class
  in der Klasse Contao\CoreBundle\Image\Studio\Figure wurde der Rückgabewert der statischen Methode getLinkAttribute() geändert. Sie gibt nun an Stelle eines Arrays ein Objekt vom Typ Contao\CoreBundle\String\HtmlAttributes zurück. Benötigt man weiterhin ein Array, so kann man hier die Funktion iterator_to_array() verwenden, um das Objekt in ein Array zu konvertieren.
  
  Die Twig-Funktion contao_figure wurde als veraltet gekennzeichnet und durch die Funktion figure ersetzt. Die neue Funktion gibt jetzt ein figure-Objekt an Stelle eines Strings zurück. Um bisherige Anwendungen kompatibel zu machen, solltet ihr das Twig-Template component/_figure.html.twig zusammen mit dem neuen figure-Objekt wie folgt verwenden:
  

  {# before #}
  {{ contao_figure('image.jpg', [800, 600]) }}
  
  {# after #}
  {% include "@Contao/component/_figure.html.twig" with 
     { figure: figure('image.jpg', [800, 600]) } 
  %}

• Der Hook sqlCompileCommands wurde entfernt
  verwendet stattdessen das Event Doctrine DBAL postGenerateSchema.
  
  
• Die Konstante CURRENT_ID wurde entfernt
  Die Konstante und Session-Variable CURRENT_ID wird nicht mehr unterstützt. Verwendet stattdessen DataContainer::$currentPid, um auf die ID des aktuellen parent Datensatzes zuzugreifen.
  

  $intCurrentParentRecordId = $dc->currentPid;

• die Klasse RequestToken wurde entfernt
  und mit ihr die Einstellungen disableReferenceCheck und requestTokenWhitelist (siehe auch dazu weiter unten unter 'Konstanten wurden entfernt').
  
  
• folgende Änderungen wurden an der Formularübertragung vorgenommen
  Es ist zukünftig nicht mehr möglich über FORM_FIELDS festzustellen, welche Felder übermittelt wurden. Um einen Wert zukünftig korrekt übermitteln zu können, muss er mit einem Leerstring initialisiert werden.
  

  <!-- Wrong: the input will only be submitted if checked -->
  <input type="checkbox" name="foo" value="bar">
  
  <!-- Right: the input will always be submitted -->
  <input type="hidden" name="foo" value=""><input type="checkbox" name="foo" value="bar">
  
  

• folgende Konstanten wurden entfernt:
  TL_ROOT, BE_USER_LOGGED_IN, FE_USER_LOGGED_IN, TL_START, TL_REFERER_ID, TL_SCRIPT, TL_MODE und REQUEST_TOKEN
  
  Die Funktionen dieser Konstanten können zukünftig wie folgt bereitgestellt werden.
  
  Die Konstante TL_ROOT kann durch Verwendung von kernel.project.dir ersetzt werden. Das war bisher auch schon möglich.
  

  $rootDir = System::getContainer()->getParameter('kernel.project_dir');

  Die Konstante BE_USER_LOGGED_IN wurde früher verwendet, um unveröffentlichten Content am Frontend auszugeben. Bitte verwendet zukünftig den token checker service, um auf den PreviewMode oder den BackenUser zu prüfen.
  

  $hasBackendUser = System::getContainer()->get('contao.security.token_checker')->hasBackendUser();
  
  oder
  
  $showUnpublished = System::getContainer()->get('contao.security.token_checker')->isPreviewMode();

  Desgleichen gilt für FE_USER_LOGGED_IN. Verwendet hierfür den token checker service.
  

  $hasFrontendUser = System::getContainer()->get('contao.security.token_checker')->hasFrontendUser();

  Anstelle von TL_START sollte zukünftig kernel.start.time verwendet werden.
  

  $startTime = System::getContainer()->get('kernel')->getStartTime();

  TL_REFERER_ID wird durch das Request-Attribut _contao_referer_id ersetzt:
  

  $refererId = System::getContainer()->get('request_stack')->getCurrentRequest()->get('_contao_referer_id');

  Vormals war es möglich, die aktuelle Route über TL_SCRIPT zu ermitteln, denn ContaoFramework.php setzte \define('TL_SCRIPT', $this->getRoute()). Das ist nun nicht mehr möglich. Bitte verwendet zukünftig folgende Methode:
  

  $route = System::getContainer()->get('request_stack')->getCurrentRequest()->get('_route'); 
  
  if ('contao_backend' === $route) 
  {
    // Do something 
  }

  Die Funktion von TL_MODE sollte durch den ScopeMatcher service ersetzt werden.
  

  use Contao\CoreBundle\Routing\ScopeMatcher;
  use Symfony\Component\HttpFoundation\RequestStack;
  
  class Test {
    private $requestStack;
    private $scopeMatcher;
  
    public function __construct(RequestStack $requestStack, ScopeMatcher $scopeMatcher) {
      $this->requestStack = $requestStack;
      $this->scopeMatcher = $scopeMatcher;
    }
  
    public function isBackend() {
      return $this->scopeMatcher->isBackendRequest($this->requestStack->getCurrentRequest());
    }
  
    public function isFrontend() {
      return $this->scopeMatcher->isFrontendRequest($this->requestStack->getCurrentRequest());
    }
  }

  Ihr könnt auch an Stellen, wo keine DependencyInjection möglich - oder kein Constructor vorhanden ist, wie z.B. in der config.php, folgenden Inline-Code verwenden.
  

  // das Konstrukt 
  if (TL_MODE === 'BE')
  
  // kann durch folgene Zeile ersetzt werden
  if (System::getContainer()->get('contao.routing.scope_matcher')->isBackendRequest(System::getContainer()->get('request_stack')->getCurrentRequest() ?? Request::create('')))
  
  // bitte vergesst folgende Zeilen nicht!
  use Contao\System;
  use Symfony\Component\HttpFoundation\Request;
  

  Die Konstante REQUEST_TOKEN kann wie folgt ersetzt werden:
  

  $requestToken = System::getContainer()->get('contao.csrf.token_manager')->getDefaultTokenValue();

  <input type="hidden" name="REQUEST_TOKEN" value="<?= $this->requestToken ?>">

• Cron-Jobs können nicht mehr über $GLOBALS['TL_CRON'] registriert werden.
  Zukünftig sollten nur noch Services mit dem Service-Tag contao.cronjob verwendet werden. Hier könnt ihr gleich die neuen PHP-8-Attribute ausprobieren. Das Attribut für den Cron-Job lautet #[AsCronJob].
  
  
• Die Einstellung Layout>Modulverwaltung>Experten-Einstellungen>Nur Gästen Zeigen (show to guests only) wurde entfernt...
  
  
  ...und durch die Palette Zugriffschutz ersetzt. Diese findet ihr in Contao 5 hier:
  
  
  
  
• Das Feld tl_content.ptable wird nicht mehr automatisch mit tl_article assoziiert.
  Es muss jetzt explizit mit dem gewünschten Wert initialisiert werden.
  
  
• Die config option $GLOBALS['TL_CONFIG']['disableInsertTags'] wurde entfernt.
  Bitte verwendet in Zukunft den Parameter contao.insert_tags.allowed_tags!

  $container->getParameter('contao.insert_tags.allowed_tags')

  Beispiel

  # config/config.yaml
  contao:
      localconfig:
          allowed_tags:
              - tag1
              - tag2

• Der onrestore_callback() wurde entfernt.
  Er wurde durch den onrestore_version_callback() ersetzt.
  
  
• Der Hook getSearchablePages() wurde entfernt.
  Verwendt nun stattdessen das SitemapEvent contao.sitemap.
  
  
• Die Methode Backend::addFileMetaInformationToRequest() sowie der gleichnamige Hook wurden entfernt.
  Verwendet zukünftig bitte den image handling service und das FileMetadataEvent.
  
  
• Der Wert des Widgets FormTextarea->value wird zukünftig nicht mehr mit der Funktion specialchars() codiert.
  ihr müsst zukünftig selbst dafür Sorge tragen, dass der Wert in euren templates form_textarea korrekt codiert wird.
• folgende sprachspezifische Komponenten wurden entfernt:
  
  1. die Datei config/languages.php
  2. die Methode System::getLanguages()
  3. der Hook getLanguages()
  
  Verwendet stattdessen zukünftig den Dienst contao.intl.locales. Um Länder zur Liste der Sprachen hinzuzufügen oder von ihr zu entfernen, sollten zukünftig die Konfigurationsvariablen contao.intl.locales oder contao.intl.enabled_locales verwendet werden. Die globale Variable $GLOBALS['TL_LANG']['LNG'] kann jetzt nur noch verwendet werden, um Übersetzungen zu überschreiben, nicht mehr jedoch, um auf die Namen der Sprachen zuzugreifen.
  
  
• folgende länderspezifische Komponenten wurden entfernt:
  
  1. die Datei countries.php
  2. die Methode System::getCountries()
  3. der Hook getCountries()
  
  Verwendet hier stattdessen den Service contao.intl.countries, oder die Konfiguration contao.intl.countries um Ländernamen hinzuzufügen oder zu entfernen. Die globale Variable $GLOBALS['TL_LANG']['CNT'] kann jetzt nur noch verwendet werden, um Übersetzungen zu überschreiben, nicht mehr jedoch, um auf die Ländernamen zuzugreifen.
  
  
• nachfolgende Klassen und Interfaces wurden entfernt
  
  - listable
  - editable
  - executable
  - uploadable
  - UnresolvableDependenciesException
  - UnusedArgumentsException
  
  
• das protected property $arrClassNames wurde aus Contao\Model entfernt.
  
  
• die gesamte Bibliothek Contao\Request wurde entfernt.
  Verwendet stattdessen eine andere, wie beispielsweise symfony/http-client.
  
  
• folgende Resourcen wurden umbenannt
  
  - ContentMedia in ContentPlayer
  - FormCheckBox in FormCheckbox
  - FormRadioButton in FormRadio
  - FormSelectMenu in FormSelect
  - FormTextField in FormText
  - FormTextArea in FormTextarea
  - FormFileUpload in FormUpload
  - ModulePassword in ModuleLostPassword
  - form_textfield in form_text
  
  
• der inputType => 'textStore' wurde entfernt
  verwende stattdessen den inputType => 'passwort'
  
  
• folgende globale Funktionen wurden entfernt
  
  ampersand() • array_delete() • array_dupliacte() • array_insert() • array_is_assoc() • array_move_down() • array_move_up() • basename_natcasecmp() • basename_natcasercmp() • deserialize() • length_sort_asc() • length_sort_desc() • natcaseksort() • nl2br_callback() • nl2br_html5() • nl2br_pre() • nl2br_xhtml() • scan() • specialchars() • standardize() • strip_insert_tags() • trimsplit() • utf8_chr_callback() • utf8_chr() • utf8_convert_encoding() • utf8_decode_entities() • utf8_detect_encoding() • utf8_hexchr_callback() • utf8_ord() • utf8_romanize() • utf8_str_split() • utf8_strlen() • utf8_strpos() • utf8_strrchr() • utf8_strrpos() • utf8_strstr() • utf8_strtolower() • utf8_strtoupper() • utf8_substr() • utf8_ucfirst()
  
  Ersatz für viele dieser Funktionen findet ihr in den Klassen StringUtil, ArrayUtil oder unter den PHP-Funktionen mb_*.
  
  
• im PageTree- und Picker-Widget
  Bei diesen Widgets wurde im DCA-eval-Array der Schlüssel orderField entfernt. Er wird nun nicht mehr ausgewertet. Verwendet stattdessen isSortable, das die Sortierung in derselben Tabelle ablegt.
• vom Zugriff auf die Session via $_SESSION wird dringend abgeraten
  Die weitere Verwendung von $_SESSION behindert die Entwicklung zukünftiger Speicherlösungen. In Contao 4 wurde ohnehin die Symfony-Session transparent auf die Contao $_SESSION abgebildet. Daher solltet ihr zukünftig auf die Session via $request->getSession() zugreifen.
  
  
• Dateien vom Typ database.sql werden nicht länger unterstützt
  wenn ihr das DB-Schema ändern möchtet, nutzt bitte zukünftig das DCA, Doctrin DBAL schema listener oder die Migrations.
  
  
• der SimpleTokenParser ist jetzt strenger
  Tokens, die nicht der Namenskonvention für gültige PHP-Variablen (wie z.B. '##0foobar##') werden nicht mehr unterstützt.
  
  
• $GLOBALS['TL_KEYWORDS']
  die Unterstützung von Schlüsselwörtern in Artikeln wurde entfernt. Ebenso o.g. Schlüssel im $GLOBALS-Array.
  
  
• das Contao-4-Routing wurde entfernt
  Daher sind die Hooks getPageFromUrl und getRootPageFromUrl nicht mehr vorhanden. Verwendet bitte zukünftig das im Symfony-Framework vorhandene Routing.
• benutzerdefinierte Entry-Points
  Die Datei inizialize.php wurde entfernt. Damit sind benutzerdefinierte Eintrittspunkte auf dieser Basis nicht mehr möglich. Verwendet stattdessen einen eigenen Controller als Eintrittspunkt.
• der Contao\ClassLoader wurde entfernt
  Der ist auch nicht mehr nötig, da diese Funktionalität vom composer autoloading bereitgestellt wird.
  
  
• die Klasse Contao\Encryption wurde entfernt,
  ...und mit ihr der DCA-eval-Schlüssel 'encrypt'. Verwendet zukünftig für die Verschlüsselung die save_* und load_callbacks und eine Bibliothek eurer Wahl, wie z.B. phpseclib/phpseclib.
  
  
• die Funktion log_message() wurde entfernt
  wer den Symfony Logger Service bisher noch nicht genutzt hat, sollte jetzt umsteigen!
  
  
• DCA config.dataContainer
  war in Contao 4 vom Typ String oder FQCN (ein Klassenname mit Namespace). Ab Contao 5 muss es zwingend ein FQCN sein! Die bloße Angabe von 'Table' oder 'Folder' etc. ist nicht mehr möglich.
  
  
• die Widgets pageSelector und fileSelector wurden entfernt
  verwendet zukünftig stattdessen das Widget 'picker'. Hier gibts dazu schon ein wenig Doku.
  
  
• der öffentliche Ordner (public folder)
  der öffentliche Ordner heisst nun standardmäßig im Dateisystem auch 'public' und kann in der composer.json umdefiniert werden.