Le task runner Castor est maintenant disponible en version 1 !

This blog post is also available in 🇬🇧 English: The Castor Task Runner is Now Stable!.

Lorsque nous avons dévoilé Castor au grand jour, nous vous parlions des raisons qui nous avaient poussé à développer notre propre task runner.

Depuis cet article de 2023, beaucoup de choses ont évolué dans le projet. Et nous considérons maintenant que Castor et son API publique sont suffisamment stables et méritent enfin une version v1.0.0.

Voyons voir à quoi ressemble Castor désormais… mais avant cela, un petit rappel du projet.

Section intitulée vous-avez-dit-castorVous avez dit Castor ?

Castor est le task runner PHP que nous développons depuis plusieurs années. Son objectif ? Remplacer nos Makefile (ou scripts fabric, invoke, shell) en nous permettant de créer nos tasks via de simples fonctions PHP, faciles à lire, à comprendre et à écrire.

Pas de classes, de POO, de configuration YAML ou de surcouche trop complexe à implémenter.

La fonctionnalité principale de Castor, c’est la DX qu’il propose. Un fichier castor.php, un attribut AsTask, c’est tout ce qu’il vous faut pour vous lancer :

// castor.php

use Castor\Attribute\AsTask;
use function Castor\run;

#[AsTask()]
function start(''): void
{
    run('composer install');
    run('bin/console assets:install');
    run('yarn install');
    // …
}

Vous pouvez dès lors exécuter votre task :

castor start

Malgré cette simplicité apparente, Castor a bien plus à offrir : une notion de contexte pour adapter vos tâches selon l’environnement, des imports et des namespaces pour structurer votre projet Castor comme vous le souhaitez, des événements pour vous brancher dans les entrailles de Castor, et bien plus encore.

De nombreux utilitaires sont évidemment disponibles nativement pour servir de brique de base dans vos tasks : gestion des variables d’environnement, entrées/sorties, logs, appels HTTP, SSH, etc. Consultez la liste exhaustive des utilitaires disponibles.

Il vous manque un outil ? Ajoutez-le naturellement comme vous le feriez dans votre projet PHP habituel. Et si vous pensez que ça pourrait bénéficier à tout le monde, venez en discuter avec nous, ou ouvrez une issue, ou encore mieux une PR !

Section intitulée les-points-clesLes points clés

Section intitulée l-api-publiqueL’API publique

L’ensemble des fonctions fournies nativement, et leur signature, forment la partie publique de l’API de Castor. Elles sont garanties de ne pas changer au sein de versions mineures de Castor.

Si nous devons modifier ou supprimer une fonction, une dépréciation sera toujours ajoutée avant sa suppression définitive dans une version majeure, à l’image de ce que fait Symfony pour respecter Semver et éviter les BC break.

Cette API publique inclut également toutes les classes et comportements qui sont mentionnées dans la documentation. On y retrouve donc, par exemple, les classes du Context, ou encore d’événements. De manière générale, toutes les classes qui ne sont pas marquées avec l’annotation @internal font partie de cette API publique.

Grâce à cette promesse, nous avons pu améliorer progressivement le fonctionnement interne de Castor, tout au long des version 0.x :

• ajout de nouvelles fonctionnalités ;
• améliorer du code ;
• simplification de la maintenance.

Le tout, sans casser les projets utilisant déjà Castor depuis les premières versions v0.x.

Section intitulée l-experience-utilisateurL’expérience utilisateur

On l’a déjà dit : la DX est au cœur du projet. Nous faisons tout pour que Castor soit :

• facile à installer ;
• simple à prendre en main ;
• compréhensible en un coup d’oeil ;
• et facile à débugger (grâce aux logs notamment).

Quand vous utilisez Castor, il va automatiquement générer un fichier .castor.stub.php qui va contenir toutes les définitions des fonctions et classes de l’API publique. Cela permettra à votre IDE de mieux comprendre votre projet Castor, et de vous proposer de l’autocomplétion et des suggestions, comme-ci Castor était installé dans les dépendances de votre projet.

Castor propose aussi l’autocomplétion dans votre shell préféré, avec la complétion des tasks disponibles, de leurs arguments et options.

L’outil doit être au service des développeurs, et tout est fait pour que l’expérience soit plus fluide, naturelle et agréable qu’avec les alternatives.

Section intitulée la-documentation-et-les-exemplesLa documentation et les exemples

Avoir plein de features, c’est bien. Mais si elles ne sont documentées nulle part, elles ne seront jamais utilisées. Un gros travail a donc été fait afin de documenter toutes les fonctionnalités offertes par Castor :

• tout ce qu’il faut savoir pour prendre rapidement en main Castor ;
• toutes les fonctions et helpers natifs ;
• les usages avancés qui sont supportés.

La doc est divisée en 2 grandes parties :

• « Getting started » pour comprendre rapidement les bases de Castor ;
• « Going further » pour les besoins plus avancés.

Et parce que rien ne vaut le code, vous trouverez de nombreux exemples directement dans le dépôt jolicode/castor pour montrer les différentes fonctionnalités en action.

Psst, spoiler : ces exemples nous servent également de suite de tests complète pour être sûrs de ne rien casser quand des modifications sont faites dans Castor.

Section intitulée de-nombreuses-fonctionnalitesDe nombreuses fonctionnalités

Castor s’est considérablement enrichi au fil des versions. Voyons dans les grandes lignes ce que permet maintenant notre rongeur favori.

Section intitulée helpers-natifsHelpers natifs

Nous avons ajouté plusieurs fonctions qui sont couramment utilisées dans les tâches que nous exécutons au quotidien.

