Tall Blueprint Addon Laravel Package

Getting Started

Minimal Setup

1. Installation:

   composer require tanthammar/tall-blueprint-addon
   php artisan vendor:publish --provider="TanThammar\BlueprintAddon\BlueprintAddonServiceProvider"
   

   • Publishes config (config/blueprint-addon.php) and migrations if needed.

2. First Use Case:

   php artisan blueprint:build
   

   • Generates a TALL-forms component for each model in app/Http/Livewire/Forms.
   • Outputs a draft YAML file in resources/blueprints/ (e.g., UserBlueprint.yaml).
   • Key files generated:
     • Livewire form component (e.g., UserForm.php).
     • Blueprint YAML (customizable via draft.yaml).
     • Tests (Livewire-specific, requires manual updates).

3. Where to Look First:

   • resources/blueprints/ → Edit draft.yaml to customize fields.
   • app/Http/Livewire/Forms/ → Review auto-generated form logic.
   • config/blueprint-addon.php → Configure global defaults (e.g., field types, exclusions).

Implementation Patterns

Workflow: Model → Blueprint → Livewire Form

1. Define Blueprint Fields: Edit draft.yaml to specify fields for your model (e.g., UserBlueprint.yaml):

   fields:
     - name: name
       type: text
       rules: required|max:255
     - name: email
       type: email
       rules: required|email
   

   • Supports all TALL-forms field types.
   • Use exclude_fields to omit columns (e.g., timestamps).

2. Generate & Customize:

   php artisan blueprint:build
   

   • Override auto-generated logic in UserForm.php (e.g., custom validation, actions).
   • Extend with custom Livewire components by injecting them into the form:

     public function mount()
     {
         $this->fields[] = new CustomField();
     }
     

3. Integration with Controllers:

   • Use the generated form in a Livewire component:

     public function render()
     {
         return view('livewire.user-form')->layout('layouts.app');
     }
     

   • Avoid duplication: Delete redundant store/update logic from controllers if copied from draft.yaml.

4. Splitting Create/Update Forms:

   • Extend the base form and override methods:

     class UserCreateForm extends UserForm
     {
         public function rules()
         {
             return ['password' => 'required|confirmed'];
         }
     }
     

Pro Tips

• Partial Generates: Regenerate only specific models:

  php artisan blueprint:build --model=User
  

• Custom Field Types: Create a service provider to register custom fields:

  BlueprintAddon::extend('custom_field', function () {
      return new CustomField();
  });
  

• Relationships: Use relationship fields in draft.yaml:

  fields:
    - name: posts
      type: relationship
      model: Post
      key: user_id
  

Gotchas and Tips

Pitfalls

1. Generated Code is a Draft:

   • Fields may not render correctly out-of-the-box. Always inspect the generated UserForm.php and adjust:
     • Field types (e.g., text → textarea for long content).
     • Validation rules (YAML rules are copied verbatim; test thoroughly).
   • Example fix: If a select field fails, ensure the options are properly defined in YAML:

     - name: status
       type: select
       options: ["active", "inactive", "pending"]
     

2. Test File Conflicts:

   • Auto-generated tests use controller assertions, not Livewire. Update them to:

     public function test_form_submission()
     {
         $this->actingAs(user())
              ->livewire(UserForm::class)
              ->fillForm(['name' => 'Test'])
              ->assertSetOnSubmit();
     }
     

   • Use php artisan blueprint:test to regenerate tests (if updated).

3. Code Duplication:

   • store/update logic in draft.yaml is duplicated in both controllers and Livewire.
   • Solution: Delete the logic from controllers and rely solely on the form’s submit() method.

4. YAML Parsing Quirks:

   • Boolean values must use true/false (not yes/no or 1/0).
   • Nested fields (e.g., hasMany) require explicit type: nested and proper relationship config.

5. Livewire Component Naming:

   • Forms are generated as ModelNameForm (e.g., UserForm). Avoid naming conflicts with existing components.

Debugging

• Field Not Rendering? Check:

  1. The field exists in the model’s $fillable.
  2. The YAML syntax is valid (use a validator like YAML Lint).
  3. The form’s rules() method includes the field.

• Validation Errors:

  • Ensure rules in YAML match Laravel’s validation syntax.
  • Override rules() in the form class if needed:

    public function rules()
    {
        return $this->validateOnly(['email' => 'required|unique:users']);
    }
    

• Relationship Fields:

  • If a relationship field fails, verify:
    • The model and key in YAML are correct.
    • The related model has a belongsTo/hasMany defined.

Extension Points

1. Custom Field Types: Register new field types in a service provider:

   BlueprintAddon::extend('custom_field', function ($field) {
       return new class($field) extends Field {
           public function render()
           {
               return view('livewire.fields.custom')->with($this);
           }
       };
   });
   

2. Blueprint Hooks: Override the blueprint builder in AppServiceProvider:

   public function boot()
   {
       BlueprintAddon::macro('customLogic', function ($blueprint) {
           $blueprint->fields[] = new CustomField();
       });
   }
   

3. Post-Generation Hooks: Use events to modify generated files:

   BlueprintAddon::listen('afterGenerate', function ($model, $form) {
       $form->appendFile(__DIR__.'/stubs/custom-method.stub');
   });
   

4. Excluding Models: Configure exclusions in config/blueprint-addon.php:

   'excluded_models' => [
       'PasswordReset',
       'FailedJob',
   ],
   

Performance

• Large Models: Exclude non-essential fields in draft.yaml to reduce form complexity.
• Caching: Regenerate blueprints only when models change (avoid running blueprint:build in production).