Supports Laravel Package

Getting Started

Minimal Steps to First Use

1. Installation:

   composer require yansongda/supports
   

   Ensure your project uses PHP 8.0+ and Guzzle 7.x (Laravel 9+ compatible).

2. First Use Case: HTTP Request Handling Use the HasHttpRequest trait to simplify Guzzle HTTP calls in a service or controller:

   use Yansongda\Supports\Traits\HasHttpRequest;
   
   class MyService {
       use HasHttpRequest;
   
       public function fetchData() {
           return $this->get('https://api.example.com/data', [
               'timeout' => 10,
               'connectTimeout' => 5,
           ]);
       }
   }
   

   Note: The trait uses Guzzle under the hood. Ensure your Laravel app’s config/http.php aligns with these settings.

3. First Use Case: Array/Config Utilities Leverage array manipulation methods (e.g., array_get, array_set):

   use Yansongda\Supports\Helpers\Arr;
   
   $config = [
       'settings' => [
           'theme' => 'dark',
       ],
   ];
   
   $theme = Arr::get($config, 'settings.theme'); // Returns 'dark'
   Arr::set($config, 'settings.theme', 'light'); // Modifies array
   

4. Pipeline Integration (Advanced) Use the package’s pipeline support for workflows (e.g., request processing):

   use Yansongda\Supports\Pipeline;
   
   $result = Pipeline::send($request)
       ->through([
           function ($request) { return $request->validate(); },
           function ($request) { return $this->logRequest($request); },
       ])
       ->then(function ($request) { return $this->process($request); });
   

Implementation Patterns

Core Workflows

1. HTTP Request Standardization

• Pattern: Replace ad-hoc Guzzle calls with the HasHttpRequest trait to enforce consistent timeouts, retries, and headers.
• Example:

  class ApiClient {
      use HasHttpRequest;
  
      public function __construct() {
          $this->client = $this->client()->withOptions([
              'timeout'  => 30,
              'retries'  => 3,
              'headers'  => ['Accept' => 'application/json'],
          ]);
      }
  
      public function getUser($id) {
          return $this->get("/users/{$id}");
      }
  }
  

• Integration Tip: Bind the ApiClient to Laravel’s container in AppServiceProvider for dependency injection.

2. Config/Array Manipulation

• Pattern: Use Arr helper for deep array operations (e.g., nested config validation, dynamic defaults).
• Example:

  use Yansongda\Supports\Helpers\Arr;
  
  // Merge configs with defaults
  $merged = Arr::merge([
      'defaults' => ['timeout' => 30],
  ], $userConfig);
  
  // Get nested value with fallback
  $timeout = Arr::get($merged, 'settings.timeout', 10);
  

• Integration Tip: Extend Laravel’s Arr facade to include these methods if needed:

  Facade::register('Arr', \Yansongda\Supports\Helpers\Arr::class);
  

3. Pipeline-Based Workflows

• Pattern: Chain operations (e.g., validation, logging, transformation) using the package’s Pipeline class.
• Example:

  use Yansongda\Supports\Pipeline;
  
  $result = Pipeline::send($data)
      ->through([
          function ($data) { return $this->validateData($data); },
          function ($data) { return $this->sanitizeData($data); },
      ])
      ->then(function ($data) { return $this->storeData($data); });
  

• Integration Tip: Wrap Laravel’s Pipeline facade to include package-specific pipes if needed.

4. Trait Composition

• Pattern: Combine traits in services to avoid repetitive code (e.g., HTTP + array utilities).
• Example:

  class DataProcessor {
      use HasHttpRequest, \Yansongda\Supports\Traits\Arrayable;
  
      public function process() {
          $rawData = $this->get('https://api.example.com/data');
          return $this->arrayFlatten($rawData['nested']['structure']);
      }
  }
  

Laravel-Specific Patterns

Service Provider Integration

• Register traits or helpers globally:

  // app/Providers/AppServiceProvider.php
  public function boot() {
      // Bind HasHttpRequest to a container alias
      $this->app->bind('apiClient', function () {
          $client = new class { use HasHttpRequest; };
          return $client;
      });
  }
  

Form Requests

• Use HasHttpRequest to fetch external data during validation:

  use Yansongda\Supports\Traits\HasHttpRequest;
  
  class StoreUserRequest extends FormRequest {
      use HasHttpRequest;
  
      public function rules() {
          $userExists = $this->get("https://api.example.com/users/{$this->user_id}");
          return [
              'email' => ['required', 'unique:users,email,' . ($userExists ? $this->user_id : null)],
          ];
      }
  }
  

Middleware Pipelines

• Extend Laravel’s middleware with package pipelines for complex logic:

  class ProcessDataMiddleware {
      public function handle($request, Closure $next) {
          return Pipeline::send($request)
              ->through([
                  [$this, 'validateRequest'],
                  [$this, 'logRequest'],
              ])
              ->then($next);
      }
  }
  

Gotchas and Tips

Pitfalls

1. Logger Removal in v3.0.0

• Issue: The package removed its logger classes, which may break existing code relying on Yansongda\Supports\Logger.
• Fix: Replace with Laravel’s Log facade:

  // Before (broken)
  Logger::info('Message');
  
  // After
  \Log::info('Message');
  

2. Guzzle Version Mismatch

• Issue: The package requires Guzzle 7.x, which may conflict with Laravel 8.x (Guzzle 6.x).
• Fix: Downgrade Guzzle or use a facade wrapper:

  // config/app.php
  'aliases' => [
      'GuzzleHttp' => \GuzzleHttp\Client::class,
  ],
  

3. Trait Method Conflicts

• Issue: Method names in traits (e.g., get, set) may collide with Laravel classes (e.g., Illuminate\Database\Eloquent\Model).
• Fix: Rename traits or use fully qualified method calls:

  // Avoid
  $this->get('key');
  
  // Use
  \Yansongda\Supports\Helpers\Arr::get($array, 'key');
  

4. Pipeline Inconsistencies

• Issue: The package’s Pipeline may not fully align with Laravel’s Illuminate\Pipeline\Pipeline.
• Fix: Stick to Laravel’s pipeline for critical workflows or wrap the package’s pipeline:

  use Illuminate\Support\Facades\Pipeline as LaravelPipeline;
  
  $result = LaravelPipeline::send($data)
      ->through([...])
      ->via(YansongdaPipelineAdapter::class)
      ->then(...);
  

5. Stale Maintenance

• Issue: No updates since 2020 may hide bugs or compatibility issues.
• Fix: Fork the repo or monitor for forks (e.g., spatie/array as an alternative).

Debugging Tips

1. Trait Method Overrides

• Override trait methods in your class to debug or extend behavior:

  class MyService {
      use HasHttpRequest;
  
      public function get($uri, $options = []) {
          \Log::debug('HTTP GET called with URI: ' . $uri);
          return parent::get($uri, $options);
      }
  }
  

2. Guzzle Client Inspection

• Inspect the underlying Guzzle client configuration:

  $client = (new class { use HasHttpRequest; })->client();
  \Log::debug('Guzzle config:', $client->getConfig());
  

3. Array Helper Debugging

• Use dd() to inspect array structures:

  $value = Arr::get($config, 'nested.key');
  dd($value, Arr::all($config)); // Debug full array
  

Configuration Quirks

1. connectTimeout Naming

• The package uses connectTimeout (camelCase), while Guzzle may expect connect_timeout