Haal alles uit PHP met Rector

Waarom Rector

Upgraden van een project om geschikt te maken voor een nieuwe PHP versie kan tijdrovend zijn. Daarnaast kunnen nieuwe PHP versies functionaliteiten bevatten waardoor je bepaalde stukken leesbaarder of efficiënter kan weergeven. Denk bijvoorbeeld aan de match statement die met PHP 8 is geïntroduceerd. Dit is een mooie vervanging voor de switch statement. In plaats van handmatig alle switch statements aan te passen in je project kan je dat Rector laten doen.

van switch naar match

Zo zijn er tal van zaken die Rector voor je kan aanpassen waardoor het eenvoudiger is om de nieuwste features van je PHP versie te benutten. Hierdoor is je project goed up to date te houden en verbetert het de algehele ontwikkelervaring. Daarnaast kan Rector ook zaken als return types toevoegen waardoor het eenvoudiger is om static code analyzers zoals PHPstan of Larastan te implementeren. Kortom, Rector biedt je allerlei hulpmiddelen om de kwaliteit van je algehele project mooi op peil te houden.

Zo werkt het

Voordat we laten zien hoe je Rector toepast in jouw project is het goed om te weten hoe Rector precies werkt. Het proces wat Rector uitvoert verloopt in een aantal fases:

1. Bestanden zoeken

Middels een config bestand rector.php kan je definiëren in welke paden Rector op zoek moet gaan naar PHP bestanden. Vervolgens worden de geconfigureerde Rectors toegepast op ieder php bestand.
rector paden

Een Rector is een PHP klasse die een specifiek ding aanpast, zoals bijvoorbeeld het vervangen van switch statements voor match statements zoals eerder beschreven.

2. Parsen en reconstrueren

Het toepassen van Rectors gaat altijd op een specifieke manier. Eerst worden alle bestanden geparsed waarbij gebruik wordt gemaakt van een AST (Abstract Syntax Tree).

3. Metadata toevoegen

Vervolgens worden alle onderdelen, ook wel nodes, overlopen om metadata toe te voegen zoals de klassenaam, de methode waarin een node zich bevindt en de namespace. Het resultaat is een rijke mapping van data die geschikt is om Rectors op toe te passen.

4. Toepassen Rectors

Iedere geconfigureerde Rector wordt een voor een toegepast. Daarbij wordt iedere node gecontroleerd of het van toepassing is op de betreffende Rector, zo ja dan wordt de Rector uitgevoerd. De wijzigingen worden meegenomen in de volgende iteratie totdat alle Rectors zijn uitgevoerd.

Nadat alle Rectors zijn uitgevoerd worden de wijzigingen, indien van toepassing, toegepast op het betreffende bestand. Nadat alle bestanden zijn overlopen wordt er een overzicht getoond van de gewijzigde bestanden.

Zo gebruik je het

Rector heeft slechts een enkele vereiste, namelijk dat je project tenminste PHP 7.2 gebruikt.

  1. Voeg Rector toe aan je project composer require rector/rector --dev
  2. Voer Rector vervolgens uit vendor/bin/rector als er geen rector.php bestand aanwezig wordt je gevraagd of Rector die voor je moet aanmaken, kies "Yes"
  3. Wanneer je rector.php opent zie je dat het je Laravel project al herkent, en alle belangrijke paden zijn geconfigureerd.
    rector config
  4. Heb je rector in een nieuw laravel project geïnstalleerd? Voer dan gerust vendor/bin/rector uit. Gebruik je je het in een bestaand project? Dan is het verstandig om wat aanpassingen door te voeren in het config bestand.

Rector in een bestaand project toepassen

Wanneer je Rector toepast in een bestaand project is het aan te raden om de rector.php config aan te passen. Standaard worden er best een aantal Rectors toegepast, dit zal voor aanzienlijk wat wijzigingen zorgen. Om Rector geleidelijker te introduceren kan je het volgende doen:

1. Begin met een enkel pad

Je hoeft Rector niet gelijk toe te passen op je hele project, je kan ook beginnen met een enkel pad. Dit zal het aantal wijzigingen aanzienlijk beperken en je hebt de volledige vrijheid om een enkel sub pad in te stellen.

2. Pas enkele Rectors toe in plaats van sets

Standaard worden er sets toegepast die meerdere Rectors bevatten, maar het is ook mogelijk om enkele Rectors toe te passen. Gebruik hiervoor de withRules methode
rector paden

Benieuwd naar de wijzigingen die zouden plaatsvinden maar wil je het nog niet toepassen? Gebruik dan de dry-run optie met vendor/bin/rector --dry-run.

3. Pas levels toe bij sets

In plaats van enkele rules toe te passen wat het beheer van de rector config bewerkelijker maakt, kan je ook levels toepassen op sets. Het level van een set bepaalt hoe uitgebreid de set wordt toegepast. Hoe hoger het level hoe meer Rectors worden toegepast. Bij een bestaand project kan je er dus ook voor kiezen om een enkele set uit te voeren op het laagste level 0 met ->withTypeCoverageLevel(0)

4. Test zorgvuldig

Hoewel Rector een hoop werk uit handen kan nemen, kan het ook nieuwe bugs introduceren. Test daarom zorgvuldig alle zaken die het aanpast om ongewenst gedrag te voorkomen. Het is dan ook erg prettig als je unit of pest tests goed zijn opgezet.

Dagelijks gebruik

Rector kan je dus het beste geleidelijk introduceren, verhoog steeds het level en werk naar het hoogste level toe van iedere set. Het verhogen van levels kan je doen naar wens. Daarnaast is het aan te raden om Rector in je CI/CD pijplijn toe te voegen, dan hoef je er niet over na te denken. Rector maakt dit erg gemakkelijk dankzij de setup-ci optie. Op hun website lees je daar meer over https://getrector.com/blog/new-setup-ci-command-to-let-rector-work-for-you

Tot slot

Rector lost helaas geen bugs op in je systeem maar het helpt wel om de algehele kwaliteit van je code op peil te houden. Net als met Laravel Pint waar we het in ons vorige artikel over hadden, kost het je niets om Rector te passen. Dit in combinatie met de voordelen is wat ons betreft dus een echte must have voor jouw laravel project. Zo biedt Rector ook specifieke Laravel Rectors https://getrector.com/find-rule?activeRectorSetGroup=laravel&rectorSet= die je kan gebruiken.

Naar alle kennis