Common Laravel Package

Getting Started

Minimal Steps

1. Installation Add the package via Composer (though note this is a legacy Guzzle 3 component—ensure compatibility with your Laravel version, ideally using Guzzle 6/7 instead):

   composer require guzzle/common:^3.0
   

   For Laravel 5.5+, prefer modern Guzzle HTTP client (guzzlehttp/guzzle).

2. First Use Case Use Guzzle\Common\Collection for grouping related data (e.g., API responses):

   use Guzzle\Common\Collection;
   
   $data = new Collection([
       'users' => ['Alice', 'Bob'],
       'roles' => ['admin', 'editor']
   ]);
   echo $data['users'][0]; // Output: "Alice"
   

3. Key Classes to Explore

   • Collection: Lightweight key-value storage.
   • EventDispatcher: For event-driven workflows (e.g., logging, caching).
   • Filter\*: Data filtering utilities (e.g., Filter\GreaterThan).

Implementation Patterns

Workflows

1. Data Aggregation Use Collection to merge API responses or form data:

   $formData = new Collection(request()->all());
   $merged = $formData->merge(['meta' => ['timestamp' => now()]]);
   
   // Laravel integration:
   return response()->json($merged->toArray());
   

2. Event-Driven Logic Attach listeners to Laravel events via EventDispatcher:

   $dispatcher = new \Guzzle\Common\EventDispatcher();
   $dispatcher->addListener('user.created', function ($event) {
       Log::info('User created: ' . $event['user']->name);
   });
   

3. Filtering Data Apply filters to Eloquent collections:

   use Guzzle\Common\Filter\GreaterThan;
   
   $users = User::all();
   $filtered = (new GreaterThan('age', 25))->filter($users->toArray());
   

Integration Tips

• Laravel Service Providers: Bind Collection as a singleton for global use:

  $this->app->singleton('collection', function () {
      return new \Guzzle\Common\Collection();
  });
  

• API Responses: Parse JSON responses into Collection for consistency:

  $response = Http::get('https://api.example.com/data');
  $data = new Collection(json_decode($response, true));
  

Gotchas and Tips

Pitfalls

1. Guzzle 3 Deprecation

   • This package is read-only and tied to Guzzle 3. Use Guzzle 6/7 (guzzlehttp/guzzle) for new projects.
   • Laravel 5.5+ ships with Guzzle 6 by default.

2. Collection vs. Laravel Collections

   • Guzzle\Common\Collection is not Laravel’s Illuminate\Support\Collection. Avoid mixing them without conversion:

     $laravelCollection = collect($guzzleCollection->toArray());
     

3. EventDispatcher Quirks

   • No built-in Laravel event integration. Manually wire listeners to Laravel’s event system:

     $dispatcher->addListener('eloquent.saved', function ($model) {
         event(new CustomEvent($model));
     });
     

Debugging

• Type Hints: The package lacks strict typing. Cast data explicitly:

  $value = (string) $collection['key'];
  

• Filter Validation: Validate filter inputs to avoid runtime errors:

  if (!is_numeric($age)) {
      throw new \InvalidArgumentException('Age must be numeric');
  }
  

Extension Points

1. Custom Filters Extend Guzzle\Common\Filter\AbstractFilter for domain-specific logic:

   class ActiveUserFilter extends AbstractFilter {
       public function filter($items) {
           return array_filter($items, fn($user) => $user['active']);
       }
   }
   

2. Event Subscribers Combine with Laravel’s event system for cross-cutting concerns:

   class GuzzleEventSubscriber implements ShouldRegister {
       public function handle() {
           $dispatcher = new \Guzzle\Common\EventDispatcher();
           $dispatcher->addListener('user.created', function () {
               // Sync with external service
           });
       }
   }