Rector für PHP und TYPO3, Programmcode

Rector für PHP und TYPO3 beschleunigt Upgrades

Rector ist ein PHP-Paket, welches den PHP-Code automatisiert, aktualisiert und sauber hält. Anhand von Regelwerken durchsucht es den bestehenden Code und bringt ihn gegebenfalls auf den neuesten Stand. Somit ist Rector bei zwei Anwendungsfällen hilfreich:

  1. Du aktualisierst deine PHP-Version oder Anwendung (z.B. TYPO3) und musst somit auch deinen Code anpassen.
  2. Um die Qualität deines PHP-Codes im Programmieralltag zu gewährleisten.

Ein Beispiel gefällig? Kein Problem. Hier kommt ein einfaches Szenario:

     public function run()
     {
         $items = [];
-        array_push($items, $item);
+        $items[] = $item;
     }

In diesem Beispiel würde Rector die Funktion array_push() durch eine zeitgemäße Schreibweise ersetzen.

Ein wenig komplexer darf es schon sein? Auch das ist kein Problem.

 class MyViewHelper implements ViewHelperInterface
 {
-    public function render(array $firstParameter, string $secondParameter = null)
+    public function initializeArguments()
     {
+        $this->registerArgument('firstParameter', 'array', '', true);
+        $this->registerArgument('secondParameter', 'string', '', false, null);
+    }
+
+    public function render()
+    {
+        $firstParameter = $this->arguments['firstParameter'];
+        $secondParameter = $this->arguments['secondParameter'];
     }
 }

Hier werden die Argumente im TYPO3 Fluid Viewhelper nicht mehr wie in älteren TYPO3-Versionen der Methode render() übergeben. Das würde in TYPO3 v10.4 LTS zu einem Fehler führen. Also werden die Argumente zunächst deklariert und innerhalb der Funktion wieder zugewiesen. Alleine diese Regel erspart einem enorm viel Zeit.

Unterstützt werden neben TYPO3 auch Symfony, Drupal, CakePHP und sicherlich bald auch noch viele weitere.

Das bei Upgrades oft genutzte „Suchen und Ersetzen“ wird mittels Rector obsolet. Aber die Software kann weitaus mehr. Das Paket ist leicht zu installieren und anzuwenden. Wie genau du Rector für TYPO3 aufsetzt und nutzt, erfährst du im folgenden Artikel.

1. Installation von Rector für TYPO3

Rector für TYPO3 ist ein PHP-Paket welches einfach via Composer installiert werden kann.

composer require --dev ssch/typo3-rector

Sollte es zu Kompatibilitätsproblemen bei der Installation kommen, dann einfach das folgende Paket anstatt dessen installieren.

composer require --dev ssch/typo3-rector-prefixed

An dieser Stelle ein großes Dankeschön an Sebastian Schreiber und alle Entwickler, die an Rector für TYPO3 mitarbeiten. Als Programmierer kannst das Projekt auf GitHub unterstützen. Hier findest du auch eine Anleitung, falls du kein Composer nutzt.

2. Konfigurieren

Nachdem du Rector installiert hast, muss es zunächst noch konfiguriert werden, was allerdings schnell erledigt ist. Zunächst führen wir im Root-Verzeichnis, also dort, wo auch die globale composer.json liegt, folgendes Statement aus:

// Für ssch/typo3-rector (PHP >= 7.4)
cp ./vendor/ssch/typo3-rector/templates/rector.php.dist rector.php

// Für rector/rector 0.13.4 (PHP < 7.4)
./vendor/bin/rector init --template-type=typo3

Nun finden wir in unserem Root-Verzeichnis eine Datei namens rector.php. Den Inhalt fassen wir noch an ein zwei Stellen an, sodass die Datei wie folgt aussieht:

<?php

declare(strict_types=1);

use Rector\Core\Configuration\Option;
use Rector\Core\ValueObject\PhpVersion;
use Rector\PostRector\Rector\NameImportingPostRector;
use Ssch\TYPO3Rector\Set\Typo3SetList;
use Symfony\Component\DependencyInjection\Loader\Configurator\ContainerConfigurator;

return static function (ContainerConfigurator $containerConfigurator): void {
// get parameters
$parameters = $containerConfigurator->parameters();

// Define what rule sets will be applied
$containerConfigurator->import(Typo3SetList::TYPO3_76);
$containerConfigurator->import(Typo3SetList::TYPO3_87);
$containerConfigurator->import(Typo3SetList::TCA_87);
$containerConfigurator->import(Typo3SetList::TYPO3_95);
$containerConfigurator->import(Typo3SetList::TCA_95);
$containerConfigurator->import(Typo3SetList::TYPO3_104);
$containerConfigurator->import(Typo3SetList::TCA_104);
$containerConfigurator->import(Typo3SetList::DATABASE_TO_DBAL);
$containerConfigurator->import(Typo3SetList::UNDERSCORE_TO_NAMESPACE);

// FQN classes are not imported by default. If you don't do it manually after every Rector run, enable it by:
$parameters->set(Option::AUTO_IMPORT_NAMES, true);

// this will not import root namespace classes, like \DateTime or \Exception
$parameters->set(Option::IMPORT_SHORT_CLASSES, false);

// this will not import classes used in PHP DocBlocks, like in /** @var \Some\Class */
$parameters->set(Option::IMPORT_DOC_BLOCKS, false);

// Define your target version which you want to support
$parameters->set(Option::PHP_VERSION_FEATURES, PhpVersion::PHP_74);

// If you would like to see the changelog url when a rector is applied
// $parameters->set(Typo3Option::OUTPUT_CHANGELOG, true);

// If you set option Typo3Option::AUTO_IMPORT_NAMES to true, you should consider excluding some TYPO3 files.
$parameters->set(Option::SKIP, [
NameImportingPostRector::class => [
'ClassAliasMap.php',
'ext_localconf.php',
'ext_emconf.php',
'ext_tables.php',
__DIR__ . '/**/TCA/*',
__DIR__ . '/**/Configuration/RequestMiddlewares.php',
__DIR__ . '/**/Configuration/Commands.php',
__DIR__ . '/**/Configuration/AjaxRoutes.php',
__DIR__ . '/**/Configuration/Extbase/Persistence/Classes.php',
],
]);

// If you have trouble that rector cannot run because some TYPO3 constants are not defined add an additional constants file
// Have a look at https://github.com/sabbelasichon/typo3-rector/blob/master/typo3.constants.php
// $parameters->set(Option::AUTOLOAD_PATHS, [
// __DIR__ . '/typo3.constants.php'
// ]);

// get services (needed for register a single rule)
// $services = $containerConfigurator->services();

// register a single rule
// $services->set(InjectAnnotationRector::class);
};

