> ## 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 riscritto da zero

> Introduzione a laravel/cpx. Uno strumento in stile npx per eseguire pacchetti Composer senza installarli. La v2.0 lo riscrive come PHAR autosufficiente e aggiunge l'esecuzione preferenziale dei binari locali, l'esecuzione di Gist, gli alias e altro.

<Info>
  Questo articolo si basa su README.md e UPGRADE.md di [laravel/cpx](https://github.com/laravel/cpx), aggiornati alla v2.0.0 rilasciata il 24 luglio 2026.
</Info>

## Cos'è cpx

[cpx](https://github.com/laravel/cpx) è uno strumento che permette di eseguire i comandi contenuti in un pacchetto Composer senza doverlo installare. Puoi pensarlo come la versione Composer di `npx`.

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

Internamente installa il pacchetto in una directory isolata prima di eseguirlo, quindi non entra in conflitto con le dipendenze Composer del progetto o globali. Dalla seconda esecuzione in poi riutilizza lo stesso pacchetto installato, quindi è veloce.

## Perché serve

L'installazione di singoli tool con `composer global require` presenta alcuni problemi.

* Le dipendenze globali si scontrano tra loro (facile con dipendenze comuni come `nikic/php-parser` o `symfony/console`).
* Vuoi cambiare versione dello stesso tool per progetto.
* Nel lungo termine ti dimentichi di aggiornare i pacchetti globali.
* Non vuoi installare globalmente un tool usato una sola volta.

cpx stesso è distribuito come PHAR autosufficiente e non ha dipendenze runtime Composer, quindi anche installato globalmente non causa conflitti.

## Riscrittura totale in v2.0

Con la v2.0 cpx è stato completamente riscritto e ora è distribuito come **PHAR autosufficiente**. L'uso di base (`cpx <package-name> <command> [arguments]`) e la directory di cache `~/.cpx` restano invariati. La 1.x è in freeze: non sono previste nuove release, comprese quelle di bug e sicurezza.

Aggiornare è semplice: reinstalli globalmente.

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

La v2.0 richiede PHP 8.3 o superiore.

## Nuove funzionalità della v2.0

### Esecuzione preferenziale dei binari locali

Come `npx`, se nel progetto esiste già un binario installato, cpx lo esegue prima di installare la copia isolata. Risale dalla directory corrente verso l'alto fino al progetto Composer più vicino ed esegue il binario corrispondente in `vendor/bin` (la `bin-dir` di default).

```bash theme={null}
cpx pint                 # esegue vendor/bin/pint se presente
cpx phpunit --filter=Foo # esegue vendor/bin/phpunit se presente
cpx laravel/pint:^2.0    # usa la copia locale solo se la versione installata soddisfa il vincolo
```

Per forzare la copia isolata usa `--skip-local`.

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

### Esecuzione diretta di una directory pacchetto locale

Puoi puntare direttamente a una directory di un pacchetto Composer in sviluppo ed eseguirne il binario.

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

La directory di destinazione deve avere un `composer.json` valido e le dipendenze devono essere già installate in `vendor/autoload.php`. In questo caso cpx non esegue Composer né copia/mette in cache il pacchetto.

### cpx exec e cpx tinker

Sono disponibili diversi modi rapidi per eseguire codice PHP.

| Comando               | Descrizione                                  |
| --------------------- | -------------------------------------------- |
| `cpx exec <file.php>` | Esegue un file PHP (solo con questo comando) |
| `cpx exec -r <code>`  | Esegue codice PHP direttamente               |
| `cpx exec <gist url>` | Scarica ed esegue un GitHub Gist             |
| `cpx tinker`          | Apre un REPL interattivo                     |

All'interno di un progetto Laravel, `cpx exec` fa il boot completo dell'applicazione (config, facade, `.env`; `$app` è disponibile) e `cpx tinker` esegue il `php artisan tinker` del progetto stesso (se è installato `laravel/tinker`). Altrove viene avviata la shell PsySH.

Negli script puoi richiedere al volo un pacchetto in autoload con `cpx_require('vendor/package')` (rinominato rispetto a `composer_require()` della 1.x).

### Alias

Per non dover ricordare nomi lunghi di pacchetti, puoi definire scorciatoie personalizzate.

```bash theme={null}
cpx alias laravel/pint pint
cpx aliases      # elenca gli alias definiti
cpx unalias pint # elimina un alias
```

L'elenco di alias built-in per pacchetti popolari incluso nella 1.x è stato rimosso, quindi se ti serve devi definirli tu.

### Modalità non interattiva e output JSON

cpx rileva automaticamente ambienti non interattivi tramite [laravel/agent-detector](https://github.com/laravel/agent-detector), redirezione dello standard input e i flag `--no-interaction`/`-n`. In modalità non interattiva, i comandi di gestione di cpx come `installed`, `aliases`, `alias`, `unalias`, `clean` e `update` restituiscono una singola riga JSON invece del testo formattato. Anche da terminale interattivo puoi ottenere lo stesso output passando `--json`.

## Principali cambi rispetto alla 1.x (comandi)

| 1.x                                           | 2.x                                                                     |
| --------------------------------------------- | ----------------------------------------------------------------------- |
| `cpx list` (elenco installati)                | Sostituito da `cpx installed` (`list` mostra l'elenco dei comandi)      |
| Elenco di alias built-in                      | Rimosso. Definiscili con `cpx alias`                                    |
| `cpx check` / `cpx format` / `cpx test`       | Rimossi. Esegui direttamente `cpx pint`, `cpx phpstan`, `cpx pest` ecc. |
| `cpx version` / `-v`                          | Rimossi. Usa `cpx --version`                                            |
| `cpx script.php` (esecuzione diretta di file) | Rimosso. Serve `cpx exec script.php`                                    |
| `composer_require()`                          | Rinominato in `cpx_require()`                                           |

## Pagine correlate

Le cache e i pacchetti vecchi in `~/.cpx` vengono migrati automaticamente al nuovo formato, ma i pacchetti eseguiti con vincoli di versione sono gestiti con nuove directory, quindi vengono reinstallati solo alla prima esecuzione. Le copie non più necessarie della 1.x si eliminano con `cpx clean`.

<Card title="Repository laravel/cpx" icon="github" href="https://github.com/laravel/cpx">
  Codice sorgente e README aggiornato.
</Card>

<Card title="Guida all'upgrade di cpx 2.0" icon="arrow-up" href="https://github.com/laravel/cpx/blob/main/UPGRADE.md">
  Procedura dettagliata di migrazione da 1.x a 2.x.
</Card>


## Related topics

- [Laravel Pint](/it/pint.md)
- [Laravel Package Skeleton — template starter per pacchetti ufficiali](/it/blog/package-skeleton-introduction.md)
- [Struttura interna del package auto-discovery](/it/advanced/package-discovery.md)
- [Laravel Cloud — il PaaS dedicato a Laravel](/it/blog/laravel-cloud.md)
- [Laravel Cloud Hibernation (sospensione automatica)](/it/blog/laravel-cloud-hibernation.md)