Blueprint Laravel Package

Getting Started

Start by installing Blueprint as a dev dependency: composer require -W --dev laravel-shift/blueprint. Create a blueprint.yaml (or blueprint.yml) file in your project root—this YAML file defines the components you want to generate using a concise, human-readable syntax. For your first attempt, copy the blog example from the docs: define a Post model with basic fields and a PostController with index and store actions. Run php artisan blueprint:build to see how Blueprint generates models, migrations, factories, controllers, routes, tests, and more—all from one file.

Implementation Patterns

Use Blueprint early and often in your workflow:

• Scaffold new features in minutes: Define an entire CRUD resource (model, controller, form request, tests, views, policies) in one YAML block before writing a line of PHP.
• Standardize across teams: Share a project’s blueprint.yaml with teammates or templates for common patterns (e.g., API-only resources, CRUD with soft deletes, policies).
• Iterate on domain models: Change the YAML spec and regenerate—Blueprint intelligently handles incremental updates (e.g., adding fields, modifying controller logic) without overwriting manual changes to stubbed code.
• Integrate with Livewire/Inertia: Use dedicated controller statements (livewire, inertia) to generate component classes and views when building real-time or SPA-style interfaces.
• Extend via stubs and macros: Customize generated code by publishing stubs (vendor:publish --tag=blueprint-stubs) or adding custom YAML shorthands and generators for opinionated patterns (e.g., “audit-friendly” models, custom UUID conventions).

Gotchas and Tips

• Laravel 11+ required: Blueprint v2+ only supports Laravel 11 or higher; upgrade your app or pin an older version if needed.
• Test generation depends on test assertions: Install jasonmccreary/laravel-test-assertions for generated tests to pass out-of-the-box—missing this causes validation assertions to fail.
• Be cautious with re-generation: Blueprint leaves manually-edited sections intact but will regenerate test, migration, and view files. Always review changes with git diff after running blueprint:build.
• Use blueprint:trace to debug: If generation fails silently or misbehaves, run php artisan blueprint:trace to see how Blueprint parsed your draft file—including model and controller resolution.
• Namespace & naming quirks: Blueprint auto-detects model namespaces (e.g., App\Models\Post), pluralizes routes by default, and handles ULID, UUID, and geo types—but verify foreign key resolution (e.g., author_id: id:user → User model) matches your conventions.
• Pest compatibility: Blueprint generates Pest tests when your app uses Pest, but ensure the base TestCase class has AdditionalAssertions imported (automatic if using Laravel’s default Pest setup).
• Custom field mappings: Define int => integer or custom types via config (blueprint.php) if using non-standard column modifiers (e.g., unsignedInteger, geoPoint).