Hazu Laravel Package

Getting Started

Minimal Setup

1. Installation Add the package via Composer:

   composer require cristianocorrea/hazu
   

   Publish the config file (if available) or check config/hazu.php for defaults.

2. Basic Usage The package provides a Hazu facade or service container binding (hazu). Initialize it with a simple configuration:

   use Hazu\Facades\Hazu;
   
   $hazu = Hazu::make('your_api_key');
   

3. First Use Case: Fetching Data Use the package to fetch data from an API (assuming it’s a wrapper for a service like a weather API, payment gateway, etc.):

   $response = $hazu->get('/endpoint');
   $data = json_decode($response->getBody(), true);
   

Implementation Patterns

Common Workflows

1. API Integration

   • Use the package as a thin wrapper around an external API. For example, if hazu is for a payment service:

     $payment = $hazu->charge($amount, $cardDetails);
     

2. Service Container Binding Bind the package to the Laravel container for dependency injection:

   $this->app->bind('hazu', function ($app) {
       return Hazu::make(config('services.hazu.key'));
   });
   

3. Middleware for API Requests Create middleware to attach the API key or other headers to requests:

   public function handle($request, Closure $next) {
       $request->headers->set('X-API-Key', config('services.hazu.key'));
       return $next($request);
   }
   

4. Laravel Service Providers Extend the package’s functionality in a service provider:

   public function register() {
       $this->app->singleton('hazu', function ($app) {
           return new Hazu(config('services.hazu.key'));
       });
   }
   

5. Queue Jobs for Async Operations Offload long-running API calls to queues:

   dispatch(new ProcessHazuPayment($amount, $cardDetails));
   

Gotchas and Tips

Pitfalls

1. Archived Package

   • The package is archived (last release in 2015) and has no stars/dependents. Use with caution—it may lack updates for Laravel’s latest versions or security patches.
   • Verify compatibility with your Laravel version (e.g., test with laravel/framework:^5.1 if the package targets older Laravel).

2. No Documentation

   • The package lacks official docs. Reverse-engineer usage from tests or examples in the repo (if any).
   • Check the src folder for method signatures or usage patterns.

3. Error Handling

   • The package may not include robust error handling. Wrap calls in try-catch blocks:

     try {
         $response = $hazu->get('/endpoint');
     } catch (\Exception $e) {
         Log::error("Hazu API error: " . $e->getMessage());
         return response()->json(['error' => 'Service unavailable'], 503);
     }
     

4. Configuration Quirks

   • If the package expects a config file, ensure config/hazu.php exists. Defaults may not be provided.
   • Override defaults in config/services.php:

     'hazu' => [
         'key' => env('HAZU_API_KEY'),
         'base_url' => env('HAZU_BASE_URL', 'https://api.example.com'),
     ],
     

5. Deprecated Laravel Features

   • The package may use deprecated Laravel helpers (e.g., Input::old() instead of $request->old()). Update calls to modern Laravel syntax.

Tips

1. Fallback to Raw HTTP If the package fails, fall back to Laravel’s HTTP client:

   $response = Http::withHeaders(['X-API-Key' => config('services.hazu.key')])
       ->get('https://api.example.com/endpoint');
   

2. Testing Mock the package in tests to avoid hitting external APIs:

   $this->mock(Hazu::class)->shouldReceive('get')->andReturn(response()->json(['test' => true]));
   

3. Extending Functionality Create a decorator class to add features:

   class ExtendedHazu {
       protected $hazu;
   
       public function __construct(Hazu $hazu) {
           $this->hazu = $hazu;
       }
   
       public function customMethod() {
           return $this->hazu->get('/custom-endpoint');
       }
   }
   

4. Logging Log API responses for debugging:

   $response = $hazu->get('/endpoint');
   Log::debug('Hazu response', ['data' => $response->getBody()]);
   

5. Fork and Maintain If the package is critical, fork it on GitHub and update it for modern Laravel. Contribute fixes upstream if possible.