Blast Extras Laravel Package

Getting Started

First Steps

1. Installation Add the package via Composer:

   composer require blast-project/blast-extras
   

   Publish the config (if available) with:

   php artisan vendor:publish --provider="BlastProject\BlastExtras\BlastExtrasServiceProvider"
   

2. Key Features Overview

   • Blast Helpers: Utility functions for common Laravel tasks (e.g., blast()->helper('slugify')).
   • Blast Macros: Extend core Laravel classes (e.g., Collection, String) with custom methods.
   • Blast Facades: Convenience facades for package functionality (e.g., Blast::macro()).
   • Blast Commands: Artisan commands for package-specific tasks (e.g., blast:generate).

3. First Use Case Extend a Collection with a custom method:

   use BlastProject\BlastExtras\Facades\Blast;
   
   Blast::macro('Collection', 'chunkByKey', function ($key) {
       return $this->groupBy($key)->map(fn ($group) => $group->values());
   });
   
   // Usage:
   $chunks = collect([1, 2, 3])->chunkByKey('id'); // Hypothetical example
   

Implementation Patterns

Core Workflows

1. Macro Registration

   • Global Macros: Register once in a service provider’s boot() method:

     public function boot()
     {
         Blast::macro('String', 'toKebabCase', fn ($string) => Str::of($string)->kebab());
     }
     

   • Contextual Macros: Register dynamically in controllers/middleware:

     Blast::macro('Collection', 'filterByUser', function ($userId) {
         return $this->where('user_id', $userId);
     });
     

2. Helper Utilization

   • Direct Calls:

     $slug = blast()->helper('slugify', 'Hello World'); // Returns 'hello-world'
     

   • Facade Shortcut:

     $slug = Blast::helper('slugify', 'Hello World');
     

3. Artisan Integration

   • Generate boilerplate (e.g., API resources, migrations):

     php artisan blast:generate resource Post --api
     

4. Testing Macros

   • Mock macros in tests:

     Blast::macro('Collection', 'testMacro', fn () => collect(['mocked']));
     $this->assertEquals(['mocked'], collect([])->testMacro());
     

Integration Tips

• Avoid Overloading: Limit macros to domain-specific logic (e.g., UserCollection::scopedByRole()).
• Namespace Conflicts: Prefix macros with your app’s namespace (e.g., App\Macros\chunkByKey).
• Performance: Cache macro results if computationally expensive:

  Blast::macro('Collection', 'expensiveCalc', function () {
      return cache()->remember("expensive_{$this->id}", now()->addHours(1), fn () => $this->sum('price'));
  });
  

Gotchas and Tips

Pitfalls

1. Macro Overwriting

   • Macros registered later overwrite earlier ones. Use hasMacro() to check:

     if (!collect([])->hasMacro('chunkByKey')) {
         Blast::macro('Collection', 'chunkByKey', ...);
     }
     

2. Facade vs. Helper Ambiguity

   • Prefer Blast::helper() over blast()->helper() for clarity in static analysis tools.

3. Artisan Command Collisions

   • Check for conflicting command names (e.g., blast:make vs. make:blast). Use --command flag:

     php artisan blast:generate --command=blast:make
     

4. GPL-3.0 License Implications

   • Ensure your project’s license is compatible (GPL-3.0 is copyleft). Document dependencies clearly.

Debugging

• Macro Introspection:

  dd(collect([])->getMacro('chunkByKey')); // Inspect registered macros
  

• Helper Tracing:

  blast()->debugHelpers(); // Logs all available helpers (if implemented)
  

Extension Points

1. Custom Helpers

   • Add helpers via the config (config/blast-extras.php):

     'helpers' => [
         'customHelper' => function ($input) {
             return strtoupper($input);
         },
     ],
     

   • Or dynamically:

     Blast::addHelper('customHelper', fn ($input) => strtoupper($input));
     

2. Macro Namespacing

   • Group macros by class type for organization:

     Blast::macro('App\Models\User', 'isAdmin', fn () => $this->role === 'admin');
     

3. Event Listeners

   • Hook into package events (if supported) via Events::listen() in a service provider.

4. Testing Utilities

   • Use Blast::flushMacros() to reset macros between tests:

     public function tearDown(): void
     {
         Blast::flushMacros();
         parent::tearDown();
     }