Tyr Component Laravel Package

Getting Started

Minimal Setup

1. Installation:

   composer require canaltp/tyr-component:~1.2
   

   Ensure your Laravel project uses Guzzle 5 (default) or Guzzle 3 (legacy).

2. Basic Initialization:

   use CanalTP\TyrComponent\TyrService;
   
   $tyrUrl = config('services.tyr.url'); // e.g., 'http://tyr.dev.canaltp.fr/v0/'
   $endpointId = config('services.tyr.endpoint_id'); // e.g., 2
   
   $tyrApi = new TyrService($tyrUrl, $endpointId);
   

3. First Use Case: Create a user via the API:

   $user = $tyrApi->createUser('user@example.com', 'johndoe');
   $response = $tyrApi->getLastResponse();
   $status = $response->getStatusCode(); // Check success (200/201)
   

Where to Look First

• TyrService.php: Core class with all API endpoints (e.g., createUser, updateUser).
• config/services.php: Store tyr.url and endpoint_id for Laravel config.
• Tests: Mock examples in the README for Guzzle testing.

Implementation Patterns

Dependency Injection (Laravel)

Register the service in a Service Provider for reusable access:

// app/Providers/AppServiceProvider.php
public function register()
{
    $this->app->singleton('tyr', function ($app) {
        return new TyrService(
            config('services.tyr.url'),
            config('services.tyr.endpoint_id')
        );
    });
}

Usage in Controllers:

use Illuminate\Support\Facades\App;

$tyrApi = App::make('tyr');
$user = $tyrApi->createUser('test@example.com', 'testuser');

Workflows

1. CRUD Operations:

   // Create
   $tyrApi->createUser('email', 'login');
   
   // Read (assuming a `getUser` method exists)
   $tyrApi->getUser($userId);
   
   // Update
   $tyrApi->updateUser($userId, ['email' => 'new@example.com']);
   
   // Delete (if supported)
   $tyrApi->deleteUser($userId);
   

2. Error Handling:

   try {
       $tyrApi->createUser('invalid-email');
   } catch (\GuzzleHttp\Exception\RequestException $e) {
       $response = $e->getResponse();
       $error = json_decode($response->getBody(), true);
       Log::error("Tyr API Error: " . $error['message']);
   }
   

3. Response Inspection:

   $response = $tyrApi->getLastResponse();
   if ($response->getStatusCode() !== 200) {
       throw new \RuntimeException("API request failed");
   }
   

Integration Tips

• Rate Limiting: Add middleware to track API calls (e.g., throttle:60,1).
• Logging: Log all API responses for debugging:

  $tyrApi->getLastResponse()->getBody()->rewind();
  Log::debug("Tyr API Response: " . $tyrApi->getLastResponse()->getBody());
  

• Testing: Use Laravel’s Mockery to stub Guzzle responses:

  $mock = Mockery::mock('overload:' . TyrService::class);
  $mock->shouldReceive('getLastResponse')->andReturn(new \GuzzleHttp\Psr7\Response(200));
  

Gotchas and Tips

Pitfalls

1. Guzzle Version Conflicts:

   • The package supports Guzzle 3 and 5, but Laravel 5.5+ defaults to Guzzle 6.
   • Fix: Explicitly require guzzlehttp/guzzle:^5.3 in composer.json or use the Guzzle3\TyrService class.

2. Deprecated Methods:

   • appName was removed in v1.1.0; ensure no legacy code references it.

3. No Official Laravel Integration:

   • No built-in facades or service providers. Manually bind the service (as shown above).

4. Outdated Releases:

   • Last update was 2017. Verify API compatibility with Tyr’s current endpoints.

Debugging

• Check Status Codes:

  $status = $tyrApi->getLastResponse()->getStatusCode();
  if ($status >= 400) {
      $body = json_decode($tyrApi->getLastResponse()->getBody(), true);
      throw new \RuntimeException("Tyr API Error: " . $body['error']);
  }
  

• Enable Guzzle Debugging:

  $client = new \GuzzleHttp\Client(['debug' => true]);
  $tyrApi->setClient($client);
  

Tips

1. Configuration: Store API credentials in .env:

   TYR_URL=http://tyr.dev.canaltp.fr/v0/
   TYR_ENDPOINT_ID=2
   

   Then access via config('services.tyr').

2. Extending the Package:

   • Override TyrService to add custom endpoints:

     class CustomTyrService extends TyrService {
         public function customEndpoint($data) {
             return $this->client->post($this->url . 'custom', ['json' => $data]);
         }
     }
     

3. Testing:

   • Use Laravel’s Http facade to mock API calls:

     $response = Http::fake([
         'tyr.dev.canaltp.fr/v0/*' => Http::response(['success' => true], 200),
     ]);
     

4. Performance:

   • Reuse the TyrService instance (singleton pattern) to avoid reinitializing Guzzle clients.

5. License Note:

   • The AGPL-3.0 license requires open-sourcing your project if modifications are distributed. Review compliance if extending heavily.