> ## 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 がフルリライト

> laravel/cpxの紹介。npxのようにComposerパッケージをインストールせずに実行できるツール。v2.0で自己完結型PHARとしてフルリライトされ、ローカルバイナリ優先実行やGist実行、エイリアス機能などが追加されました。

<Info>
  この記事は[laravel/cpx](https://github.com/laravel/cpx)のREADME.mdとUPGRADE.mdに基づく情報です。v2.0.0（2026年7月24日リリース）時点の内容です。
</Info>

## cpxとは

[cpx](https://github.com/laravel/cpx) は、Composerパッケージに含まれるコマンドをインストールせずに実行できるツールです。npmにおける`npx`のComposer版と考えると分かりやすいです。

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

内部的にはパッケージを分離ディレクトリにインストールして実行するため、プロジェクトやグローバルのComposer依存関係と衝突しません。2回目以降の実行は同じインストール済みパッケージを再利用するため高速です。

## なぜ必要か

`composer global require` で個別ツールをインストールする方法には以下の課題があります。

* グローバル依存関係同士が競合する（`nikic/php-parser`や`symfony/console`など共通依存を使うツールで発生しやすい）
* 同じツールの異なるバージョンをプロジェクトごとに切り替えたい
* 長期運用時にグローバルパッケージの更新を忘れる
* 一度しか使わないツールをグローバルインストールしたくない

cpx自体はPHARとして自己完結しており、ランタイムのComposer依存を持たないため、グローバルインストールしても競合の原因になりません。

## v2.0での全面リライト

cpxは v2.0 で全面的に書き直され、**自己完結型のPHAR**として配布されるようになりました。基本的な使い方（`cpx <package-name> <command> [arguments]`）や `~/.cpx` キャッシュディレクトリはそのまま維持されています。1.xは開発が凍結されており、バグ修正・セキュリティ修正を含め今後のリリースはありません。

アップグレードはグローバルインストールし直すだけです。

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

v2.0はPHP 8.3以上が必要です。

## v2.0の新機能

### ローカルバイナリの優先実行

npxと同様に、プロジェクトに既にインストールされているバイナリがあれば、分離コピーをインストールする前にそちらを優先して実行します。カレントディレクトリから上に遡って最も近いComposerプロジェクトを探し、`vendor/bin`（デフォルトの`bin-dir`）内の一致するバイナリを実行します。

```bash theme={null}
cpx pint                 # vendor/bin/pint が存在すればそれを実行
cpx phpunit --filter=Foo # vendor/bin/phpunit が存在すればそれを実行
cpx laravel/pint:^2.0    # インストール済みバージョンが制約を満たす場合のみローカルを使用
```

分離コピーを強制したい場合は `--skip-local` を使います。

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

### ローカルパッケージディレクトリの直接実行

開発中のComposerパッケージのディレクトリを直接指定して、そのバイナリを実行できます。

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

対象ディレクトリには有効な `composer.json` が必要で、依存関係は事前に `vendor/autoload.php` にインストールされている必要があります。cpxはこの場合、Composerの実行やパッケージのコピー・キャッシュを行いません。

### cpx exec と cpx tinker

PHPコードを素早く実行する複数の方法が用意されています。

| コマンド                  | 説明                        |
| --------------------- | ------------------------- |
| `cpx exec <file.php>` | PHPファイルを実行（ファイル実行はこの方法のみ） |
| `cpx exec -r <code>`  | PHPコードを直接実行               |
| `cpx exec <gist url>` | GitHub Gistをダウンロードして実行    |
| `cpx tinker`          | インタラクティブREPLを開く           |

Laravelプロジェクト内では `cpx exec` がconfig・facade・`.env`を含めてフルにアプリケーションをブート（`$app`が使用可能）し、`cpx tinker` はプロジェクト自身の `php artisan tinker` を実行します（`laravel/tinker`がインストールされている場合）。それ以外の場所ではPsySHシェルが起動します。

スクリプト内では `cpx_require('vendor/package')`（1.xの`composer_require()`から改名）でパッケージをその場でオートロードできます。

### エイリアス機能

長いパッケージ名を覚えなくて済むよう、独自のショートカットを定義できます。

```bash theme={null}
cpx alias laravel/pint pint
cpx aliases      # 定義済みエイリアスの一覧
cpx unalias pint # エイリアスの削除
```

1.xに組み込まれていたポピュラーパッケージ向けのビルトインエイリアス一覧は廃止されたため、必要なら自分で定義する必要があります。

### 非対話モードとJSON出力

cpxは[laravel/agent-detector](https://github.com/laravel/agent-detector)によるAIエージェント検出、標準入力のリダイレクト、`--no-interaction`/`-n` フラグから非対話環境を自動検出します。非対話モードでは、`installed`・`aliases`・`alias`・`unalias`・`clean`・`update` などcpx自身の管理コマンドが整形テキストの代わりに1行のJSONを返します。対話端末からでも `--json` を渡せば同じ出力を得られます。

## v1.xからの主な変更点（コマンド）

| 1.x                                     | 2.x                                          |
| --------------------------------------- | -------------------------------------------- |
| `cpx list`（インストール済み一覧）                  | `cpx installed` に変更（`list`はコマンド一覧を表示）        |
| ビルトインのエイリアス一覧                           | 廃止。`cpx alias`で自分で定義                         |
| `cpx check` / `cpx format` / `cpx test` | 廃止。`cpx pint`・`cpx phpstan`・`cpx pest`など直接実行 |
| `cpx version` / `-v`                    | 廃止。`cpx --version`を使用                        |
| `cpx script.php`（ファイル直接実行）              | 廃止。`cpx exec script.php`が必要                  |
| `composer_require()`                    | `cpx_require()`に改名                           |

## 関連ページ

`~/.cpx`ディレクトリのキャッシュや旧バージョンパッケージは自動的に新形式へ移行されますが、バージョン制約付きで実行していたパッケージは新しいディレクトリ名で管理されるため初回のみ再インストールされます。不要になった1.x時代のコピーは `cpx clean` で削除できます。

<Card title="laravel/cpx リポジトリ" icon="github" href="https://github.com/laravel/cpx">
  ソースコードと最新のREADMEはこちら。
</Card>

<Card title="cpx 2.0 アップグレードガイド" icon="arrow-up" href="https://github.com/laravel/cpx/blob/main/UPGRADE.md">
  1.xから2.xへの詳細な移行手順。
</Card>


## Related topics

- [Laravel AI SDK 用の Amazon Bedrock ドライバー](/jp/packages/laravel-amazon-bedrock.md)
- [Inertia.jsでSPAを構築する](/jp/blog/inertia-introduction.md)
- [InteractsWithDataトレイト](/jp/advanced/interacts-with-data.md)
- [tap() ヘルパーと Tappable トレイト](/jp/advanced/tap.md)
- [Vue.js入門 — Inertia × Laravel で使う基礎知識](/jp/blog/vue-introduction.md)