README

devkit-composer-manager

Interactive CLI for Composer scripts, dependencies, autoload, config, and repositories — with validation, favourites, and a Symfony TUI.

Table of Contents

• Why this exists
• Prerequisites
• Install
• How to run it
• Add Composer shortcuts using manage
• Wire Composer shortcuts manually
• Manage menu reference
• CLI commands reference
• Behaviour notes
• Quick test (this repo)
• Full local setup
• Development
• Support
• License

Why this exists

composer.json scripts grow over time: test suites, linters, deploy steps, one-off helpers. Listing them with composer run-script --list is fine, but finding, running, favouriting, and editing scripts — plus dependencies, autoload, config, and repositories — usually means jumping between docs, grep, and hand-editing JSON.

This tool gives you a single CLI that walks up to the nearest composer.json, shows scripts in a table (with filters and favourites), runs them via composer run-script, and offers an interactive manage hub. On PHP 8.4+ with symfony/tui installed, manage uses a full-screen TUI; on PHP 8.3 (or without TUI), the same flows use numbered console menus. Before mutating composer.json, it writes composer.json.bak.

Package: devkit/composer-manager

Prerequisites

composer require symfony/tui:^8.1

Install

composer require devkit/composer-manager

git clone https://github.com/stuarttodd-dev/devkit-composer-manager.git
cd devkit-composer-manager
composer install

{
  "repositories": [
    {
      "type": "path",
      "url": "../devkit-composer-manager"
    }
  ],
  "require-dev": {
    "devkit/composer-manager": "@dev"
  }
}

How to run it

The CLI finds composer.json by walking up from the current working directory (or from --dir / -d). Run from your application root, or pass --dir to target another project.

1. Install the package

composer require devkit/composer-manager

2. Run the binary

# After composer require (consumer project)
./vendor/bin/devkit-composer-manager --help

# This repo (development)
php bin/devkit-composer-manager --help

Windows: use vendor\bin\devkit-composer-manager.bat or php vendor\bin\devkit-composer-manager.

3. Open the interactive manager

Needs a real terminal (TTY):

./vendor/bin/devkit-composer-manager manage
# or, when stdin is a TTY:
./vendor/bin/devkit-composer-manager

4. List or run scripts without the menu

./vendor/bin/devkit-composer-manager list
./vendor/bin/devkit-composer-manager run tests
./vendor/bin/devkit-composer-manager list --filter=test

Default command

Global option

Passing options through Composer scripts

Use -- before options when calling through composer run-script so Composer does not consume them:

composer commands:list -- --filter=tests
composer commands:list -- --filter='/^test/' --regex
composer commands:run -- tests --no-interaction

Docker

Mount your project and run from the app root inside the container:

docker compose run --rm -it composer php vendor/bin/devkit-composer-manager manage

Ensure devkit/composer-manager is installed in that project’s composer.json.

Add Composer shortcuts using manage

The easiest way to wire shortcuts is through manage itself — no hand-editing JSON.

Example: add composer commands:manage

1. Open manage (from your project root):

   ./vendor/bin/devkit-composer-manager manage

2. Main menu — choose Scripts (usually option 1).

3. Scripts menu — choose Add script.

4. Script name — enter:

   commands:manage
   

5. Command line — enter:

   vendor/bin/devkit-composer-manager manage
   

   Confirm the line when prompted. For a multi-line script, choose Add another line after each line; leave the line empty when finished.

6. Preview — confirm the summary.

7. Back — return to the main menu, then Exit.

8. Test the shortcut:

   composer commands:manage

Add the rest of the recommended shortcuts

Repeat Scripts → Add script for each row below:

After that you can use composer commands:list, composer commands:manage, and so on.

Tip: star your daily drivers with Scripts → Toggle favourite, or composer commands:favourite add tests.

Wire Composer shortcuts manually (recommended set)

Alternatively, paste this into the consumer project’s composer.json:

{
  "scripts": {
    "commands:list": "vendor/bin/devkit-composer-manager list",
    "commands:run": "vendor/bin/devkit-composer-manager run",
    "commands:favourite": "vendor/bin/devkit-composer-manager favourite",
    "commands:add": "vendor/bin/devkit-composer-manager add",
    "commands:edit": "vendor/bin/devkit-composer-manager edit",
    "commands:remove": "vendor/bin/devkit-composer-manager remove",
    "commands:manage": "vendor/bin/devkit-composer-manager manage",
    "commands:guide": "vendor/bin/devkit-composer-manager guide",
    "commands:help": "vendor/bin/devkit-composer-manager help",
    "commands:cli": "vendor/bin/devkit-composer-manager list-commands"
  }
}

In this repo, the same shortcuts use @php bin/devkit-composer-manager … so Composer invokes PHP on the checked-in binary.

Manage menu reference

Open with ./vendor/bin/devkit-composer-manager manage (or composer commands:manage once wired).

