Download the PHP package thumanics/laravel-boost without Composer

Introduction

resurex-boost

Laravel Boost accelerates AI-assisted development by providing the essential context and structure that AI needs to generate high-quality, Laravel-specific code.

Official Documentation

Documentation for Laravel Boost can be found on the Laravel website.

Contributing

Thank you for considering contributing to Boost! The contribution guide can be found in the Laravel documentation.

Code of Conduct

In order to ensure that the Laravel community is welcoming to all, please review and abide by the Code of Conduct.

Security Vulnerabilities

Please review our security policy on how to report security vulnerabilities.

Guide d'implementation de nouvelles fonctionnalites - Laravel Boost

Ce guide documente pas a pas les patterns a suivre pour ajouter de nouvelles fonctionnalites au package Laravel Boost, en s'appuyant sur les conventions existantes du code source.

Table des matieres

1. Ajouter un outil MCP
2. Ajouter un agent IA
3. Ajouter des guidelines pour un package
4. Ajouter un prompt MCP
5. Ajouter une ressource MCP
6. Ajouter un skill
7. Ajouter une commande Artisan
8. Ajouter un middleware ou service
   • Compiler et distribuer le package
   • Renommer le package

Fonctionnalites existantes par defaut

Outils MCP (src/Mcp/Tools/)

15 outils enregistres dans Boost::discoverTools() :

Prompts MCP (src/Mcp/Prompts/)

Enregistres dans Boost::discoverPrompts() :

Ressources MCP (src/Mcp/Resources/)

Enregistrees dans Boost::discoverResources() :

Agents IA (src/Install/Agents/)

7 agents enregistres dans BoostManager::$agents. Tous implementent SupportsGuidelines, SupportsMcp et SupportsSkills.

Commandes Artisan (src/Console/)

5 commandes enregistrees dans BoostServiceProvider::registerCommands() :

Skills (.ai/)

10 skills uniques repartis sur plusieurs versions de packages :

Guidelines packages (.ai/)

20+ packages avec guidelines Blade dans .ai/{package}/core.blade.php :

Middleware & Services

Configuration (config/boost.php)

Le filtrage MCP (exclude/include par outil, prompt, ressource) est gere dynamiquement par Boost::filterPrimitives() et n'apparait pas dans la config par defaut.

Guide d'implementation

1. Ajouter un outil MCP

Les outils MCP permettent aux agents IA d'interagir avec l'application Laravel (requetes BDD, routes, config, etc.).

Etape 1 : Creer la classe

Creer un fichier dans src/Mcp/Tools/MonOutil.php :

Elements cles :

• Etendre Laravel\Mcp\Server\Tool
• $description (obligatoire) : decrit l'outil pour l'agent IA
• schema() : definit les parametres d'entree avec leur type et description
• handle() : recoit un Request, retourne un Response
• #[IsReadOnly] : annotation pour les outils en lecture seule

Injection de dependances : Le constructeur supporte l'injection via le container Laravel :

Etape 2 : Enregistrer l'outil

Ajouter la classe dans la methode discoverTools() de src/Mcp/Boost.php :

Etape 3 : Ecrire les tests

Creer tests/Feature/Mcp/Tools/MonOutilTest.php :

Expectations personnalisees disponibles :

• isToolResult() : verifie que c'est une Response
• toolHasNoError() / toolHasError() : verifie le statut
• toolTextContains('texte') : verifie le contenu texte
• toolTextDoesNotContain('texte') : verifie l'absence
• toolJsonContent(fn ($data) => ...) : assertion sur le JSON parse
• toolJsonContentToMatchArray([...]) : correspondance partielle

Etape 4 : Verifier

Configuration optionnelle

L'outil peut etre exclu ou inclus via config/boost.php (publiable dans l'app hote) :

Execution en sous-processus

Les outils sont executes dans des sous-processus PHP isoles via ToolExecutor. Cela signifie :

• Chaque execution demarre un processus PHP frais
• Aucun etat partage entre les executions
• Timeout configurable (defaut : 180s, max : 600s)
• Les modifications de code sont prises en compte entre les appels

2. Ajouter un agent IA

Un agent represente un assistant IA (IDE ou CLI) que Boost peut configurer.

Etape 1 : Creer la classe

Creer src/Install/Agents/MonAgent.php :

Methodes abstraites obligatoires :

• name() : identifiant unique en snake_case
• displayName() : nom lisible
• systemDetectionConfig(Platform) : comment detecter l'agent sur le systeme
• projectDetectionConfig() : comment detecter l'agent dans le projet

Contrats optionnels :

