Jack Laravel Package

Getting Started

First, decide whether to install at all. rector/jack is marked deprecated and archived — the repo description says "[Deprecated] and moved to ↓" — on top of being explicitly experimental with zero dependents. If you're evaluating it today, find the successor package first; the guidance below still applies to anyone already running Jack or working with a fork pinned in an existing project.

Assuming it's already in the project (or you're doing a time-boxed trial):

1. Install as a dev dependency — it never touches runtime:

   composer require rector/jack --dev
   

   The README claims PHP 7.2+, but the 1.2.1 release notes say the source was backported to PHP 7.4 and is tested on 7.4 / 8.2 / 8.5. On a PHP 7.2–7.3 project, pin an older tag or skip it.

2. Start read-only. breakpoint is the only command that doesn't mutate composer.json, so run it first:

   vendor/bin/jack breakpoint --dev --limit 3
   

   It counts major outdated packages and exits non-zero above the limit. --dev restricts the scan to require-dev, which is where the low-risk wins are.

3. First real use case: pick the single noisiest dev package (usually phpunit/phpunit or larastan/phpstan), preview the change, and complete one full cycle:

   vendor/bin/jack open-versions --dev --package-prefix phpunit --limit 1 --dry-run
   # review the diff, drop --dry-run, run composer update, run tests, commit
   

Where to look first: the README's three numbered command sections map one-to-one to the three commands — there is no config file, no service provider, no facade. Everything is CLI flags. Release notes matter more than the README here, because the 1.x line changed the PHP floor and the dependency footprint.

Implementation Patterns

CI gate for dependency debt (the highest-value pattern). Add breakpoint to your pipeline as a scheduled job rather than a blocking PR check — otherwise a single stale package fails unrelated feature branches.

# .github/workflows/dependency-debt.yml
- run: composer install --no-interaction --prefer-dist
- run: vendor/bin/jack breakpoint --dev --limit 5

Run it weekly (or nightly) and treat a red build as a ticket generator, not an emergency. Ratchet the --limit down over time (5 → 3 → 1) as the team clears debt. Cache composer.lock and run it after composer install — the breakpoint scan is much slower when it has to resolve from scratch on a large monorepo.

The incremental upgrade loop. Jack deliberately does not run composer update for you — it only widens constraints. Respect that split and script it:

open-versions --dry-run  →  review diff  →  open-versions  →  composer update  →  tests  →  commit

Keep each cycle to a handful of packages (--limit 3 is a sane default; --limit 1 when touching anything in require). One commit per cycle makes git bisect trivial when something breaks three weeks later.

Batch by prefix for framework-coupled packages. Laravel's illuminate/* components and Symfony components move in lockstep — Jack treats them as independent entries, so a mixed batch will produce a partially-consistent composer.json. Constrain the blast radius:

vendor/bin/jack open-versions --package-prefix illuminate --limit 6 --dry-run
vendor/bin/jack open-versions --package-prefix symfony --limit 6 --dry-run

Never let open-versions touch laravel/framework in the same pass as illuminate/* — do the framework bump manually and let Composer's resolver drive the rest.

Reconcile after every merge. raise-to-installed is the inverse operation and the one people forget. Dependabot/PR merges and manual composer update runs leave composer.json advertising constraints lower than what's actually installed, which means a fresh composer update on another machine (or in Docker) can silently downgrade you. Wire it into a post-update check:

vendor/bin/jack raise-to-installed --dry-run

Run it right before a release branch cut, not on every push — the diff is noisy and only meaningful when composer.lock is settled.

Composer scripts as the team interface. Since there's no config file, the only extension point is wrapping the binary. Give the team memorable aliases so nobody hand-types flags:

"scripts": {
  "deps:check": "jack breakpoint --dev --limit 5",
  "deps:open-dev": "jack open-versions --dev --limit 3 --dry-run",
  "deps:align": "jack raise-to-installed --dry-run"
}

Pair with composer validate --strict and composer normalize after every mutation — Jack writes valid JSON, but it does not check whether the resulting constraint set is coherent (e.g. a php requirement that excludes the versions you just opened up to).

Gotchas and Tips

The deprecation is the headline gotcha. No further releases mean the Windows console bug fixed in 0.2.7 is the last fix you get, and the "experimental, breaking changes" caveat is now permanent. Pin an exact version ("rector/jack": "1.2.1" rather than ^1.0) so a fork or a composer update can't move you onto something unexpected. Keep it out of require in any project you can't easily patch.

Widened ranges are not targeted upgrades. open-versions appends the next major (^9.0 → ^9.0|^10.0), but it's Composer that decides what actually installs — and Composer takes the newest satisfiable version. On a Laravel 9 app, ^9.0|^10.0 for PHPUnit resolves to PHPUnit 10, which needs PHP 8.1. Check composer show --platform against the new constraint before committing, and run your test matrix, not just your local PHP.

raise-to-installed tightens by design. It rewrites ^6.4|^7.2 to ^7.2. If that package is a library you publish, or if you claim to support an older Laravel line, this silently drops supported versions. Only run it on applications, and only after confirming the installed version is the one you intend to commit to.

Framework awareness is zero. Jack reads composer.json as a flat list of names and constraints. It does not know that illuminate/container 12.14 implies a matching laravel/framework, nor that Symfony 7 requires PHP 8.2. Treat every diff as a proposal requiring a human who knows the framework's compatibility matrix.

Always --dry-run first on mutating commands. open-versions and raise-to-installed rewrite composer.json in place with no confirmation prompt and no backup. In CI, never auto-commit their output — the whole value is the human review step.

Ensure the lock file is in sync before you start. Jack reasons about composer.json constraints; if composer.lock is stale (common after a merge conflict resolution), raise-to-installed will happily align your constraints to a version set that no longer resolves. Run composer install first.

Verify --dev semantics against your version. The flag filters to require-dev; don't assume it adds dev packages to a full scan. Read the breakpoint output header each time to confirm which section was scanned — a green CI run that only checked dev packages is not evidence your production deps are current.

Windows CI: pin >=0.2.7. Earlier releases rendered corrupted diffs against Symfony Console 6.4.24+, which is exactly the kind of thing you'd waste a morning debugging in a pipeline log.

No extension points beyond the CLI. If you need custom logic (e.g. "never open laravel/framework"), the answer is a wrapper script or a Composer script that filters package lists — not a Jack config. Budget for that rather than searching for a config file that doesn't exist.