CPX: Інструмент для виконання Composer-пакетів без встановлення

CPX - це CLI-інструмент, який дозволяє запускати команди з будь-якого 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

Коли пакет має один бінарний файл або його бінарник збігається з назвою пакета, можна не вказувати команду:

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

Якщо пакет має більше одного бінарника і ви не вказали конкретний, версія 2.0 запропонує вибрати потрібний.

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

cpx ../my-package --version

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

Локальні бінарники мають пріоритет

Це найважливіша зміна поведінки порівняно з версією 1.x. CPX тепер спочатку шукає бінарник у вашому проєкті перед встановленням ізольованої копії. Він піднімається вгору від поточної директорії, щоб знайти найближчий 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 запускає версію, закріплену у вашому проєкті, а не найновішу. Коли локального бінарника немає, CPX встановлює та запускає ізольовану копію. Щоб примусово використати ізольовану копію, передайте --skip-local перед назвою пакета.

Аліаси тепер визначаєте ви

Версія 1.x мала фіксований список скорочень для популярних пакетів, тому cpx phpstan та cpx laravel працювали одразу. Цього списку більше немає у версії 2.0. Натомість ви самі визначаєте аліаси:

cpx alias phpstan/phpstan phpstan
cpx alias laravel/pint

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

Дві інші корисні команди управління: cpx installed показує пакети, які ви запускали через CPX, а cpx clean видаляє ті, що не використовувалися нещодавно (--all видаляє все). Зверніть увагу, що cpx list тепер показує доступні команди CPX (стандартна поведінка консолі), а не встановлені пакети.

Виконання PHP-файлів, Gist та 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 містить кілька PHP-файлів, CPX запитає, який запустити, або можна додати якір файлу зі сторінки gist, щоб пропустити запит. Додавання SHA закріплює ревізію, а встановлення GITHUB_TOKEN допомагає обійти ліміт GitHub.

Обидві команди виконують підготовчу роботу перед запуском вашого коду. Автозавантажувач Composer визначається в поточній або батьківській директорії. Класи, які використовуються без імпорту, отримують псевдоніми там, де CPX може знайти збіг. У Laravel-проєкті додаток повністю завантажується з конфігурацією, фасадами, .env та доступною змінною $app; у Symfony-проєкті завантажується ядро і доступні $kernel та $container. Передайте --no-boot, щоб пропустити це. Ваш код виконується у власному PHP-процесі, тому не може конфліктувати з залежностями CPX, а коди exit() передаються далі.

Усередині цих скриптів cpx_require() завантажує пакет на вимогу:

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

У Laravel-проєкті з встановленим laravel/tinker команда cpx tinker передає виконання у власний php artisan tinker вашого проєкту і пробрасує аргументи, такі як --execute. У всіх інших випадках відкривається PsySH-оболонка з завантаженим проєктом.

Вивід для агентів

CPX визначає, коли він не підключений до інтерактивного терміналу. Це охоплює перенаправлення stdin, передачу --no-interaction або -n, а також виконання всередині AI-агента, який ідентифікується через laravel/agent-detector.

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

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

Запуск пакетів виводить лише результат роботи самого інструменту, без прогрес-індикаторів CPX. Помилки на рівні CPX, такі як нерозпізнана команда або неможливість встановлення пакета, також повідомляються у форматі JSON. Передайте --json, щоб отримати такий самий вивід в інтерактивному терміналі. Перезапис існуючого аліаса в неінтерактивному режимі вимагає --force.

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

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

composer global require cpx/cpx

Додаткова інформація

CPX спочатку створив Liam Hammett. CPX 2.0 тепер є офіційним пакетом laravel/cpx з кількома контриб'юторами від Laravel. Якщо хочете побачити живу демонстрацію, Taylor Otwell представив і продемонстрував CPX 2.0 під час свого виступу на Laracon US 2026 у Бостоні.

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