PHPackages                             andydefer/php-signature-parser - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [Utility & Helpers](/categories/utility)
4. /
5. andydefer/php-signature-parser

ActiveLibrary[Utility & Helpers](/categories/utility)

andydefer/php-signature-parser
==============================

A flexible signature parser for CLI commands

v0.10.2(2w ago)0279↓50%1MITPHPPHP ^8.1

Since Jun 18Pushed 2w agoCompare

[ Source](https://github.com/andydefer/php-signature-parser)[ Packagist](https://packagist.org/packages/andydefer/php-signature-parser)[ RSS](/packages/andydefer-php-signature-parser/feed)WikiDiscussions main Synced 2w ago

READMEChangelogDependencies (10)Versions (21)Used By (1)

PHP Signature Parser
====================

[](#php-signature-parser)

**Un parseur strict et typé pour les commandes CLI qui extrait la source, les arguments requis, les arguments par défaut, les nullables, les variadiques, les énumérations et les flags avec des Value Objects et des collections typées. Support automatique du formatage des espaces via le caractère `^`, des commentaires inline, des tokens spéciaux (`?`, `_`) et des tags personnalisés.**

[![PHP Version](https://camo.githubusercontent.com/83dd395020c37276225039739320f6c8e7e99963ab21ee3d09282cb48dad2a60/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f5048502d382e312532422d626c7565)](https://php.net)[![License](https://camo.githubusercontent.com/5caa455d8debc46fb23abbadb45a733a937f3910a73fc875c2f7820468e1bb54/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f4c6963656e73652d4d49542d677265656e)](LICENSE)

---

Table des matières
------------------

[](#table-des-matières)

1. [Installation](#installation)
2. [Concepts fondamentaux](#concepts-fondamentaux)
3. [Commentaires inline](#commentaires-inline)
4. [Formatage des espaces avec `^`](#formatage-des-espaces-avec-)
5. [Tokens spéciaux](#tokens-sp%C3%A9ciaux)
    - [Le token `?` (null explicite)](#le-token--null-explicite)
    - [Le token `_` (skip)](#le-token--skip)
6. [Ordre strict des arguments](#ordre-strict-des-arguments)
7. [Énumérations (Enum)](#%C3%A9num%C3%A9rations-enum)
8. [Tags personnalisés](#tags-personnalis%C3%A9s)
9. [Utilisation du parseur](#utilisation-du-parseur)
10. [Manipulation des collections](#manipulation-des-collections)
    - [ArgumentCollection](#argumentcollection)
    - [FlagCollection](#flagcollection)
    - [EnumCollection](#enumcollection)
    - [VariadicArgumentCollection](#variadicargumentcollection)
11. [Value Objects](#value-objects)
    - [SignatureStructureVO](#signaturestructurevo)
    - [SignatureVO](#signaturevo)
12. [SignatureDocumentor - Génération de documentation](#signaturedocumentor---g%C3%A9n%C3%A9ration-de-documentation)
13. [QueryBuilder - Construction dynamique](#querybuilder---construction-dynamique)
14. [Les parseurs internes](#les-parseurs-internes)
15. [Extensibilité](#extensibilit%C3%A9)
16. [Cas d'usage avancés](#cas-dusage-avanc%C3%A9s)
17. [Exemples complets](#exemples-complets)
18. [Licence](#licence)

---

Installation
------------

[](#installation)

```
composer require andydefer/php-signature-parser
```

### Prérequis

[](#prérequis)

- PHP 8.1 ou supérieur

---

Concepts fondamentaux
---------------------

[](#concepts-fondamentaux)

### La signature

[](#la-signature)

La signature est une chaîne qui décrit la structure de la commande.

```
$signature = 'backup {source} {destination} {format=zip} {env=?} ::level->[low,medium,high]=medium {excludes*} {purpose*} {--force} {--verbose}';
```

ÉlémentSyntaxeDescription**Source**`backup`Nom de la commande (position 0)**Requis**`{source}`Argument obligatoire**Par défaut**`{format=zip}`Argument avec valeur par défaut**Nullable**`{env=?}`Argument pouvant être `null`**Enum**`::level->[low,medium,high]=medium`Énumération avec valeurs autorisées**Variadique**`{excludes*}`Argument qui capture plusieurs valeurs**Flag**`{--force}`Flag optionnel (booléen)**Tag personnalisé**``Données supplémentaires (non définies dans la signature)**Commentaire**`# "comment"`Documentation inline### La requête

[](#la-requête)

La requête est la commande réelle exécutée par l'utilisateur.

```
$query = 'backup /var/www /backup tar.gz staging high [cache, logs, tmp] [home, data, models] --force ';
```

---

Commentaires inline
-------------------

[](#commentaires-inline)

Les commentaires permettent de documenter chaque argument directement dans la signature.

### Syntaxe

[](#syntaxe)

```
{name}#'comment'
{name=value}#'comment'
{name*>[values]}#'comment'
::name->[values]#'comment'
{--flag}#'comment'
```

### Exemples

[](#exemples)

```
$signature = 'backup {source}#"Source directory" {destination}#"Destination" {format=zip}#"Archive format" {--force}#"Force overwrite"';
```

### Utilisation avec les records

[](#utilisation-avec-les-records)

Les commentaires sont automatiquement extraits et disponibles dans les records :

```
$result = $parser->parse($signature, $query);

echo $result->requireds->first()->comment;  // 'Source directory'
echo $result->defaults->first()->comment;   // 'Archive format'
echo $result->flags->first()->comment;      // 'Force overwrite'
```

### Formats supportés

[](#formats-supportés)

```
// Guillemets doubles
{name}#"The user name"

// Guillemets simples
{name}#'The user name'
```

---

Formatage des espaces avec `^`
------------------------------

[](#formatage-des-espaces-avec-)

Le parser remplace automatiquement les caractères `^` par des espaces dans toutes les valeurs extraites.

### Règle simple

[](#règle-simple)

> **Pour inclure un espace dans une valeur, utilisez `^` à la place.**

Saisie utilisateurValeur réelle`John^Doe``John Doe``Hello^World!``Hello World!``C:/Program^Files``C:/Program Files`### Exemples

[](#exemples-1)

```
// Arguments requis
$signature = 'user:create {name} {email}';
$query = 'user:create John^Doe john@example.com';

$result = $parser->parse($signature, $query);
// $result->requireds->first()->value = 'John Doe'

// Valeurs par défaut
$signature = 'user:list {format=zip}';
$query = 'user:list tar^gz';
$result = $parser->parse($signature, $query);
// $result->defaults->first()->value = 'tar gz'
```

---

Tokens spéciaux
---------------

[](#tokens-spéciaux)

### Le token `?` (null explicite)

[](#le-token--null-explicite)

Le token `?` permet de passer explicitement `null` comme valeur.

CasExempleRésultatArgument requis`backup /var/www ?``destination = null`Argument par défaut`deploy staging ?``env = null` (override)### Le token `_` (skip)

[](#le-token-_-skip)

Le token `_` permet de sauter un argument et d'utiliser la valeur par défaut ou `null` :

CasComportement**Argument requis**`_` → `null`**Argument par défaut**`_` → utilise la valeur par défaut**Argument nullable**`_` → `null`**Enum avec défaut**`_` → utilise la valeur par défaut**Enum optionnel**`_` → `null`### Exemples

[](#exemples-2)

```
// Par défaut → valeur par défaut
$signature = 'backup {source} {format=zip}';
$query = 'backup /var/www _';
// format = zip

// Nullable → null
$signature = 'deploy {env=?} {--force}';
$query = 'deploy _ --force';
// env = null

// Enum avec défaut
$signature = 'set-level ::level->[low,high]=medium';
$query = 'set-level _';
// level = medium
```

---

Ordre strict des arguments
--------------------------

[](#ordre-strict-des-arguments)

⚠️ **L'ordre des éléments dans la signature est STRICT et IMPÉRATIF.**

OrdreTypeSyntaxeExemple**1****Source**`command``backup`**2****Requis**`{name}``{source}` `{destination}`**3****Par défaut**`{name=value}``{format=zip}` `{output=dist}`**4****Nullable**`{name=?}``{env=?}` `{port=?}`**5****Enum**`::name->[values]=state``::level->[low,high]=medium`**6****Variadique**`{name*}``{excludes*}` `{purpose*}`**7****Flags**`{--flag}``{--force}` `{--verbose}`**8****Tags personnalisés**````### Exemples d'ordre valide

[](#exemples-dordre-valide)

```
// ✅ Ordre correct avec tous les types
$signature = 'backup {source} {destination} {format=zip} {env=?} ::level->[low,high]=medium {excludes*} {--force}';

// ✅ Commentaires à n'importe quelle position
$signature = 'backup {source}#"Source" {destination} {--force}#"Force"';
```

### Exemples d'ordre invalide

[](#exemples-dordre-invalide)

```
// ❌ Enum après variadic
$signature = 'backup {source} {excludes*} ::level->[low,high]=medium';

// ❌ Required après default
$signature = 'backup {format=zip} {source}';
```

---

Énumérations (Enum)
-------------------

[](#énumérations-enum)

Les énumérations permettent de restreindre les valeurs autorisées pour un argument.

### Syntaxe

[](#syntaxe-1)

```
::name->[value1,value2,value3]=state
```

### États possibles

[](#états-possibles)

ÉtatSyntaxeDescription**Requis**`=*`Doit être fourni**Optionnel**`=?`Peut être `_`**Défaut**`=default`Valeur par défaut### Exemples

[](#exemples-3)

```
// Avec valeur par défaut
$signature = 'set-level ::level->[beginner,middle,master]=middle';
$query = 'set-level master';
// level = 'master'

// Requis
$signature = 'set-level ::level->[beginner,middle,master]=*';
$query = 'set-level beginner';
// level = 'beginner'
// set-level seul échouerait

// Optionnel
$signature = 'set-level ::level->[beginner,middle,master]=?';
$query = 'set-level _';
// level = null

// Avec commentaire
$signature = 'set-level ::level->[beginner,middle,master]=medium#"The skill level"';
```

### Accès aux énumérations

[](#accès-aux-énumérations)

```
$result = $parser->parse($signature, $query);

// Valeur
$level = $result->enums->get('level'); // 'master'

// Valeurs autorisées
$allowed = $result->enums->getAllowedValues('level'); // ['beginner', 'middle', 'master']

// Vérifications
if ($result->enums->isRequired('level')) {
    echo "Level est requis";
}

if ($result->enums->isAllowed('level', 'master')) {
    echo "'master' est autorisé";
}
```

---

Tags personnalisés
------------------

[](#tags-personnalisés)

Les tags personnalisés permettent d'ajouter des données supplémentaires à une commande sans modifier la signature.

### Syntaxe

[](#syntaxe-2)

```

```

### Utilisation

[](#utilisation)

```
$signature = 'send {recipient} {--verbose}';
$query = 'send John --verbose  ';

$result = $parser->parse($signature, $query);

$customData = $result->custom_data->toArray();
echo $customData['greeting']; // 'Hello World'
echo $customData['later'];    // 'goodby'
```

### Avec QueryBuilder

[](#avec-querybuilder)

```
$query = QueryBuilder::init('deploy {environment}')
    ->setRequired('environment', 'staging')
    ->setCustoms([
        'version' => '1.2.3',
        'user' => 'admin'
    ])
    ->build();

// 'deploy staging  '
```

---

Utilisation du parseur
----------------------

[](#utilisation-du-parseur)

### Utilisation de base

[](#utilisation-de-base)

```