> ## Documentation Index
> Fetch the complete documentation index at: https://kawax.biz/llms.txt
> Use this file to discover all available pages before exploring further.

# cpx 2.0 — Composer Package Executor entièrement réécrit

> Présentation de laravel/cpx, un outil permettant d'exécuter des packages Composer sans les installer, à la manière de npx. La version 2.0 est entièrement réécrite sous forme d'un PHAR autonome et introduit l'exécution prioritaire des binaires locaux, l'exécution de Gists, la gestion d'alias, etc.

<Info>
  Cet article s'appuie sur le README.md et le UPGRADE.md du dépôt [laravel/cpx](https://github.com/laravel/cpx). Il reflète l'état de la version 2.0.0 sortie le 24 juillet 2026.
</Info>

## Qu'est-ce que cpx ?

[cpx](https://github.com/laravel/cpx) est un outil qui permet d'exécuter les commandes fournies par un package Composer sans avoir à l'installer. On peut le voir comme l'équivalent Composer de `npx` en npm.

```bash theme={null}
composer global require cpx/cpx
cpx friendsofphp/php-cs-fixer fix ./src
```

En interne, cpx installe le package dans un répertoire isolé avant de l'exécuter, ce qui évite tout conflit avec les dépendances Composer globales ou celles du projet. À partir de la deuxième exécution, cpx réutilise le package déjà installé, ce qui est très rapide.

## À quoi cela sert-il ?

Installer chaque outil individuellement avec `composer global require` pose plusieurs problèmes :

* Les dépendances globales entrent en conflit entre elles (typiquement des dépendances communes comme `nikic/php-parser` ou `symfony/console`).
* On veut parfois passer d'une version à l'autre du même outil selon les projets.
* Sur le long terme, on oublie de mettre à jour les packages globaux.
* On préfère éviter d'installer globalement un outil dont on n'a besoin qu'une seule fois.

cpx lui-même est distribué comme un PHAR autonome, sans dépendances Composer à l'exécution : l'installer globalement ne crée donc aucun conflit.

## Réécriture complète en v2.0

En v2.0, cpx a été entièrement réécrit et est désormais distribué sous forme de **PHAR autonome**. L'usage de base (`cpx <package-name> <command> [arguments]`) et le répertoire de cache `~/.cpx` sont conservés. La branche 1.x est gelée : ni corrections de bugs ni correctifs de sécurité ne sont prévus.

Pour mettre à niveau, il suffit de réinstaller globalement.

```bash theme={null}
composer global require cpx/cpx:^2.0
```

La v2.0 requiert PHP 8.3 ou plus récent.

## Nouveautés de la v2.0

### Priorité aux binaires locaux

Comme npx, si un binaire est déjà installé dans le projet, cpx l'exécute en priorité avant d'envisager d'installer une copie isolée. cpx remonte à partir du répertoire courant pour trouver le projet Composer le plus proche et exécute le binaire correspondant dans `vendor/bin` (le `bin-dir` par défaut).

```bash theme={null}
cpx pint                 # exécute vendor/bin/pint s'il existe
cpx phpunit --filter=Foo # exécute vendor/bin/phpunit s'il existe
cpx laravel/pint:^2.0    # utilise le binaire local uniquement si sa version satisfait la contrainte
```

Pour forcer l'usage de la copie isolée, utilisez `--skip-local`.

```bash theme={null}
cpx --skip-local laravel/pint --version
```

### Exécuter directement un répertoire de package local

Vous pouvez cibler directement le répertoire d'un package Composer en cours de développement pour en exécuter le binaire.

```bash theme={null}
cpx /absolute/path/to/package --version
cpx ../path/to/package --version
```

Le répertoire cible doit contenir un `composer.json` valide et ses dépendances doivent être préalablement installées dans `vendor/autoload.php`. Dans ce cas, cpx n'exécute pas Composer et ne recopie/ne met pas le package en cache.

### cpx exec et cpx tinker

Plusieurs raccourcis sont fournis pour exécuter rapidement du code PHP.

| Commande              | Description                                                  |
| --------------------- | ------------------------------------------------------------ |
| `cpx exec <file.php>` | Exécute un fichier PHP (le seul moyen d'exécuter un fichier) |
| `cpx exec -r <code>`  | Exécute directement du code PHP                              |
| `cpx exec <gist url>` | Télécharge et exécute un Gist GitHub                         |
| `cpx tinker`          | Ouvre un REPL interactif                                     |

Au sein d'un projet Laravel, `cpx exec` amorce complètement l'application, y compris la configuration, les façades et le `.env` (la variable `$app` est utilisable). `cpx tinker` invoque le `php artisan tinker` du projet lui-même (si `laravel/tinker` est installé). En dehors, cpx lance directement le shell PsySH.

Dans vos scripts, `cpx_require('vendor/package')` (renommé depuis `composer_require()` en 1.x) permet d'autoloader un package à la volée.

### Alias

Pour éviter d'avoir à retenir des noms de packages longs, définissez vos propres raccourcis.

```bash theme={null}
cpx alias laravel/pint pint
cpx aliases      # liste les alias définis
cpx unalias pint # supprime un alias
```

La liste des alias intégrés pour les packages populaires (présente en 1.x) a été supprimée : vous devrez éventuellement les redéfinir vous-même.

### Mode non interactif et sortie JSON

cpx détecte automatiquement un environnement non interactif via [laravel/agent-detector](https://github.com/laravel/agent-detector) (détection d'agent IA), une redirection de l'entrée standard ou les flags `--no-interaction` / `-n`. Dans ce mode, les commandes internes de gestion comme `installed`, `aliases`, `alias`, `unalias`, `clean` ou `update` renvoient une seule ligne JSON à la place du texte formaté. Depuis un terminal interactif, l'option `--json` donne le même résultat.

## Principaux changements par rapport à la v1.x (commandes)

| 1.x                                               | 2.x                                                                         |
| ------------------------------------------------- | --------------------------------------------------------------------------- |
| `cpx list` (liste des packages installés)         | Renommée en `cpx installed` (`list` affiche la liste des commandes)         |
| Alias intégrés                                    | Supprimés. Définissez-les vous-même avec `cpx alias`                        |
| `cpx check` / `cpx format` / `cpx test`           | Supprimés. Utilisez directement `cpx pint`, `cpx phpstan`, `cpx pest`, etc. |
| `cpx version` / `-v`                              | Supprimé. Utilisez `cpx --version`                                          |
| `cpx script.php` (exécution directe d'un fichier) | Supprimé. Il faut `cpx exec script.php`                                     |
| `composer_require()`                              | Renommé en `cpx_require()`                                                  |

## Pages associées

Le cache dans `~/.cpx` et les anciennes versions de packages sont migrés automatiquement vers le nouveau format ; cependant, les packages exécutés avec une contrainte de version sont gérés sous un nouveau nom de répertoire, ce qui déclenche une réinstallation lors de la première utilisation. Les copies devenues obsolètes issues de la v1.x peuvent être supprimées avec `cpx clean`.

<Card title="Dépôt laravel/cpx" icon="github" href="https://github.com/laravel/cpx">
  Le code source et le README à jour.
</Card>

<Card title="Guide de mise à niveau cpx 2.0" icon="arrow-up" href="https://github.com/laravel/cpx/blob/main/UPGRADE.md">
  Marche à suivre détaillée pour passer de la 1.x à la 2.x.
</Card>


## Related topics

- [Fonctionnement interne de la découverte automatique des packages](/fr/advanced/package-discovery.md)
- [Installer PHP, Composer et Node.js avec WSL (Windows)](/fr/blog/windows-setup.md)
- [Présentation de Laravel Wayfinder](/fr/blog/wayfinder-introduction.md)
- [Pilote Amazon Bedrock pour Laravel AI SDK](/fr/packages/laravel-amazon-bedrock.md)
- [Laravel Package Skeleton — le template de démarrage pour packages officiels](/fr/blog/package-skeleton-introduction.md)