Dev Bundle Laravel Package

Getting Started

perform/dev-bundle is a Composer meta-package whose purpose is to pull a set of Laravel developer tools into a project in one shot rather than wiring them up one at a time. Treat it as a starting point for local tooling, not a production dependency.

Install (as a dev dependency):

composer require --dev perform/dev-bundle

Because it is a bundle, the value is in what it pulls in — expect it to bring along a subset of the usual Laravel dev stack (debugbar, IDE helper, Pint, PHPStan/Larastan, log viewer, possibly Telescope). Your first stop should be:

1. composer show perform/dev-bundle — read the requires list. That tells you exactly which tools you are actually getting, which is the single most important fact about a bundle package. If the require list is empty or thin, the bundle adds nothing over installing the individual tools yourself.
2. The package's README and composer.json in the repo — look for a laravel section with providers / aliases (auto-discovery). If the bundle registers a ServiceProvider, note whether it guards registration by environment ($this->app->environment('local', 'testing')) or runs unconditionally.
3. php artisan about and php artisan serve — confirm the app still boots after install. A bundle pulling five packages can silently shadow config or fail to boot on an older/newer Laravel major.

First use case: a fresh clone on a new machine. Onboarding a contributor should be composer install and nothing else — no “also run composer require --dev …” step in the README. If you can get from clone to a working Xdebug-less local environment with the bundle and a single composer install, it has done its job.

If you are on an existing project, do not install this blind. Diff the bundle's requires against your composer.lock first; a dev bundle that force-upgrades a transitive dependency can break your toolchain (e.g. Pint vs. PHP-CS-Fixer formatting rules changing under you).

Implementation Patterns

Environment-gated service provider. The most common pattern in these bundles is a provider that boots only in local/testing. If the bundle ships one, do not duplicate it. If it does not, register it yourself in AppServiceProvider::boot():

if ($this->app->environment('local', 'testing')) {
    // any manual bootstrapping the bundle requires
}

Publish selectively, not blindly. Run php artisan vendor:publish --tag=... per tool so you know which config file came from where. Bundles often ship a --tag=dev-bundle-config that publishes several configs at once; that is convenient the first time and confusing on the second project when you need to diff defaults. Keep published configs in version control and let the bundle’s defaults drift — your local copy is the contract.

Composer scripts are the real integration point. A well-formed dev bundle slots into your existing composer.json scripts. Wire it up so day-to-day commands stay short:

"scripts": {
  "test": ["@php artisan test"],
  "lint": ["pint --test"],
  "stan": ["phpstan analyse"]
}

Then composer lint, composer stan, composer test become the shared entry points regardless of whether the underlying tool is Pint, PHP-CS-Fixer, Larastan, or Psalm. This is the highest-leverage thing you can do with the bundle: it decouples your commands from the bundle’s choices, so swapping the bundle later is a one-line change.

CI is not the bundle’s home. Install with --dev locally, but in CI install with composer install --no-dev for the build artifact and a separate job with dev deps for lint/static analysis. Do not let a dev bundle leak into the runtime image. If you are on Sail, add the bundle to the host composer.json only; the container gets it via the mounted vendor directory.

IDE helper cadence. If the bundle includes barryvdh/laravel-ide-helper, add its generation to your post-update hook and gitignore the generated _ide_helper*.php files. Regenerating on every save is wasteful; regenerating never means stale facades and phantom IDE errors.

Log viewer / debugbar in local only. If a log viewer (Pail, LogViewer) or debugbar is pulled in, confirm the middleware/route is environment-gated. A dev-only route that answers in production is a real information leak.

Gotchas and Tips

Auto-discovery is not environment-aware. Composer package discovery has no concept of --dev. A provider registered via the bundle's extra.laravel.providers boots on every environment where the package is installed — which is fine only if composer install --no-dev is guaranteed in production. Guard provider boot logic explicitly rather than relying on install flags.

The bundle is a moving target. Dev bundles pin versions loosely by design (they want to stay current). Read the changelog before composer update. A major bump in any constituent tool — Pint rule changes, PHPStan level shifts, Telescope migration changes — lands in your repo without you choosing it. If reproducibility matters, pin the bundle to a minor ("perform/dev-bundle": "~1.2") and bump deliberately.

Migration collisions. If Telescope, Horizon, or any bundle constituent ships migrations, they can collide with existing publish tags or fail on migrate:fresh in CI where the package isn’t installed. Either publish migrations once and own them, or exclude the dev database from your test suite and use RefreshDatabase against a schema that does not include dev tables.

Boot-time cost. Debugbar and Telescope add measurable request overhead. If local response times feel wrong, disable the bundle temporarily (composer remove --dev perform/dev-bundle) before profiling your own code. Memory is often the culprit — debugbar collectors on large payloads are a classic.

Low adoption signal. With zero stars and zero dependents you have no community to fall back on for breakage reports. Budget time to read the bundle’s source (it is small) before depending on it, and prefer it as a convenience wrapper you could inline in an afternoon if it is abandoned. If the require list is thin or the repo has gone quiet, install the underlying tools directly — you lose nothing but a single composer require.

Debugging a broken install. If composer require --dev fails on dependency resolution, run composer why-not perform/dev-bundle to see which of your existing packages is blocking it — usually a PHPStan or PHP version ceiling. If the app boots but tools are missing, php artisan about and composer dump-autoload first; providers that ship without discovery registration need manual addition to bootstrap/providers.php.

Extension point. If the bundle exposes a config file (config/dev-bundle.php), that is your hook for enabling/disabling constituents and setting tool paths. Publish it, commit it, and use it as the place to document your choice of tools for the next developer — it is the only durable artifact the bundle leaves you.