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.
