Builder Laravel Package

Getting Started

1. Verify you're on a compatible Laravel first. This package's last release was August 2017, targeting Laravel 5.1–5.4 on PHP 5.6/7.0. On anything newer, composer require grafite/builder will either fail resolution or install something that fatal-errors on boot (deprecated string-based service provider bindings, removed str_*/array_* helpers, Route::controller usage). Check composer.json constraints in the repo before you start; if you're on Laravel 6+, plan to fork and patch rather than install.

2. Install and register.

composer require grafite/builder

On Laravel ≤5.4, add to config/app.php:

Grafite\Builder\BuilderServiceProvider::class,

'Builder' => Grafite\Builder\Facades\Builder::class,

3. Publish the config/boilerplate (this is your first look — read what lands):

php artisan vendor:publish --provider="Grafite\Builder\BuilderServiceProvider"

Then run the installer on a clean git branch:

php artisan builder:setup

4. Where to look first, in this order:

• config/builder.php — paths, namespaces, stub locations; almost every mismatch you'll hit later is configured here.
• vendor/grafite/builder/src/Console/Commands/ — the actual generator classes; this is the real documentation, since the README is thin and the repo is archived.
• The stub directory — generated output is only as good as these templates, and they encode the author's conventions.
• php artisan list — confirm the exact command set on your pinned version before scripting anything.

5. First use case: scaffold a single, low-risk resource end-to-end (e.g. a Post CRUD), then read every generated file before accepting it. Migration → model → controller → routes → views → tests. If it doesn't run clean after php artisan migrate, the package's assumptions don't match your app and you need to fix stubs, not code.

Implementation Patterns

Greenfield bootstrap. The intended flow is builder:setup once to lay down the base boilerplate (layout, routes, base controller conventions), then one scaffolding command per resource. Treat setup as a one-shot: it writes into your app and is not idempotent.

CRUD-first resource loop. The day-to-day win is turning "model + migration + controller + routes + views + tests" into one command:

php artisan builder:crud   # prompts for table/model name
php artisan migrate
php artisan test           # or vendor/bin/phpunit on 5.x
git add -A && git commit -m "scaffold: Post"

Commit the scaffold as its own commit immediately. Everything downstream is hand-editing, and having a clean revert point is what makes regeneration safe.

API/web split. Use the API scaffolding command for JSON endpoints and the CRUD command for the admin-facing side of the same resource. Generate both from the same table so naming and validation stay consistent, then unify the validation rules into a form request by hand.

Programmatic use via the facade. The facade/service behind the commands is the real extension point. If you have house conventions (repository + interface, form requests, policies), write a thin project-local command that calls the generator service with your own stub paths rather than teaching every dev to post-edit generated output. This is the pattern that actually pays off — it turns a 2017 scaffolder into your scaffolder.

Customize stubs once, in-repo. Publish the stubs and commit them into your project, then point config/builder.php at your copies. This keeps generated code idiomatic (your namespace, your base controller, your test base class) and survives composer update.

Keep it out of production. This is a build-time tool. Prefer require-dev, and if the service provider must load for local commands, guard it:

if ($this->app->environment('local')) {
    $this->app->register(\Grafite\Builder\BuilderServiceProvider::class);
}

Complement, don't replace, make:*. Use artisan make:model, make:request, make:policy for one-offs; reserve the builder commands for full resource stacks where the boilerplate volume justifies the convention lock-in.

Gotchas and Tips

• The archive status is the headline gotcha. No fixes, no Laravel 6+/PHP 8 support, zero dependents. You are adopting code you now own. Budget a fork: replace deprecated helpers, convert provider bindings, update composer.json, and vendor it as a path repository or private package.
• Generators overwrite. Assume any existing file at the target path is at risk. git status before and after every command, and never run builder:setup on a repo with uncommitted work.
• builder:setup mutates your app. It edits routes, config, and possibly .env. Snapshot (commit or git stash-free branch) before running; there is no uninstall.
• Convention coupling fails at runtime, not generation time. Generated models/controllers assume a particular namespace (App vs App\Models), table inflection, and base class. Generation succeeds, then you get a 500 on first request. Align config/builder.php before generating, not after.
• Config caching silently eats your changes. After editing config/builder.php: php artisan config:clear.
• Duplicate migrations on regeneration. Each run timestamps a new migration. Delete the previous one, or you'll get "table already exists" on the next migrate.
• Interactive prompts break CI. These commands ask questions; they're fine for a dev machine, painful in scripts. Either pipe answers, find non-interactive flags by reading the command class, or wrap the underlying service in your own command with arguments.
• Debugging generation failures: run with -v, open the command class in vendor/grafite/builder/src/Console/Commands/, and find which stub it renders. The most common failure is an unreplaced stub token (leftover {{class}}/{{table}}) or a stub path that moved after publishing.
• Generated tests reference things that don't exist yet. Factories and seeders usually aren't generated. Write the factory before running the generated test suite, or you'll chase red herrings.
• Extension points, ranked: (1) your own stubs via config, (2) your own command wrapping the generator service, (3) binding a custom implementation of the generator in the container behind the facade, (4) forking. Reach for (1) and (2) first — they're upgrade-safe and get you 90% of the value.