Parce que l’idée n’était pas de réinventer la roue, nous tirons pleinement partie de PHP et son écosystème très complet. Plusieurs fonctions exposées par Castor sont ainsi totalement basées sur des composants de Symfony. Par exemple :

• cache() qui exploite symfony/cache et la PSR-6 ;
• io() qui offre les capacités d’interactivité de symfony/console ;
• http_request() qui permet de faire des requêtes HTTP grâce à symfony/http-client;
• run() pour éxécuter des commandes à l’aide de symfony/process;
• fs() pour manipuler le filesystem avec symfony/filesystem et finder() pour chercher des fichiers/dossiers grâce à symfony/finder;
• yaml_parse() et yaml_dump() qui permettent de manipuler des fichiers YAML avec symfony/yaml.

En plus de cela, Castor inclut :

• un système de log basé sur Monolog ;
• des notifications desktop avec JoliNotif ;
• éxécution de processus en parallèles grâce aux Fibers de PHP 8.1 ;
• commandes SSH ou SCP via la librairie spatie/ssh.

Pour finir cette liste loin d’être exhaustive, notons qu’il est également possible de surveiller le système de fichiers afin de relancer des commandes à chaque changement sur le disque ou encore de chiffrer/déchiffrer des fichiers.

Encore une fois, nous ne pouvons que vous encourager à jeter un œil à la liste exhaustive des fonctions pour découvrir tout ce qu’il est possible de faire nativement avec Castor.

Section intitulée methodes-d-installationMéthodes d’installation

Castor offre désormais plusieurs modes d’installation. Le moyen le plus simple :

curl "https://castor.jolicode.com/install" | bash

Si vous avez PHP >= 8.2 d’installé, vous pourrez profiter du phar comme sur la plupart des projets PHP qui offre un exécutable (composer, rector, phpstan, etc).

Vous n’avez pas PHP ou votre PHP est trop vieux ? Aucun problème, le script d’installation vous permet d’installer Castor sous la forme d’un binaire autonome qui inclut la bonne version de PHP :

curl "https://castor.jolicode.com/install" | bash -s -- --static

Et parce qu’on utilise également Github Action dans la plupart de nos projets, nous avons créé une Action castor-php/setup-castor qui permet d’installer directement Castor dans votre workflow :

jobs:
  my-job:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout
        uses: actions/checkout@v4

      - name: Setup castor
        uses: castor-php/setup-castor@v0.1.0

      - name: Run castor "hello" task
        run: castor hello

Comme pour le reste, tout est expliqué dans la documentation d’installation.

Section intitulée castor-en-tant-que-framework-cliCastor en tant que Framework CLI

Castor vous permet de coder facilement vos tasks du quotidien. Imaginez que vous ayez un ensemble de tasks castor que vous souhaiteriez partager avec d’autres utilisateurs ou au sein d’autres projets ?

Castor vous permet désormais de « repacker » votre projet, c’est à dire de construire un phar contenant Castor ainsi que toutes vos tasks, comme s’il agissait de votre propre exécutable.

Il est même possible de masquer le logo de Castor par défaut, voire même depuis peu, de configurer votre propre logo.

Et de la même manière que Castor est disponible à l’installation sous la forme d’un phar, mais aussi d’un binaire, il est possible de construire un binaire contenant votre propre projet repacké.

Section intitulée les-imports-distantsLes imports distants

Dans les cas où vous auriez besoin d’une fonctionnalité qui n’est pas incluse nativement dans Castor, il est désormais possible d’importer des tasks, des fonctions ou même des classes depuis des packages externes.

Encore une fois, l’idée n’était pas de re-développer tout un système de gestion et de téléchargement de plugin. A la place, nous avons choisi de réutiliser le meilleur package manager que nous connaissons : Composer. Castor embarque donc directement Composer et permet de configurer les différents packages à importer (depuis packagist.org ou depuis votre propre repository interne) de la même manière que vous le feriez dans le composer.json de votre projet.

<?php

import('composer://vendor/package/', file: 'functions.php');

Cette fonctionnalité nous a demandé plusieurs itérations avant d’arriver à une implémentation fiable et satisfaisante. Pour autant, nous préférons considérer cette fonctionnalité comme expérimentale pendant encore quelque temps, afin de peaufiner les derniers détails.

Section intitulée adoptionAdoption

Nous avons conçu Castor pour simplifier notre quotidien : piloter nos stacks Docker/Ansible, automatiser des tâches, etc. Tous nos développeurs sont ravis de ne plus avoir d’environnement python à installer, d’être capable de contribuer facilement des tâches, et de ne plus avoir de problème de dépendance, etc. Nous utilisons également Castor pour développer Castor. La CI du projet tourne dans Github Action avec Castor, le système de release est une task Castor qui s’occupe de créer le tag et la release avec le CLI gh puis d’attacher les différents artefact (PHARs, binaires) à la release, la documentation est générée par mkdocs via des tasks Castor. Bref, nous sommes les premiers utilisateurs de Castor 🦫

Quand nous avons open-sourcé Castor, nous avons eu de nombreux retours très positifs de gens qui étaient eux-aussi ravis de pouvoir écrire leur tasks en PHP de manière simple. Nous avons de plus en plus de contributions de gens extérieurs au projet, ce qui confirme l’engouement et l’intérêt autour de Castor.

Merci pour vos ⭐ qui nous motivent encore plus !

Section intitulée un-dernier-motUn dernier mot

Castor v1 est disponible et nous espérons qu’il conviendra à tous vos besoins.

Faites nous savoir si vous seriez intéressés pour savoir comment fonctionne Castor en interne, comment nous avons automatisé le build des différentes versions linux/macos/windows, comment nous avons construit la suite de tests, etc.