Refactoring de code PHP dans VSCode

Actuellement, fin février 2024, il n'existe pas beaucoup d'extensions de refactoring gratuites pour PHP sous VSCode. Nous allons regarder PHP Refactor Tool et PHP Refactoring.

Nous allons apprendre à renommer un symbole, une classe et, encore mieux, à extraire une portion d'une longue méthode vers une nouvelle.

Ces extensions refactorisent ce que vous leur désignez. Pour des refactorings suggérés — et appliqués — automatiquement sur tout un code source, voir Rector 1.0.0, my friend, my coach.

Créer les fichiers d'exemple​

Pour la démo, lancez un shell Linux et exécutez mkdir -p /tmp/refactor && cd $_ pour créer un dossier refactor dans votre dossier temporaire Linux et vous y rendre.

Créez deux fichiers php. Le premier s'appellera index.php et contiendra ce code :

<?php

namespace Cavo;?

require_once('Product.php');?

$product = new Product();?

$product->setProductName('keyboard');
$product->setProductPrice(125);

printf(
    'The name is %s cost %d €'.PHP_EOL,?
    $product->getProductName(),
    $product->getProductPrice()
);

Le second fichier, Product.php, contiendra :

<?php

namespace Cavo;?

class Product
{
    private string $productName = '';?
    private float $productPrice = 0;

    public function __construct(string $name='', float $price=0)?
    {
        $this->setProductName($name);
        $this->setProductPrice($price);
    }

    public function getProductName(): string {
        return $this->productName;
    }

    public function setProductName(string $name): void {?
        $this->productName = $name;
    }

    public function getProductPrice(): float {?
        return $this->productPrice;
    }

    public function setProductPrice(float $price): void {
        $this->productPrice = $price;
    }
}

Lancer l'exemple​

Exécutez docker run -it --rm -v "${PWD}":/project -w /project php:8.2 php index.php pour lancer notre exemple dans la console.

Vous obtiendrez, comme prévu :

$ docker run -it --rm -v "$PWD":/project -w /project php:8.2 php index.php
The name is keyboard cost 125 €▋

Refactoring​

