Laravel Pot Laravel Package

Getting Started

Install it as a dev-only dependency — this is an inspection tool, not runtime infrastructure:

composer require nunomaduro/laravel-pot --dev

The package registers itself through Laravel's package auto-discovery, so there is nothing to add to config/app.php in a modern skeleton. Verify the registration actually happened before assuming anything about the command surface:

php artisan list | grep -i pot

Because the command names have been renamed/reshuffled across versions more than once, treat artisan list as the source of truth rather than copying command names out of a blog post or a gist. If you're on a Laravel version the package hasn't been updated for, the provider may register but the commands may blow up — check composer show nunomaduro/laravel-pot for the supported illuminate/* constraints.

Where to look first: the package is deliberately small. Open vendor/nunomaduro/laravel-pot/src and read the command classes top to bottom — it's a few hundred lines and it will tell you more about what the output means than any README. Each command is essentially a formatted dump over $app->getBindings(), getAliases(), getInstances(), so once you've read one you know what all of them do.

First use case: you join a codebase (or install a package) and something resolves to "the wrong thing" — an interface bound to a base implementation when you expected the decorated one, or a singleton where you expected a fresh instance per resolution. Instead of dd(app()) and scrolling through a 400-line array dump, run the pot command and read the table: abstract → concrete, singleton or not, already instantiated or not. That's the ten-minute win that justifies the dependency.

Implementation Patterns

Recon on unfamiliar codebases. Before touching a service provider, dump the container state as the framework sees it. This is faster than grepping for $this->app->bind( across vendor/ and your own app/Providers, because it also surfaces what was registered conditionally.

php artisan pot --env=local

Diffing environments. The interesting bugs live in the gap between local and production bindings. Run the same command with and without config caching, and with the two .env files, and diff the output:

php artisan pot > /tmp/pot-local.txt
php artisan config:cache && php artisan pot > /tmp/pot-cached.txt
diff /tmp/pot-local.txt /tmp/pot-cached.txt

Anything that appears or disappears is a provider branching on app()->environment() or config('app.debug') — a classic source of "works on my machine."

Fallback when the commands don't cover what you need. The commands are thin wrappers; you can reproduce them in Tinker and get exactly the shape you want:

php artisan tinker --execute="
collect(app()->getBindings())
    ->map(fn (\$c, \$k) => [\$k, \$c['concrete'], \$c['shared']])
    ->sortBy(0)
    ->each(fn (\$r) => dump(implode('  ', [\$r[0], is_string(\$r[1]) ? \$r[1] : get_debug_type(\$r[1]), \$r[2] ? 'singleton' : 'bind'])));
"

This is the pattern I actually reach for most days; the package is a nicer presentation of the same three accessors.

Third-party provider archaeology. When a package ships four providers and you can't tell which one is doing the binding, inspect the container after composer require but before you write a single line of config. If the binding you expected isn't there, the provider is either deferred (see Gotchas) or gated behind a config flag you haven't published.

CI guardrails. The output is stable enough to assert against. A cheap regression test: snapshot the binding count per environment and fail the build if a deploy adds an unexpected singleton. This catches the "someone left $this->app->singleton() in a dev-only provider" class of bug that otherwise shows up as mysterious state bleed in queue workers.

Onboarding artifacts. When you finish untangling a container, paste the output (pruned of secrets in class names) into the PR description or an ADR. It's the clearest possible explanation of why a decorator chain exists.

Gotchas and Tips

Deferred providers lie to you. A binding registered by a deferred provider does not exist until something resolves a service from that provider. A container dump on a fresh process will show a smaller world than the one a real request sees. If a binding is "missing," resolve one thing related to it first and re-run.

Bindings ≠ aliases ≠ instances. getBindings() gives abstract → concrete. getAliases() gives the short names that map onto abstracts ('db' → Illuminate\Database\DatabaseManager). getInstances() gives what's already been resolved and is now cached — singletons and anything instance()-registered. A concrete that appears in instances but not bindings was registered with $app->instance(), which is a smell worth chasing.

Contextual bindings are invisible. $this->app->when(Foo::class)->needs(Bar::class)->give(Baz::class) doesn't show up in a flat binding dump. If a class resolves correctly inside Foo but not via app(Bar::class), the container map won't explain it — you need to read the provider.

Never let it reach production. --dev means composer install --no-dev strips it, which is correct. But watch your deploy pipeline: if any step runs composer install without --no-dev in a build image that ships to prod, you've added a command surface that exposes your class graph. Add it to dont-discover if you're paranoid, or just confirm the flag.

Config and route caching change what you see. php artisan optimize / config:cache can alter which providers register conditionally. Always note whether you were cached when you took the dump, or you'll chase a phantom.

Don't confuse it with a profiler. This tells you what is bound, not what got resolved at runtime, how long it took, or who asked for it. For resolution timing and call sites, use Telescope's service events, Debugbar, or a Container::resolving() listener. Pot answers "what's in the box," not "what came out of it and why."

Version drift is the real risk. ~100 stars and zero dependents means you are the QA. Pin the version in composer.json, and if a Laravel upgrade breaks the commands, fall back to the Tinker snippet above — it's five lines and depends on nothing but the framework. Don't build CI on top of the command output unless you've pinned.

Extension point. If you need machine-readable output for tooling, write your own artisan command rather than parsing the pretty table. The container accessors are public API; the package's formatting is not.