CPX: інструмент для швидкого запуску PHP-пакетів через Composer без їхнього встановлення в проєкт

CLI-інструмент cpx дозволяє запускати команди з будь-якого Composer-пакета без його встановлення у ваш проєкт. Фактично, cpx — це для Composer те саме, що npx для npm.

Якщо ви хоч раз стикалися з конфліктами залежностей після composer global require, cpx вирішить цю проблему завдяки повній ізоляції пакетів.

Інструмент встановлює кожен пакет в окрему директорію, незалежну від вашого проєкту чи глобальних налаштувань Composer. При повторному запуску cpx використовує вже встановлену версію, паралельно перевіряючи наявність оновлень.

# Запуск пакетів без встановлення

Просто вкажіть назву пакета, команду та її аргументи. Формат назви такий самий, як у composer.json, включно з підтримкою версій:

cpx friendsofphp/php-cs-fixer php-cs-fixer fix ./src
cpx friendsofphp/php-cs-fixer:^3.0 php-cs-fixer fix ./src

Якщо пакет містить лише один binary або його назва збігається з назвою пакета, команду можна не вказувати:

cpx friendsofphp/php-cs-fixer fix ./src

Якщо ж у пакеті кілька binary-файлів і ви не вказали конкретний, cpx версії 2.0 запропонує обрати потрібний зі списку.

Також cpx може працювати з локальними директоріями, що зручно під час розробки пакетів:

cpx ../my-package --version

У такій директорії має бути валідний composer.json та встановлені залежності у vendor/autoload.php. cpx запустить вказаний binary безпосередньо з цього місця без кешування чи копіювання.

# Пріоритет локальних binary за замовчуванням

Це ключова зміна у версії 2.0. Тепер cpx спочатку шукає binary всередині вашого проєкту. Він знаходить найближчий Composer-проєкт у дереві директорій і запускає відповідний файл із налаштованого bin-dir:

cpx pint                 # запустить vendor/bin/pint, якщо він є у проєкті
cpx phpunit --filter=Foo # запустить vendor/bin/phpunit
cpx laravel/pint:^2.0    # використає локальний pint, лише якщо він відповідає версії ^2.0

Таким чином, команда cpx pint всередині проєкту запустить саме ту версію, яка зафіксована у вашому composer.lock. Якщо локального binary не знайдено, cpx завантажить ізольовану копію. Щоб ігнорувати локальну версію, використовуйте прапорець --skip-local.

# Власні аліаси

У версії 1.x був жорстко прописаний список скорочень для популярних пакетів (наприклад, для phpstan чи laravel). У версії 2.0 цей список видалено, і тепер ви самі керуєте аліасами:

cpx alias phpstan/phpstan phpstan
cpx alias laravel/pint

Якщо не вказати ім'я аліасу, cpx використає коротку назву пакета (як pint у прикладі вище). Аліаси зберігаються у ~/.cpx/. Переглянути їх можна через cpx aliases, а видалити — командою cpx unalias <name>.

Також доступні команди cpx installed (список усіх запущених через cpx пакетів) та cpx clean (видалення пакетів, що давно не використовувалися). Команда cpx list тепер відображає доступні команди самого cpx.

# Запуск PHP-файлів, Gists та REPL

Команди cpx exec та cpx tinker ідеально підходять для швидких скриптів та чернеток:

cpx exec script.php
cpx exec -r 'echo PHP_VERSION;'
cpx exec https://gist.github.com/user/id
cpx tinker

Підтримка Gist дозволяє завантажити та запустити скрипт у поточній директорії. Якщо Gist містить кілька файлів, cpx запитає, який саме виконати. Використання SHA дозволяє зафіксувати конкретну ревізію, а GITHUB_TOKEN — обійти ліміти запитів GitHub API.

Перед виконанням коду cpx автоматично знаходить Composer autoloader. У проєктах на Laravel застосунок завантажується повністю (з конфігами, facades та .env), а в Symfony — ініціалізується kernel. Це можна вимкнути прапорцем --no-boot. Ваш код виконується в окремому PHP-процесі.

У таких скриптах можна динамічно підключати пакети через cpx_require():

cpx_require('nesbot/carbon');
 
echo Carbon\Carbon::now();

Якщо у вашому Laravel-проєкті встановлено laravel/tinker, команда cpx tinker делегує виконання вашому php artisan tinker. В інших випадках вона відкриває оболонку PsySH.

# Адаптація виводу під оточення

cpx автоматично розпізнає неінтерактивні термінали (наприклад, перенаправлення stdin, прапорець -n або роботу в середовищі AI-агентів через laravel/agent-detector).

У такому режимі вимкнено TTY, запити використовують значення за замовчуванням, а команди керування (installed, aliases тощо) повертають JSON:

{
    "success": true,
    "errors": [],
    "summary": {
        "packages": [
            { "name": "laravel/pint", "last_run": "2024-01-02 03:04:05" }
        ]
    }
}

Під час запуску пакетів виводиться лише результат роботи самого інструменту, без службових повідомлень cpx. Ви можете примусово отримати JSON-вивід, додавши прапорець --json.

# Встановлення та оновлення

cpx 2.0 вимагає PHP 8.3 або вище. Встановіть його глобально через Composer і переконайтеся, що шлях до глобальних bin додано до вашого PATH:

composer global require cpx/cpx

# Дізнатися більше

Проєкт cpx створив Liam Hammett. Починаючи з версії 2.0, це офіційний пакет laravel/cpx, над яким працює команда Laravel. Живу демонстрацію інструменту від Тейлора Отвелла можна переглянути у записі виступу на Laracon US 2026.

Повна документація доступна в репозиторії laravel/cpx на GitHub. Якщо ви оновлюєтеся з версії 1.x, зверніть увагу на upgrade guide. Також завітайте на офіційний сайт cpx.dev.