Assurez-vous que PHP Refactor Tool est installé. Allez dans la liste des extensions de VSCode (appuyez sur CTRL-SHIFT-X) et recherchez PHP Refactor Tool. Installez celle de Son Tung PHAM (l'auteur).

Renommer un symbole​

L'illustration ci-dessous montre un script index.php d'exemple utilisant une classe définie dans Product.php.

Tout fonctionne bien mais, oui, les fonctions s'appellent getProductName et getProductPrice et c'est assez redondant : notre objet est $product donc, oui, $product->getProductName() et $product->getProductPrice() peuvent être réécrits en $product->getName() et $product->getPrice(). Plus court, c'est mieux.

Nous devons donc renommer nos fonctions.

En ouvrant notre fichier Product.php, nous pourrions le faire à la main mais... ne faites pas ça : vous devriez mettre à jour manuellement chaque fichier utilisant votre classe Product et si vous oubliez ne serait-ce qu'une utilisation, votre code sera cassé.

La fonctionnalité de renommage sert exactement à ça. Il vous suffit de sélectionner une propriété comme productName comme illustré dans l'animation, d'appuyer sur F2 et de la renommer.

Faisons-le et voyons comment ça fonctionne :

1. Ouvrez le fichier Product.php, placez le curseur sur le mot productName à la ligne 7 private string $productName = '';,
2. Appuyez sur F2 (ou choisissez Rename Symbol dans la palette de commandes (appuyez sur CTRL-SHIFT-P)) et tapez le nouveau nom, par exemple name (au lieu de productName),
3. VSCode affichera une petite liste en haut de l'écran, validez simplement, c'est-à-dire sélectionnez Update Getter name and Setter name.
4. Faites de même pour productPrice et renommez-le en price.

Le nouveau fichier Product.php est maintenant :

<?php

namespace Cavo;?

class Product
{
    private string $name = '';?
    private float $price = 0;

    public function __construct(string $name='', float $price=0)?
    {
        $this->setName($name);
        $this->setPrice($price);
    }

    public function getName(): string {
        return $this->name;
    }

    public function setName(string $name): void {
        $this->name = $name;
    }

    public function getPrice(): float {
        return $this->price;
    }

    public function setPrice(float $price): void {
        $this->price = $price;
    }
}

Mais le plus sympa, c'est que index.php a été mis à jour automatiquement. Ouvrez index.php et vérifiez :

<?php

namespace Cavo;?

require_once('Product.php');?

$product = new Product();

$product->setName('keyboard');
$product->setPrice(125);

printf(
    'The name is %s cost %d €'.PHP_EOL,?
    $product->getName(),?
    $product->getPrice()
);

En exécutant docker run -it --rm -v "${PWD}":/project -w /project php:8.2 php index.php, ça fonctionne toujours.

La même chose en images :

Renommer une classe​

Pour l'exemple, réouvrez le fichier Product.php et, à la ligne 5, placez le curseur sur le mot Product. Appuyez sur F2 et renommez en Products (au pluriel).

Comme on pouvait s'y attendre, le nom de la classe a été mis à jour, mais le nom du fichier aussi. Et, une fois encore, si vous ouvrez le fichier index.php, vous verrez que $product = new Product(); est devenu parfaitement $product = new Products();.

Extraire vers une nouvelle méthode​

La troisième méthode très pratique est Extract method de PHP Refactoring.

Prenons l'exemple suivant (le code ne tourne pas, c'est juste pour l'illustration). Créez un nouveau fichier appelé Pandoc.php avec ce contenu :

<?php

namespace Avonture;

class Pandoc
{
    public function download(string $filename): void
    {
        $filename = Sanitize::sanitizeFileName(trim($filename));?

        if ('' == $filename) {?
            throw new PandocFileNotSpecified();
        }

        if (!is_file($this->outputFolder . $filename)) {?
            throw new PandocFileNotFound($filename);
        }

        // Make the filename absolute
        $filename = $this->outputFolder . ltrim($filename, self::DS);?

        $this->outputType = pathinfo($filename)['extension'];?

        $contentType = $this->getContentType()['type'];?

        header('Content-Type: ' . $contentType);?
        header('Content-Transfer-Encoding: ' . $this->getContentType()['encoding']);

        header('Content-Disposition: attachment; filename="' . basename($filename) . '"');?
        header('Content-Length: ' . filesize(utf8_decode($filename)));?
        header('Accept-Ranges: bytes');
        header('Pragma: no-cache');
        header('Expires: 0');

        ob_end_flush();?

        @readfile(utf8_decode($filename));?
    }
}

La fonction download ne respecte pas le principe de responsabilité unique. Nous y faisons quelques initialisations et assertions. Peut-on faire mieux ? Oui : nous pouvons extraire les lignes concernant le navigateur et créer une nouvelle fonction sendToBrowser mais, au lieu de le faire à la main, nous allons utiliser la fonctionnalité Extract.

Voyez l'animation ci-dessous :

Autres extensions​

• 💀 😒 PHP Refactor existe également mais la dernière mise à jour par l'auteur date de 2019, il y a cinq ans, et la fonctionnalité d'extraction ne fonctionne pas bien ; passez votre chemin.
• 💲😒 PHP Tools for Visual Studio Code de DEVSENSE est une extension freemium (les fonctionnalités de refactoring ne sont que dans la version payante). Le renommage de symbole est payant alors qu'il est gratuit avec PHP Refactor Tool. N'installez pas PHP Tools for Visual Studio Code car il écrasera la fonction F2 de PHP Refactor Tool et la cassera. (voir mon issue Devsense - All-In-One conflicts)

Renommer et extraire des méthodes n'est qu'une partie du travail pour garder un code PHP sain ; pour l'analyse statique et le formatage automatisés, voir l'image Docker regroupant des outils d'analyse statique et formater du code PHP mal formaté.