Blueprint

Overview: The Philosophy of Efficient Code Generation Programming efficiency isn't just about typing faster; it's about reducing the cognitive load required to translate a mental architecture into working code. Blueprint represents a significant evolution in the Laravel ecosystem, moving beyond basic file stubbing into true application automation. While the framework provides robust tools like `php artisan make:model`, these commands often leave developers with a "facade" of code—empty classes that still require manual configuration of migrations, fillable attributes, and controller logic. Blueprint bridges this gap by leveraging Laravel conventions to infer intent. By providing a simple YAML definition, a developer can generate migrations with correct data types, models with defined relationships, and controllers with functional, tested logic. This matters because it eliminates the tedious, repetitive boilerplate that consumes the first several hours of any new feature or project. It turns a dozen manual steps into a single build command, ensuring that best practices—like form request validation and comprehensive testing—are baked into the codebase from the first second. Prerequisites and Environment Setup Before utilizing Blueprint, you should have a baseline understanding of the PHP programming language and the Laravel framework. Specifically, familiarity with Eloquent ORM relationships, database migrations, and RESTful controller patterns is essential. From a tooling perspective, you need a local Laravel installation (version 10 or 11 is recommended) and Composer for package management. To get started, install Blueprint as a development dependency: ```bash composer require --dev laravel-shift/blueprint ``` If you want to use Blueprint's specialized testing assertions, such as checking if a controller used a specific form request or dispatched a particular job, you should also include the testing helpers: ```bash composer require --dev jasonmccreary/laravel-test-assertions ``` Key Libraries & Tools * **Blueprint**: The core code generation tool that parses YAML files to create Laravel components. * **Laravel Shift**: The organization behind Blueprint, primarily known for automated framework upgrades. * **YAML**: A human-readable data serialization language used to define application drafts. * **Pest**: A modern PHP testing framework supported by Blueprint as an alternative to PHPUnit. * **Eloquent ORM**: Laravel's active record implementation which Blueprint automates. Code Walkthrough: From Draft to Implementation The workflow begins with a `draft.yaml` file. This file acts as the architect's sketch of the application. Let's break down a logical section involving a conference management system. 1. Defining the Model You don't need to specify IDs or timestamps; Blueprint assumes these by default. Focus on the unique attributes and relationships. ```yaml models: Conference: name: string:400 starts_at: datetime venue_id: id:venue relationships: hasMany: Talk, Attendee ``` In this snippet, `string:400` tells the generator to create a column with a specific length. The `venue_id: id:venue` syntax is a shorthand that creates a foreign key and establishes a `belongsTo` relationship in the Eloquent model. 2. Crafting the Controller Blueprint uses "controller statements" to define logic. These are keywords like `query`, `render`, `redirect`, and `store`. ```yaml controllers: Conference: index: query: all render: conference.index with: conferences store: validate: name, starts_at, venue_id save: conference flash: conference.id redirect: conference.index ``` When you run `php artisan blueprint:build`, this results in a `ConferenceController` where the `store` method automatically uses a generated `ConferenceStoreRequest` for validation. It also creates the `conference.index` blade view and a migration file for the `conferences` table. 3. Automatic Testing Generation One of the most powerful features is the testing output. Blueprint doesn't just create a test file; it writes functional tests that use Model Factories to populate data and assert that responses are correct. If you define a `mail` or `dispatch` statement in your controller, Blueprint will automatically add `Mail::fake()` and `Bus::fake()` to the test, ensuring the code is fully covered. Syntax Notes: Shorthands and Conventions Blueprint is built on the idea of "typing less to get more." Several syntax patterns facilitate this: * **The `resource` keyword**: Instead of defining every action, you can type `resource: web` or `resource: api` under a controller name. This expands into the full suite of resourceful methods (index, create, store, etc.). If you choose `api`, it swaps blade redirects for Eloquent API resources. * **Column Typing**: Blueprint uses the exact same names as Laravel migration methods (e.g., `nullable`, `string`, `text`, `unsignedInteger`). * **Relationship Inferences**: If you name a column `user_id`, Blueprint automatically adds a `belongsTo(User::class)` method to your model. * **Passivity**: Blueprint is a passive generator. It creates new files but generally avoids destructive edits to your existing logic, though it will append routes to your `web.php` or `api.php` files. Practical Examples: Trace and Existing Apps A common misconception is that Blueprint is only for "Greenfield" projects. However, the `blueprint:trace` command allows it to work with existing codebases. Imagine you have an existing `User` model but need to build an admin interface for it. By running `php artisan blueprint:trace`, Blueprint analyzes your existing models and migrations. You can then reference those existing models in a new `draft.yaml` to generate new controllers or tests that are fully aware of your existing database schema. This is a massive time-saver for expanding mature applications. Tips & Gotchas * **The "Nah" Shortcut**: When prototyping, you may generate code you don't like. A common community alias is `alias nah='git clean -df && git checkout .'`, which quickly wipes uncommitted changes so you can tweak your `draft.yaml` and try again. * **Configuring for Pest**: If you prefer Pest over PHPUnit, publish the config via `php artisan vendor:publish --provider="Blueprint\BlueprintServiceProvider"` and swap the test generator class. * **Stub Customization**: You can publish Blueprint's "stubs" (template files). If your team has a specific way of writing controllers or models that differs from the Laravel default, you can modify the stubs so that Blueprint always generates code in your specific style. * **Formatting YAML**: YAML is sensitive to indentation. Ensure your models and controllers are correctly nested, or the parser will fail to associate attributes with the correct parent component.