Bloom Laravel Package

Getting Started

Minimal Steps to First Use

1. Installation:

   composer require emilijus/bloom
   php artisan vendor:publish --tag=bloom
   php artisan bloom:install
   

   • Follow the README to set up Laravel 10 with Breeze (Blade) and PHPUnit.

2. First CRUD Generation:

   php artisan bloom:make Post
   

   • This generates a Post model, migration, controller, views, and routes.
   • Navigate to /admin/posts to see the auto-generated CRUD interface.

3. Key Files to Explore:

   • app/Providers/BloomServiceProvider.php (configures Bloom’s admin routes).
   • config/bloom.php (customize default settings like table names, view paths).
   • resources/views/vendor/bloom/ (override default Blade templates).

Implementation Patterns

Core Workflows

1. Generating CRUD for a Model

php artisan bloom:make Post title:string,body:text,is_published:boolean

• Output: Model, migration, controller (PostController), views (create, edit, index, show), and routes (/admin/posts).
• Customization: Extend the generated controller or override views in resources/views/vendor/bloom/.

2. Admin Dashboard Integration

• Bloom auto-registers an admin panel at /admin (protected by middleware).
• Custom Admin Routes:

  // In routes/admin.php
  Bloom::resource('posts', PostController::class)->only(['index', 'store']);
  

3. Reusing Components

• Form Fields: Use @bloomFormField in Blade to render dynamic fields (e.g., @bloomFormField('title')).
• Tables: @bloomTable renders a paginated table with CRUD actions:

  @bloomTable(Post::class, ['title', 'is_published'])
  

4. API + Admin Duality

• Generate a separate API controller alongside the admin CRUD:

  php artisan bloom:make Post --api
  

• Outputs PostApiController with store, index, etc., methods (uses Laravel’s apiResource routes).

5. Testing

• Bloom includes PHPUnit helpers. Example test:

  public function test_create_post()
  {
      $response = $this->actingAsAdmin()->post('/admin/posts', [
          'title' => 'Test Post',
          'body'  => 'Content...',
      ]);
      $this->assertRedirect('/admin/posts');
  }
  

• Use $this->actingAsAdmin() trait (published by bloom:install).

Integration Tips

With Existing Projects

• Partial Adoption: Generate only models/controllers without the admin panel by skipping bloom:install and manually registering routes in routes/web.php:

  Route::prefix('admin')->middleware(['auth', 'admin'])->group(function () {
      Route::resource('posts', PostController::class);
  });
  

Custom Middleware

• Extend Bloom’s admin middleware (App\Http\Middleware\AdminMiddleware) to add logic (e.g., role checks):

  public function handle($request, Closure $next)
  {
      if (!auth()->user()->hasRole('superadmin')) {
          abort(403);
      }
      return $next($request);
  }
  

Database Seeders

• Bloom-generated models support seeding. Example:

  // database/seeders/PostsTableSeeder.php
  public function run()
  {
      Post::factory()->count(10)->create();
  }
  

  • Register in DatabaseSeeder.php:

    $this->call(PostsTableSeeder::class);
    

Localization

• Override default labels (e.g., "Create Post") in resources/lang/en/bloom.php:

  return [
      'posts' => [
          'create_title' => 'Add New Article',
      ],
  ];
  

Gotchas and Tips

Pitfalls

1. Breeze Dependency:

   • Bloom assumes Breeze for auth. If using another auth system (e.g., Jetstream), manually replicate the is_admin column and middleware.

2. View Overrides:

   • Overriding views requires exact path matching. For example, to customize the index view:

     resources/views/vendor/bloom/posts/index.blade.php
     

   • Mistake: Placing files in resources/views/bloom/ won’t work—use the vendor/bloom/ path.

3. Migration Conflicts:

   • If you manually modify migrations after generation, Bloom’s bloom:make may overwrite them. Use --no-migration to skip:

     php artisan bloom:make Post --no-migration
     

4. Route Caching:

   • After generating routes, clear the cache:

     php artisan route:clear
     

5. Testing Quirks:

   • The actingAsAdmin() helper requires the is_admin column. If missing, add it manually:

     php artisan bloom:install --update-user-table
     

Debugging Tips

1. Log Bloom Events:

   • Enable debug mode in config/bloom.php:

     'debug' => env('BLOOM_DEBUG', false),
     

   • Check logs in storage/logs/laravel.log for generation errors.

2. Check Generated Files:

   • Verify files exist in:
     • app/Models/Post.php
     • app/Http/Controllers/Admin/PostController.php
     • resources/views/vendor/bloom/posts/

3. Middleware Issues:

   • If /admin routes 403, ensure:
     • The admin middleware is registered in app/Http/Kernel.php.
     • The is_admin column exists in users table.

Extension Points

1. Custom Field Types:

   • Extend Bloom’s field renderers by publishing and modifying:

     php artisan vendor:publish --tag=bloom-views
     

   • Add logic in app/View/Composers/BloomComposer.php.

2. Dynamic Permissions:

   • Use Laravel’s gates/policies to restrict CRUD actions:

     // app/Policies/PostPolicy.php
     public function create(User $user)
     {
         return $user->is_admin;
     }
     

3. API Resources:

   • Convert Bloom’s API controllers to use Laravel’s ApiResource for custom responses:

     public function toArray($request, Post $post)
     {
         return [
             'id' => $post->id,
             'title' => Str::limit($post->title, 50),
         ];
     }
     

4. Multi-Tenant Support:

   • Override the resolveModel() method in PostController to scope queries by tenant:

     protected function resolveModel()
     {
         return Tenant::query()->model()->where('tenant_id', auth()->tenant()->id);
     }
     

5. Event Listeners:

   • Listen to Bloom’s model events (e.g., created, updated) in EventServiceProvider:

     protected $listen = [
         'eloquent.created: App\Models\Post' => [
             'App\Listeners\LogPostCreation',
         ],
     ];