On PHP 8.4+ with symfony/tui, menus use full-screen lists and a multi-line editor (Ctrl+Enter to submit). Otherwise numbered console menus are used. Destructive or structural changes show a preview and ask for confirmation before saving.

Main menu

Scripts

Dependencies / Dev dependencies

Both sections work the same; dev uses require-dev and passes --dev to Composer.

Packagist search shows package name, description, installs, stars, and a Packagist URL column. Use Next page, Previous page, Search again, or Exit results while browsing.

Autoload / Autoload dev

Same actions; Autoload dev writes to autoload-dev.

Config

Manages the "config" block — Composer behaviour settings (not packages or autoload).

Preset config keys (available when adding):

Keys already present in composer.json are hidden from the preset list. Custom keys accept true/false, numbers, strings, or JSON objects/arrays.

Repositories

Backups

Snapshots live in .devkit-composer-manager/backups/. Every edit also writes a quick composer.json.bak next to your project file.

Run a script

Pick a script from the list → executes via composer run-script → returns to main menu when finished.

CLI commands reference

Global option on all project-aware commands: --dir / -d — project root to search for composer.json.

list

vendor/bin/devkit-composer-manager list
vendor/bin/devkit-composer-manager list --filter=test
vendor/bin/devkit-composer-manager list --filter='/^test/' --regex

run

vendor/bin/devkit-composer-manager run
vendor/bin/devkit-composer-manager run tests
vendor/bin/devkit-composer-manager run --favourites-only

favourite

vendor/bin/devkit-composer-manager favourite add tests
vendor/bin/devkit-composer-manager favourite remove tests
vendor/bin/devkit-composer-manager favourite list

Favourites are stored in extra.devkit-composer-manager.favourites.

add

vendor/bin/devkit-composer-manager add --name=qa --line="./vendor/bin/pest"
vendor/bin/devkit-composer-manager add   # interactive prompts

edit

vendor/bin/devkit-composer-manager edit tests
vendor/bin/devkit-composer-manager edit tests --line="phpunit" --line="echo done"

remove

vendor/bin/devkit-composer-manager remove old-script
vendor/bin/devkit-composer-manager remove old-script --force

Help

vendor/bin/devkit-composer-manager help
vendor/bin/devkit-composer-manager help run
composer commands:help run

• list — table of Composer scripts in the project.
• list-commands — this app’s CLI subcommands (run, favourite, add, …).
• guide — install, shortcuts, and examples in the terminal.

Behaviour notes

• composer.json only — every read, write, backup, restore, and composer require/remove targets composer.json in the project root. The COMPOSER environment variable (e.g. composer.local.json in Docker) is ignored so this tool always adjusts the same file you commit.
• Startup — on load, composer.json is repaired (common shape issues) and validated with composer validate. Invalid files show errors and exit before the menu opens.
• Dependencies — add/remove runs composer require / composer remove so composer.lock stays in sync. Version picker loads stable releases from Packagist when adding a package.
• Validation — repositories, autoload paths, config keys/values, script names/lines, package names/constraints, and list filters are validated on input.
• Symfony TUI — when symfony/tui is installed on PHP 8.4+, filterable full-screen pickers in interactive mode; otherwise console menus.
• Run uses php vendor/bin/composer run-script <name> when that file exists, otherwise composer on your PATH.
• Backups — timestamped snapshots in .devkit-composer-manager/backups/; quick composer.json.bak before each edit; restore can auto-backup current file and runs composer update.
• Favourites — extra.devkit-composer-manager.favourites (legacy extra.devkit-composer-ui.favourites and extra.devkit-composer-commands.favourites still read).
• Saving composer.json may normalise formatting (Composer’s JSON writer).

Quick test (this repo)

From the project root, after dependencies are installed:

composer install
php bin/devkit-composer-manager list
composer tests

You should see a table of script names and definitions, then passing Pest tests.

Optional one-liners:

php bin/devkit-composer-manager list --filter=tests
php bin/devkit-composer-manager guide
php bin/devkit-composer-manager help run
php bin/devkit-composer-manager list --dir=/path/to/other/php/project
composer commands:manage

Full local setup

1. Get the code and install dependencies

   git clone https://github.com/stuarttodd-dev/devkit-composer-manager.git
   cd devkit-composer-manager
   composer install

2. Automated tests

   composer tests

3. Docker (optional)

   docker compose build --no-cache --pull
   docker compose run --rm app php -v   # must show PHP 8.3.x
   docker compose run --rm app php bin/devkit-composer-manager list
   docker compose run --rm -it app php bin/devkit-composer-manager   # interactive manage
   docker compose run --rm app composer tests

   The image is php:8.3-cli with Composer installed. The project is mounted at /src, so local edits are visible in the container. Rebuild after pulling changes: docker compose build --no-cache --pull app.

   For TUI testing inside Docker, use a PHP 8.4 image and run composer require symfony/tui:^8.1 in the container.

Development

composer run tests
composer run standards:check

Support

If this project saves you time, consider buying me a coffee:

License

MIT