Note : frontmatter(), transformGuidelines(), useAbsolutePathForMcp(), getPhpPath(), getArtisanPath() et installMcp() ont des implementations par defaut dans la classe Agent. Il suffit de les surcharger si necessaire.

Methodes surchargeables :

• frontmatter(): bool - Retourner true si le fichier de guidelines necessite du frontmatter YAML (ex: Cursor)
• transformGuidelines(string $markdown): string - Transformer le markdown genere (ex: Gemini echappe les @)
• useAbsolutePathForMcp(): bool - Utiliser des chemins absolus pour le MCP (ex: Junie)
• mcpConfigKey(): string - Cle de configuration MCP (defaut : mcpServers)
• defaultMcpConfig(): array - Configuration MCP par defaut
• shellMcpCommand(): ?string - Commande shell pour l'installation MCP (strategie SHELL)

Etape 2 : Enregistrer l'agent

Ajouter dans le tableau $agents de src/BoostManager.php :

Etape 3 : Ecrire les tests

Etape 4 : Verifier

3. Ajouter des guidelines pour un package

Les guidelines fournissent du contexte specifique a un package aux agents IA.

Etape 1 : Creer la structure de repertoires

Le nom du repertoire est le nom du package composer normalise (vendor/package -> package).

Etape 2 : Ecrire le template Blade

.ai/mon-package/core.blade.php :

Variables disponibles dans les templates :

• $assist (GuidelineAssist) : acces aux packages installes, versions, chemins, configuration

Methodes utiles de $assist :

• $assist->hasPackage(Packages::NAME) : verifie si un package est installe
• $assist->hasSkillsEnabled() : verifie si les skills sont actives
• $assist->skills() : collection des skills disponibles
• $assist->inertia()->pagesDirectory() : repertoire des pages Inertia

Directives speciales :

@boostsnippet protege les blocs de code de l'interpretation Blade. Les backticks et balises <?php sont aussi automatiquement proteges.

Etape 3 : Decouverte automatique

Les guidelines sont decouvertes automatiquement par GuidelineComposer :

• Les guidelines dans .ai/ du package Boost sont integrees directement
• Les packages tiers peuvent fournir leurs propres guidelines dans .ai/ de leur repertoire
• Les guidelines conditionnelles sont filtrees selon les packages detectes par Roster

Etape 4 : Verifier

4. Ajouter un prompt MCP

Les prompts MCP sont des instructions pre-construites que les agents IA peuvent invoquer.

Etape 1 : Creer la structure

Etape 2 : Creer la classe

src/Mcp/Prompts/MonPrompt/MonPrompt.php :

Etape 3 : Creer le template Blade

src/Mcp/Prompts/MonPrompt/mon-prompt.blade.php :

Etape 4 : Enregistrer le prompt

Ajouter dans discoverPrompts() de src/Mcp/Boost.php :

Etape 5 : Ecrire les tests

tests/Feature/Mcp/Prompts/MonPromptTest.php :

Etape 6 : Verifier

5. Ajouter une ressource MCP

Les ressources MCP exposent des donnees persistantes que les agents IA peuvent consulter.

Etape 1 : Creer la classe

src/Mcp/Resources/MonResource.php :

Proprietes obligatoires :

