Sape Php Client Laravel Package

Getting Started

Minimal Setup

1. Installation

   composer require anh/sape-php-client
   

   Add the service provider to config/app.php:

   'providers' => [
       Anh\SapeClient\SapeServiceProvider::class,
   ],
   

2. Configuration Publish the config file:

   php artisan vendor:publish --provider="Anh\SapeClient\SapeServiceProvider"
   

   Update .env with your SAPE API credentials:

   SAPE_API_KEY=your_api_key_here
   SAPE_API_SECRET=your_api_secret_here
   

3. First Use Case: Fetching a User

   use Anh\SapeClient\Facades\Sape;
   
   $user = Sape::user()->get(123);
   dd($user);
   

Implementation Patterns

Common Workflows

1. CRUD Operations

   // Create
   $user = Sape::user()->create(['name' => 'John Doe', 'email' => 'john@example.com']);
   
   // Read
   $users = Sape::user()->all();
   
   // Update
   $updated = Sape::user()->update(123, ['email' => 'new@example.com']);
   
   // Delete
   Sape::user()->delete(123);
   

2. API Resource Handling Use the resource() method to interact with custom endpoints:

   $orders = Sape::resource('orders')->all();
   

3. Pagination

   $users = Sape::user()->paginate(10);
   

4. Query Parameters

   $users = Sape::user()->get(['active' => true, 'role' => 'admin']);
   

Integration Tips

• Laravel Eloquent Integration Extend the package to work with Eloquent models:

  class User extends Model {
      public static function fetchFromSape($id) {
          return Sape::user()->get($id);
      }
  }
  

• Middleware for API Calls Create middleware to handle API rate limits or authentication:

  namespace App\Http\Middleware;
  
  use Anh\SapeClient\Facades\Sape;
  use Closure;
  
  class SapeAuthMiddleware {
      public function handle($request, Closure $next) {
          Sape::setApiKey(config('sape.api_key'));
          return $next($request);
      }
  }
  

Gotchas and Tips

Pitfalls

1. Authentication Errors Ensure .env credentials are correct. Test with:

   Sape::auth()->validate();
   

2. Rate Limiting The package may not handle rate limits automatically. Implement retry logic:

   use Anh\SapeClient\Exceptions\RateLimitExceeded;
   
   try {
       $data = Sape::user()->get(123);
   } catch (RateLimitExceeded $e) {
       sleep(60); // Wait and retry
       $data = Sape::user()->get(123);
   }
   

3. Endpoint Mismatches Verify endpoint names in the config (config/sape.php) match the API’s actual endpoints.

Debugging

• Enable Debug Mode

  Sape::setDebug(true); // Logs all API requests/responses
  

• Check Raw Responses

  $response = Sape::user()->get(123, [], true); // Returns raw response
  

Extension Points

1. Custom Requests Extend the Anh\SapeClient\Requests\Request class to add custom logic:

   namespace App\Sape;
   
   use Anh\SapeClient\Requests\Request;
   
   class CustomRequest extends Request {
       public function getHeaders() {
           return array_merge(parent::getHeaders(), ['X-Custom-Header' => 'value']);
       }
   }
   

2. Override API Base URL Dynamically change the base URL:

   Sape::setBaseUrl('https://custom-api.sape.com');
   

3. Add New Resources Register new resources in the service provider’s boot() method:

   Sape::extend('custom_resource', function () {
       return new CustomResource();
   });