Blast Laravel Package

Getting Started

Minimal Setup

1. Installation

   composer require blast-project/blast
   

   Ensure your composer.json includes "minimum-stability": "dev" if the package is pre-release.

2. Service Provider & Facade Register the package in config/app.php under providers:

   BlastProject\Blast\BlastServiceProvider::class,
   

   Publish the config (if available) with:

   php artisan vendor:publish --provider="BlastProject\Blast\BlastServiceProvider"
   

3. First Use Case Check the package’s basic functionality via the facade (if provided):

   use BlastProject\Blast\Facades\Blast;
   
   $response = Blast::query('your_search_term_here');
   dd($response); // Inspect the output structure
   

4. Configuration Review config/blast.php (if published) for API keys, endpoints, or default settings. Example:

   'api_key' => env('BLAST_API_KEY'),
   'endpoint' => env('BLAST_ENDPOINT', 'https://api.blast.example.com'),
   

Implementation Patterns

Core Workflows

1. Search Queries Use the facade or service container to execute searches:

   $results = Blast::search([
       'query' => 'laravel packages',
       'limit' => 10,
       'filters' => ['type' => 'open-source']
   ]);
   

   • Pagination: Handle paginated responses with Laravel’s Cursor or LengthAwarePaginator:

     $paginated = $results->paginate(20);
     

2. Data Transformation Chain methods to transform raw API responses:

   $formatted = Blast::get('resource_id')->map(function ($item) {
       return (object)[
           'title' => $item->name,
           'url' => route('details', $item->id)
       ];
   });
   

3. Event-Driven Extensions Listen for package events (if documented) to react to API responses:

   // In EventServiceProvider
   protected $listen = [
       'BlastProject\Blast\Events\SearchCompleted' => [
           'App\Listeners\LogBlastSearch',
       ],
   ];
   

4. Caching Strategies Cache frequent queries using Laravel’s cache:

   $cached = Cache::remember("blast_{$query}", now()->addHours(1), function () use ($query) {
       return Blast::search(['query' => $query]);
   });
   

Integration Tips

• API Rate Limiting: Implement a ThrottleRequests middleware for the package’s routes.
• Error Handling: Wrap calls in a try-catch to handle BlastException (if defined):

  try {
      $data = Blast::fetch('resource');
  } catch (\BlastProject\Blast\Exceptions\BlastException $e) {
      Log::error("Blast API failed: " . $e->getMessage());
      return response()->json(['error' => 'Service unavailable'], 503);
  }
  

• Testing: Mock the package’s HTTP client in PHPUnit:

  $mock = Mockery::mock('overload', Blast::class);
  $mock->shouldReceive('search')->andReturn($mockData);
  

Gotchas and Tips

Pitfalls

1. Undocumented API Changes

   • The package is labeled WIP. Assume breaking changes in minor updates. Pin versions in composer.json:

     "require": {
         "blast-project/blast": "1.0.0"
     }
     

2. Missing Facade/Service

   • If no facade exists, instantiate the service directly:

     $blast = app(\BlastProject\Blast\Services\BlastService::class);
     

3. Configuration Overrides

   • Environment variables may not be auto-loaded. Explicitly set them in .env:

     BLAST_API_KEY=your_key_here
     BLAST_DEBUG=true
     

4. No Built-in Retry Logic

   • Implement exponential backoff for transient failures:

     use Symfony\Component\HttpClient\RetryStrategy;
     
     $client = Blast::getClient()
         ->withOptions([
             'retry_strategy' => new RetryStrategy(),
         ]);
     

Debugging

• Enable Debug Mode Set BLAST_DEBUG=true in .env to log raw API responses to storage/logs/blast.log.

• Inspect HTTP Requests Use Laravel’s tap to debug the underlying HTTP client:

  Blast::search(['query' => 'test'])
       ->tap(function ($response) {
           \Log::debug('Raw response:', $response->original);
       });
  

Extension Points

1. Custom HTTP Client Bind a custom Guzzle client in AppServiceProvider:

   $this->app->singleton(\BlastProject\Blast\Contracts\BlastClient::class, function () {
       return new \BlastProject\Blast\Clients\GuzzleClient(
           new \GuzzleHttp\Client(['timeout' => 30])
       );
   });
   

2. Response Decorators Extend the BlastResponse class to add custom methods:

   namespace App\Extensions;
   
   use BlastProject\Blast\BlastResponse;
   
   class EnhancedBlastResponse extends BlastResponse
   {
       public function getHighlights()
       {
           return $this->data['highlights'] ?? [];
       }
   }
   

   Then rebind the class in AppServiceProvider.

3. Queueable Jobs Offload long-running searches to a queue:

   Blast::dispatch('complex_query')->onQueue('blast');
   

   (Requires implementing ShouldQueue in the package’s base class.)