Php Sdk Laravel Package

Getting Started

Minimal Setup

1. Install via Composer (recommended):

   composer require taiga/php-sdk:^1.0
   

   • No additional dependencies required (PHP 5.5+ with curl/openssl enabled).

2. Basic Initialization:

   use Taiga\Taiga;
   
   $taiga = new Taiga\Taiga('https://your-taiga-instance.com/api/v1/', 'your-api-token');
   

3. First Use Case: Fetching Projects

   $projects = $taiga->projects->getAll();
   // Returns array of projects
   

Key Entry Points

• API Endpoints: The SDK wraps Taiga’s REST API v1.
• Namespace: Taiga\ (e.g., Taiga\Projects, Taiga\Issues).
• Authentication: Pass your API token to the constructor.

Implementation Patterns

Common Workflows

1. CRUD Operations:

   // Create an issue
   $issue = $taiga->issues->create([
       'subject' => 'Fix bug',
       'description' => '...',
       'project' => 1,
   ]);
   
   // Update an issue
   $taiga->issues->update($issue->id, ['status' => 'closed']);
   
   // Delete an issue
   $taiga->issues->delete($issue->id);
   

2. Pagination Handling:

   $issues = $taiga->issues->getAll(['page' => 1, 'per_page' => 20]);
   // Loop through results (SDK returns paginated arrays)
   

3. Query Parameters:

   // Filter issues by project and status
   $issues = $taiga->issues->getAll([
       'project' => 1,
       'status' => 'open',
       'order_by' => '-created_at',
   ]);
   

4. Webhooks (if supported):

   • Use the SDK to validate incoming webhook payloads against Taiga’s API responses.

Integration Tips

• Laravel Service Provider: Bind the SDK as a singleton for dependency injection:

  $this->app->singleton('taiga', function ($app) {
      return new Taiga\Taiga(config('taiga.api_url'), config('taiga.api_token'));
  });
  

• API Rate Limiting: Implement retry logic for 429 Too Many Requests (e.g., using Guzzle middleware).

• Testing: Mock the SDK’s HTTP client (e.g., Mockery) to test business logic without hitting Taiga’s API.

Gotchas and Tips

Pitfalls

1. Deprecated API:

   • The SDK targets Taiga API v1, which may not support newer Taiga features (e.g., v2 endpoints).
   • Workaround: Manually extend the SDK or use raw HTTP requests for unsupported endpoints.

2. No PSR-7/HTTP Client Abstraction:

   • The SDK uses PHP’s curl directly. For modern Laravel apps, wrap it in a Guzzle client for consistency:

     $client = new \GuzzleHttp\Client();
     $taiga = new Taiga\Taiga($client, 'https://api-url', 'token');
     

3. Error Handling:

   • The SDK throws generic exceptions. Catch and map them to Laravel’s HttpException or custom exceptions:

     try {
         $taiga->issues->get($id);
     } catch (\Taiga\Exception $e) {
         throw new \App\Exceptions\TaigaException($e->getMessage(), $e->getCode());
     }
     

4. Token Management:

   • Hardcoding tokens violates security best practices. Use Laravel’s .env:

     TAIGA_API_TOKEN=your_token_here
     

     $taiga = new Taiga\Taiga(config('taiga.api_url'), config('taiga.api_token'));
     

Debugging Tips

• Enable Verbose Logging:

  $taiga->setDebug(true); // Logs raw API requests/responses
  

• Check Response Codes:

  • Taiga returns 404 for missing resources. Validate IDs before operations:

    try {
        $taiga->issues->get($id);
    } catch (\Taiga\Exception $e) {
        if ($e->getCode() === 404) {
            // Handle missing issue
        }
    }
    

Extension Points

1. Custom Endpoints:

   • Extend the SDK by adding methods to Taiga\Taiga:

     class ExtendedTaiga extends Taiga\Taiga {
         public function customEndpoint($data) {
             return $this->request('POST', '/custom', $data);
         }
     }
     

2. Middleware:

   • Add request/response middleware (e.g., for auth headers or rate limiting) by overriding the request method.

3. Event Dispatching:

   • Trigger Laravel events after SDK operations (e.g., issue.created):

     $issue = $taiga->issues->create($data);
     event(new \App\Events\IssueCreated($issue));