• $description : description de la ressource
• $uri : URI canonique (format file://instructions/nom.md)
• $mimeType : type MIME (text/markdown, text/plain, application/json)

Etape 2 : Enregistrer la ressource

Ajouter dans discoverResources() de src/Mcp/Boost.php :

Etape 3 : Ecrire les tests et verifier

Meme pattern que les outils et prompts. Utiliser les expectations isToolResult(), etc.

6. Ajouter un skill

Les skills sont des capacites specialisees que les agents peuvent activer selon le contexte.

Etape 1 : Creer le fichier skill

.ai/mon-package/2/skill/mon-skill/SKILL.blade.php :

Frontmatter obligatoire :

• name : identifiant en kebab-case
• description : description de quand activer le skill et ce qu'il fait

Placement :

• Skills lies a un package : .ai/{package}/{version}/skill/{skill-name}/SKILL.blade.php
• Skills generiques : .ai/skills/{skill-name}/SKILL.blade.php

Etape 2 : Decouverte automatique

Les skills sont automatiquement decouverts par SkillComposer qui scanne les repertoires .ai/ :

• Decouverte dans le repertoire .ai/ de Boost
• Decouverte dans les packages tiers avec des guidelines Boost
• Decouverte dans les skills personnalises de l'utilisateur

Le SkillWriter ecrit les skills dans le repertoire defini par $agent->skillsPath() pour chaque agent configure.

Etape 3 : Verifier

7. Ajouter une commande Artisan

Etape 1 : Creer la classe

src/Console/MaCommand.php :

Regles architecturales (appliquees par tests/ArchTest.php) :

• La classe DOIT etendre Illuminate\Console\Command
• Le nom de classe DOIT avoir le suffixe Command
• Namespace : Laravel\Boost\Console

Avec options et injection de dependances :

Etape 2 : Enregistrer la commande

Ajouter dans registerCommands() de src/BoostServiceProvider.php :

Etape 3 : Ecrire les tests

Etape 4 : Verifier

8. Ajouter un middleware ou service

Middleware

Etape 1 : Creer src/Middleware/MonMiddleware.php :

Etape 2 : Enregistrer dans BoostServiceProvider::boot() :

Service

Etape 1 : Creer src/Services/MonService.php :

Etape 2 : Enregistrer dans BoostServiceProvider::register() :

Le service est ensuite injectable dans les constructeurs des outils MCP, commandes, etc.

Rappels importants

Conventions de code obligatoires

• declare(strict_types=1) dans tous les fichiers PHP (test d'architecture)
• Pas de dd(), dump(), var_dump(), die(), ray() (test d'architecture)
• Pas d'appels directs a env() sauf dans BoostServiceProvider (test d'architecture)
• Style Laravel Pint avec comparaisons strictes (===)
• PHPStan niveau 5

Commandes de verification

Structure de test standard

Pattern de filtrage MCP

Tous les primitives MCP (outils, prompts, ressources) supportent le filtrage via la configuration boost.mcp.{type}.exclude et boost.mcp.{type}.include. Ce filtrage est applique automatiquement par Boost::filterPrimitives().

Compiler et distribuer le package

Laravel Boost est un package Composer PHP standard. Il n'y a pas d'etape de "build" ou de compilation : le code source PHP est distribue tel quel.

Prerequis

Installation des dependances de developpement

Cycle de validation avant distribution

Publier sur Packagist (depot public)

Etape 1 : Creer un depot Git et pousser le code :

Etape 2 : Creer un tag de version :

Etape 3 : Enregistrer le package sur packagist.org :

• Se connecter avec son compte GitHub.
• Se rendre sur la page de soumission : https://packagist.org/packages/submit.
• Saisir l'URL du dépôt (ex: https://github.com/thumanics/laravel-boost.git).
• Cliquer sur le bouton "Check" pour valider la structure.
• Si tout est correct, cliquer sur "Submit". Packagist détectera automatiquement les informations du composer.json.

Etape 4 : Le package est installable par les utilisateurs :

Publier sur un depot Composer prive (Satis, Private Packagist, etc.)

Option A - Satis :

Ajouter le depot dans le satis.json :

Option B - Depot VCS direct :

Les utilisateurs ajoutent dans leur composer.json :

Option C - Depot local (path) pour le developpement :

Structure minimale requise pour la distribution

Les fichiers essentiels a inclure dans le package :

Les fichiers a exclure de la distribution (via .gitattributes) :

Auto-decouverte Laravel

Le package est auto-decouvert grace a la section extra.laravel dans composer.json :

Aucune action manuelle n'est necessaire pour l'utilisateur apres composer require.

Renommer le package

Pour forker ou renommer laravel/boost en un autre nom (ex: acme/ai-tools), voici la liste exhaustive de tous les points d'ancrage a modifier.

Etape 1 : Identite Composer (composer.json)

Etape 2 : Namespace PHP (tous les fichiers dans src/ et tests/)

Renommer le namespace racine dans tous les fichiers PHP :

Commande pour renommer en masse :

Etape 3 : Noms de classes racine

Renommer egalement les fichiers PHP pour correspondre aux nouveaux noms de classes.

Etape 4 : Configuration (config/boost.php)

Renommer le fichier et la cle de configuration :

Puis mettre a jour le ServiceProvider :

Etape 5 : References config('boost.*') dans le code source

Rechercher et remplacer toutes les references de configuration. Fichiers concernes :

Etape 6 : Variables d'environnement

Etape 7 : Commandes Artisan (src/Console/)

Etape 8 : Nom du serveur MCP

Etape 9 : Route et nom de route

Etape 10 : Directive Blade

Les utilisateurs devront remplacer @boostJs par @aiToolsJs dans leurs vues.

Etape 11 : Cle de cache

Etape 12 : Canal de log

Etape 13 : Tests d'architecture (tests/ArchTest.php)

Etape 14 : Documentation

Mettre a jour les references dans :

• README.md : logos, badges, texte
• CHANGELOG.md : URLs GitHub
• UPGRADE.md : noms de commandes
• CLAUDE.md : noms de classes et chemins
• CONTRIBUTING_GUIDE.md : ce fichier

Checklist de verification apres renommage

License

Laravel Boost is open-sourced software licensed under the MIT license.