Chatea Client Lib Laravel Package

Getting Started

Minimal Setup

1. Installation Add the package via Composer in your Laravel project:

   composer require antwebes/chatea-client-lib
   

   Ensure your composer.json includes the package under require.

2. Basic Initialization Import the client in your Laravel service or controller:

   use Antwebes\ChateaClientLib\Client;
   use Antwebes\ChateaClientLib\OAuth2;
   
   // Initialize OAuth2 (if needed)
   $oauth = new OAuth2([
       'client_id'     => env('CHATEA_CLIENT_ID'),
       'client_secret' => env('CHATEA_CLIENT_SECRET'),
       'redirect_uri'  => env('CHATEA_REDIRECT_URI'),
   ]);
   
   // Initialize the client
   $client = new Client($oauth);
   

3. First API Call (Example: Fetching Resources) Use URI templates to fetch data (e.g., users, messages):

   $users = $client->get('/users', [
       'limit' => 10,
       'offset' => 0,
   ]);
   

   The package supports resource iterators for paginated results.

Implementation Patterns

1. OAuth2 Workflow

• Authentication Flow: Redirect users to Chatea’s OAuth2 endpoint:

  $authUrl = $oauth->getAuthorizationUrl();
  return redirect()->to($authUrl);
  

  Handle the callback in Laravel’s routes:

  Route::get('/callback', function () {
      $token = $oauth->handleAuthorizationCallback(request()->query);
      session(['chatea_token' => $token]);
  });
  

• Token Storage: Store tokens in Laravel’s session, cache, or database (e.g., config('services.chatea.token')).

2. URI Templates

• Dynamic Endpoints: Use placeholders (e.g., {user_id}) for RESTful routes:

  $user = $client->get('/users/{user_id}', ['user_id' => 123]);
  

• Query Parameters: Pass as an associative array:

  $messages = $client->get('/messages', [
      'since' => Carbon::now()->subDays(7),
      'limit' => 50,
  ]);
  

3. Resource Iterators

• Paginated Data: Fetch all pages automatically:

  $iterator = $client->getIterator('/posts');
  foreach ($iterator as $post) {
      // Process each post
  }
  

  Customize pagination via options:

  $iterator = $client->getIterator('/posts', [
      'limit' => 20,
      'page'  => 1,
  ]);
  

4. Repository Pattern

• Laravel Integration: Create a service class to abstract API calls:

  class ChateaService {
      protected $client;
  
      public function __construct(Client $client) {
          $this->client = $client;
      }
  
      public function fetchUser($userId) {
          return $this->client->get('/users/{user_id}', ['user_id' => $userId]);
      }
  }
  

  Bind the service in Laravel’s AppServiceProvider:

  $this->app->bind(ChateaService::class, function ($app) {
      return new ChateaService(new Client($app->make(OAuth2::class)));
  });
  

5. Error Handling

• HTTP Exceptions: Wrap API calls in try-catch:

  try {
      $data = $client->get('/protected-data');
  } catch (\Antwebes\ChateaClientLib\Exception\ApiException $e) {
      Log::error("Chatea API Error: " . $e->getMessage());
      return response()->json(['error' => 'Failed to fetch data'], 500);
  }
  

Gotchas and Tips

1. Deprecation Warnings

• Outdated Package: The last release was in 2016. Verify API compatibility with Chatea’s current docs.
  • Workaround: Use a wrapper or fork the package if endpoints change.

2. OAuth2 Quirks

• Token Expiry: Tokens may expire. Implement a refresh mechanism:

  if ($oauth->isTokenExpired()) {
      $refreshedToken = $oauth->refreshToken(session('chatea_refresh_token'));
      session(['chatea_token' => $refreshedToken]);
  }
  

• Redirect URI: Ensure redirect_uri in OAuth2 config matches Chatea’s registered URI.

3. URI Template Pitfalls

• Reserved Characters: URL-encode dynamic values:

  $userId = urlencode(123); // If passed directly
  $client->get('/users/{user_id}', ['user_id' => $userId]);
  

• Case Sensitivity: Chatea’s API may be case-sensitive for endpoints (e.g., /Users vs /users).

4. Performance Tips

• Caching Responses: Cache frequent API calls in Laravel’s cache:

  $cacheKey = "chatea_users_{$userId}";
  $user = Cache::remember($cacheKey, now()->addHours(1), function () use ($client, $userId) {
      return $client->get('/users/{user_id}', ['user_id' => $userId]);
  });
  

• Batch Requests: Use getIterator for large datasets to avoid memory issues.

5. Debugging

• Enable Verbose Logging: Configure Guzzle’s logging (if used internally):

  $client->setDebug(true); // If the package exposes this method
  

• API Response Inspection: Dump raw responses for debugging:

  $response = $client->get('/debug-endpoint');
  dd($response->getBody());
  

6. Extension Points

• Custom Headers: Add headers globally:

  $client->setDefaultOption('headers', [
      'X-Custom-Header' => 'value',
  ]);
  

• Middleware: Attach middleware to modify requests/responses (if the package supports it).

7. Documentation

• Generate Docs Locally: Follow the README’s instruction to generate PHPDoc:

  mkdir docs
  phpdoc -d ./vendor/antwebes/chatea-client-lib/src -t docs/ --template responsive
  

  Note: Paths may need adjustment based on Composer’s vendor directory.