Download the PHP package alwayscurious/laravel-project-devtool without Composer

Laravel Project Devtool

Simplify your developers' startup time on new projects from an existing repo — one command to a clean-slate dev environment, and a clean way for your app to hook into it.

php artisan project:dev --setup tears the local environment down and rebuilds it from scratch: clear caches → migrate:fresh → seed → build assets. Onboard a new teammate, recover from a broken branch, or reset between feature spikes in a single command instead of a wiki page of steps.

The part that makes it worth installing instead of writing your own shell script: at every stage of the reset it fires a lifecycle event, and your app attaches its own work by dropping a listener into app/Listeners. Generate permissions, seed demo data, print login credentials — without ever editing this package. The engine is mechanism; your app supplies the policy.

⚠️ Dev-only. --setup runs migrate:fresh, which drops every table. Install it as a --dev dependency and never point it at data you care about.

Install

That's the whole setup — the command auto-registers. Publish the config only if you want to change defaults:

Try it:

The command

Before wiping anything, --setup confirms with a prompt that names the exact connection and database it's about to drop — so a wrong .env can't surprise you. --force skips it. And it refuses to run in production unless you pass --force-production.

Run only the steps you need

--setup is no longer all-or-nothing. The selectable steps, in order, are install, caches, migrate, seed, build. Use --only to run a subset or --skip to drop a few:

The confirmation prompt only appears when a destructive step (migrate or seed) is actually in the run — --only=caches won't ask.

Preview with --dry-run

--dry-run walks the entire sequence, prints what each step would do, fires every lifecycle event (so your listeners can announce their intent too), and changes nothing — no migrations, no seeding, no processes, no prompt:

Timing report

Every real run prints a per-step timing table at the end, so you can see where onboarding time actually goes:

How --setup runs (and where you plug in)

The sequence is fixed and ordering-sensitive — your listeners can rely on it:

Each event carries the running command, so a listener gets the live console and can run nested artisan commands:

Why seeding comes after a separate DatabaseMigrated event

This is the design detail the package exists for. Some apps must generate data (permissions, lookup tables) after the schema exists but before the seeder runs — because the seeder consumes it (e.g. granting permissions to a role). So the reset deliberately fires DatabaseMigrated in the gap between migrate:fresh and db:seed, giving you a hook at exactly that moment. Merge the two and the seam disappears; keep them split and your app slots right in.

Integrating your app: write a hook

A hook is just a listener that type-hints one of the lifecycle events. Laravel's event discovery wires it up — no registration, no config, no service provider edits.

Scaffold one

Generates app/Listeners/BuildDemoData.php, pre-typed to the event and documented with the full event list. --event is validated and defaults to DatabaseSeeded.

Or write it by hand

Lifecycle reference

Hooks can't break the reset

A thrown exception from any listener is reported and swallowed so a broken custom hook never leaves you with a half-built database. The single exception is the deliberate veto below.

Guarding the reset: AbortSetup

Veto a doomed run before anything destructive happens by throwing AbortSetup from a SetupStarting listener:

The command prints the message, says “Nothing was changed.”, and exits with a failure code — the database is never touched. AbortSetup is honoured only from the SetupStarting pre-flight point; thrown later it's treated as a misplaced veto (warned and swallowed) so it can't corrupt a half-built database.

Batteries (opt-in recipes)

Common integrations ship as listeners that are off by default — a project that doesn't use them pulls in zero coupling — and self-guard when an optional dependency is missing.

Filament Shield permissions

GenerateShieldPermissions regenerates filament-shield permissions on DatabaseMigrated, in the gap before seeding, so your seeder can grant them to a super-admin role. If filament-shield isn't installed it skips with a notice instead of failing. Enable it in config:

Configuration

config/project-devtool.php — everything you'd want to vary, nothing hardcoded:

• build → null/[] skips the asset build (the command tells you it did).
• seeder → a class name to seed something other than the default DatabaseSeeder.
• install → swap in yarn, pnpm, bun, etc.

Requirements

• PHP ^8.3
• Laravel 11, 12, or 13

Testing

License

The MIT License (MIT). See License File.