In der Zeile 18 habe ich definiert, welche Regelsammlungen angewendet werden sollen.

// Define what rule sets will be applied
$containerConfigurator->import(Typo3SetList::TYPO3_76);
$containerConfigurator->import(Typo3SetList::TYPO3_87);
$containerConfigurator->import(Typo3SetList::TCA_87);
$containerConfigurator->import(Typo3SetList::TYPO3_95);
$containerConfigurator->import(Typo3SetList::TCA_95);
$containerConfigurator->import(Typo3SetList::TYPO3_104);
$containerConfigurator->import(Typo3SetList::TCA_104);
$containerConfigurator->import(Typo3SetList::DATABASE_TO_DBAL);
$containerConfigurator->import(Typo3SetList::UNDERSCORE_TO_NAMESPACE);

Eine Übersicht aller Regeln speziell für TYPO3 findet ihr im GitHub, ebenso wie die Übersicht aller Regelsammlungen.

Neben den Regelsammlungen habe ich in Zeile 39 die Ziel-PHP-Version von PHP_72 auf PHP_74 angehoben.

// Define your target version which you want to support
$parameters->set(Option::PHP_VERSION_FEATURES, PhpVersion::PHP_74);

Es ist nicht zwingend notwendig, dass Rector dann auch mit PHP 7.4 ausgeführt wird, die PHP-Applikation sollte es hingegen schon. Die über 600 allgemeinen Rector PHP Regeln gibt es ebenfalls auf GitHub.

3. Rector ausführen

Einmal konfiguriert, kann Rector auf jeden beliebigen Zielpfad ausgeführt werden. Wie bereits bei der Konfiguration befinden wir uns wieder im Root-Verzeichnis, um das Tool anzuwenden.

./vendor/bin/rector process public/typo3conf/ext/my_extension --dry-run

Mit --dry-run wird wie bei Composer zunächst angezeigt, welche Änderungen durchgeführt werden.

Beispielhafte Anzeige der PHP-Änderungen via TYPO3 Rector in der Shell

Wenn alles soweit ok ist, dann führen wir die Aktion nochmal durch, nur ohne den Parameter.

vendor/bin/typo3-rector process public/typo3conf/ext/my_extension

Alle Änderungen sind somit in den Dateien gespeichert. Wie bereits beschrieben, lässt sich der Pfad beliebig anpassen.
Nun wünschen wir dir viel Spaß beim Anwenden.

Sebastian Schreiber hat mit Never Code Alone das Tool nochmal ausgiebiger vorgestellt.

Info Icon

Dieses Video wird über eine externe Plattform (YouTube) gehostet. Das Laden bedarf der Zustimmung unserer Datenschutzbestimmungen.

Einstellung vornehmen

Rector kann mehr

Wenn du kein TYPO3 nutzt, kannst du trotzdem Rector für deine PHP-Anwendung nutzen. Die Anleitung dazu findest du im GitHub. Zudem wird das Projekt stetig weiterentwickelt, wodruch sich ein Blick auf die aktuelle Dokumentation immer lohnt.

Neben den bereits bestehenden Regeln, lässt sich die Software beliebig erweitern. Wenn du neue Regeln für TYPO3 hast, teile sie gerne.

Erfahre in einem weiteren Blog-Artikel, was beim Update auf die TYPO3 v10.4 LTS zu beachten ist.

Hast du bereits Erfahrungen mit Rector oder sollen wir mal ein anderes Tool / eine Extension vorstellen? Schreibt uns das gerne in den Kommentaren oder auf unseren Social Media Kanälen. Wir freuen uns über euer Feedback.

  • 18/05/2021

    Kommentar von Sebastian Schreiber

    Hi Marc,
    danke für den Artikel.
    In der letzten Zeit ist bei Rector und TYPO3-Rector passiert.
    Magst du in Abstimmung mit mir den Artikel noch mal aktualisieren?
    Ich hatte das letzte Mal den Fall, dass jemand nach eurer Anleitung vorgegangen ist, aber das Ganze leider schon wieder „veraltet“ war.

    Wir können uns gerne über Slack weiter austauschen.

    • 18/05/2021

      Kommentar von Marc

      Hallo Sebastian,

      vielen Dank erstmal für deine Arbeit an dem Projekt. Es erleichtert unsere Prozesse enorm. Danke auch für deinen Kommentar und dein Feedback im Slack. Der Artikel ist nun wieder auf dem aktuellen Stand.

Kommentar hinzufügen

Deine E-Mail-Adresse wird nicht veröffentlicht. Erforderliche Felder sind mit * markiert