Comment appliquer vos propres correctifs aux packages Composer –

L’utilisation de packages tiers peut accélérer le développement de votre projet. Parfois, vous devrez peut-être ajouter des fonctionnalités supplémentaires ou corriger un bogue critique. Voici comment appliquer des correctifs aux packages PHP installés par Composer.

Quand appliquer un correctif à un package

Vérifiez d’abord s’il est approprié de créer un correctif dans le projet. Un patch doit toujours être un changement mineur. Si vous avez besoin d’ajouter de nouvelles fonctionnalités étendues, vous devez ouvrir un problème avec le package ou le fourcher vous-même. Cela aidera à éviter les conflits à mesure que le package évolue.

Vous devez vous demander si le changement dont vous avez besoin est vraiment spécifique à votre projet. Les correctifs de dépendance n’affectent généralement que quelques lignes de code. Ils corrigent des bogues et des problèmes qui vous empêcheraient autrement d’utiliser le package. La plupart des correctifs sont de nature à court terme. Ils devraient être remplacés ultérieurement par des correctifs à la source dans la base de code du package.

En fin de compte, vous devez mesurer vos intentions. Êtes-vous en train de résoudre un problème immédiat avec un package ou d’étendre les fonctionnalités du package pour l’aligner sur votre base de code? Si c’est le dernier, vous devriez envisager de contribuer au package ou de l’envelopper avec des classes et des fonctions supplémentaires qui sont des citoyens de première classe dans votre projet.

Création d’un patch Composer

Une fois que vous avez effectué l’appel à patch, vous pouvez commencer à préparer votre projet. Composer n’a pas de support de patch intégré, nous allons donc utiliser le populaire simplify/vendor-patches projet pour l’ajouter. Cela fournit une interface intuitive sur cweagans/composer-patches pour vous aider à créer de nouveaux correctifs.

composer require --dev symplify/vendor-patches

Assurez-vous que le package que vous devez corriger est installé dans votre projet:

composer require example/broken-package

Ensuite, ouvrez le fichier problématique dans votre éditeur de code. Vous le trouverez dans le vendor annuaire. Dans notre exemple, nous devons modifier vendor/example/broken-package/src/Broken.php:

<?php
 
class Broken {
    public function __construct(string|int $foo) {
        if (is_string($foo)) {
            echo "Valid value!";
        }
    }
}
 
?>

La Broken La classe doit accepter à la fois les chaînes et les entiers, en utilisant les types d’union de PHP 8. Malheureusement, regarder la source montre qu’elle n’accepte en fait que les chaînes.

Dans notre exemple fictif, le responsable du package a reconnu le problème mais n’a pas encore créé de nouvelle version. Corrigeons notre chemin autour du problème en attendant.

Copiez le fichier cassé, inchangé, et ajoutez un .old suffixe:

cp vendor/example/broken-project/src/Broken.php vendor/example/broken-project/src/Broken.php.old

Assurez-vous de ne pas modifier le .old fichier!

Ensuite, modifiez le original afin qu’il fonctionne correctement dans votre base de code. Lorsque vous effectuez des modifications sur place, les modifications prennent effet immédiatement. Vérifiez que votre base de code se comporte désormais comme prévu.

<?php
 
class Broken {
    public function __construct(string|int $foo) {
        if (is_string($foo)) {
            echo "Valid value!";
        }
        else if (is_int($foo)) {
            echo "Also valid!";
        }
    }
}
 
?>

Création du fichier de patch

Vous pouvez maintenant utiliser le symplify/vendor-patches projet pour créer un fichier de correctif pour votre correctif. Le package fournit un vendor-patches binaire qui scanne automatiquement votre vendor répertoire pour trouver les modifications que vous avez apportées.

vendor/bin/vendor-patches generate

L’exécution de la commande générera un diff pour vous. Il sera enregistré dans le patches répertoire à la racine de votre projet. Le diff est calculé en comparant les .php et .php.old les fichiers que vous avez créés.

Vous pouvez réexécuter la commande pour découvrir les nouveaux correctifs que vous ajoutez. Chaque fichier modifié reçoit son propre patch dans le patches annuaire.

Patch automatique

Au sein de votre composer.json fichier, vous verrez qu’une nouvelle section a été ajoutée:

{
    "extra": {
        "patches": {
            "example/broken-package": [
                "patches/example-broken-package-src-broken-php.patch"
            ]
        }
    }
}

La patches object mappe les noms des packages installés à un tableau de fichiers de correctifs à appliquer. Ces correctifs seront appliqués automatiquement chaque fois que vous composer install.

Un script d’installation est enregistré par simplify/vendor-patches. Il est appelé après l’installation de chaque dépendance. Le script cherche à voir si des correctifs ont été définis pour le package. Il appliquera automatiquement tout ce qu’il trouve.

Vous verrez des lignes dans le composer install sortie indiquant quand les patchs ont été appliqués. Si une erreur est signalée, vous pouvez utiliser composer install --verbose pour obtenir plus d’informations sur les raisons pour lesquelles le correctif a été ignoré. Cela est souvent dû à une mise à jour du package corrigeant le problème que vous avez corrigé, rendant votre fichier de correctif redondant.

Suppression de correctifs

Vous pouvez supprimer temporairement un patch en supprimant sa ligne de composer.json. Cela arrêtera l’application du patch lorsque vous composer install.

Pour supprimer définitivement un patch de votre projet, supprimez son composer.json ligne. Vous pouvez ensuite supprimer son .patch fichier de votre projet patches annuaire.

Si vous souhaitez rétablir un correctif que vous avez appliqué localement, il est plus simple de suivre les étapes ci-dessus pour supprimer ou désactiver le correctif. Vous pouvez ensuite supprimer le package du vendor répertoire et exécutez composer install pour revenir à une table rase.