Taiga Bundle Laravel Package

Getting Started

Minimal Setup

1. Install the Bundle

   composer require troopers/taiga-bundle:^0.1
   

   Add to config/bundles.php (Symfony 4+) or AppKernel.php (Symfony 2/3):

   TaigaBundle\TaigaBundle::class => ['all' => true],
   

2. Configure API Token Add to .env:

   TAIGA_API_TOKEN=your_generated_token_here
   

   Reference in config/packages/taiga.yaml:

   taiga:
       api_token: '%env(TAIGA_API_TOKEN)%'
   

3. First Use Case: Fetch User Projects Inject the service in a controller or command:

   use TaigaBundle\Service\TaigaService;
   
   public function __construct(private TaigaService $taiga) {}
   
   public function index()
   {
       $projects = $this->taiga->projects->getList([
           'member' => $this->taiga->users->getMe()->id
       ]);
       // Render or process projects
   }
   

Implementation Patterns

Core Workflows

1. Project Management

   • Fetch Projects: Filter by user membership or tags.

     $projects = $taiga->projects->getList(['member' => $userId]);
     

   • Create Project: Use createProject() with required fields (name, description, etc.).
   • Update Project: Patch via updateProject($projectId, ['field' => 'value']).

2. Sprint (Milestone) Operations

   • List Sprints: Scope to a project.

     $sprints = $taiga->milestones->getList(['project' => $projectId]);
     

   • Create Sprint: Define start/end dates and project ID.
   • Assign User Stories: Link stories to sprints via updateUserStory().

3. User Story Handling

   • Bulk Fetch: Retrieve stories for a sprint.

     $stories = $taiga->userStories->getList(['milestone' => $sprintId]);
     

   • Update Status: Transition stories (e.g., "ready" → "in progress").

     $taiga->userStories->update($storyId, ['status' => 'inprogress']);
     

   • Add Comments: Attach notes to stories.

     $taiga->userStoryComments->create($storyId, ['text' => 'Review needed']);
     

4. Statistics & Analytics

   • Project Stats: Fetch issue counts (open/closed).

     $stats = $taiga->projects->getProjectIssueStats($projectId);
     

   • Sprint Metrics: Track progress via getMilestoneStats().

5. Event-Driven Integrations

   • Webhooks: Use Taiga’s webhook API (not bundled) to trigger Symfony events.
   • Cron Jobs: Sync Taiga data nightly (e.g., update local DB from sprints).

Integration Tips

• Dependency Injection: Prefer constructor injection for TaigaService in controllers/commands.
• Error Handling: Wrap API calls in try-catch for Taiga\Exceptions\ApiException.

  try {
      $taiga->userStories->create($projectId, $storyData);
  } catch (ApiException $e) {
      $this->addFlash('error', $e->getMessage());
  }
  

• Pagination: Handle large datasets with getList()’s page and per_page params.
• Caching: Cache frequent queries (e.g., project lists) with Symfony’s cache layer.

  $projects = $this->cache->get('taiga_projects_' . $userId, function() use ($taiga, $userId) {
      return $taiga->projects->getList(['member' => $userId]);
  });
  

Gotchas and Tips

Pitfalls

1. Token Permissions

   • Ensure the API token has read/write access to required resources (e.g., projects/sprints).
   • Debug: 403 Forbidden errors often indicate insufficient permissions.

2. Rate Limiting

   • Taiga enforces rate limits.
   • Fix: Implement exponential backoff for retries or cache aggressively.

3. Deprecated Methods

   • The bundle wraps taiga/php-sdk@0.1, which may have outdated endpoints.
   • Tip: Check Taiga’s API docs for breaking changes.

4. Symfony Version Mismatch

   • The bundle targets Symfony 2.7–3.0. For Symfony 4/5, ensure compatibility or fork.
   • Workaround: Use symfony/framework-bundle:^4.0 in composer.json if needed.

5. ID vs. UUID Handling

   • Taiga uses UUIDs for resources (e.g., projects). Ensure your DB/ORM matches this format.

Debugging

• Enable SDK Debugging Configure the SDK via bundle config:

  taiga:
      api_token: '%env(TAIGA_API_TOKEN)%'
      debug: true  # Logs requests/responses
  

• Inspect Raw Responses Access the underlying SDK client:

  $client = $this->taiga->getClient();
  $response = $client->get('/api/v1/projects');
  

• Common HTTP Errors

  Error	Cause	Solution
  404 Not Found	Invalid resource ID	Verify UUID format and existence
  400 Bad Request	Malformed payload	Validate data against API schema
  500 Server Error	Taiga backend issue	Check Taiga status page

Extension Points

1. Custom API Clients Extend the bundle to support additional Taiga endpoints:

   // src/Service/TaigaExtendedService.php
   class TaigaExtendedService extends TaigaService {
       public function getCustomEndpoint() {
           return $this->getClient()->get('/api/v1/custom');
       }
   }
   

   Register as a service in services.yaml:

   services:
       App\Service\TaigaExtendedService:
           parent: 'taiga.api'
   

2. Event Listeners Trigger Symfony events on Taiga actions (e.g., story creation):

   // src/EventListener/TaigaListener.php
   class TaigaListener {
       public function onUserStoryCreated(UserStoryEvent $event) {
           // Dispatch Symfony event or log
       }
   }
   

   Bind to the taiga.user_story.created event (if supported) or hook into the SDK directly.

3. Data Transformers Normalize Taiga responses for your domain:

   $project = $taiga->projects->get($projectId);
   $normalized = [
       'id' => $project->id,
       'name' => $project->name,
       'slug' => $project->slug,
       'stats' => $this->transformStats($project->stats),
   ];
   

4. Testing Mock the Taiga service in PHPUnit:

   $mockTaiga = $this->createMock(TaigaService::class);
   $mockTaiga->method('projects->getList')->willReturn([$mockProject]);
   $this->container->set('taiga.api', $mockTaiga);
   

Pro Tips

• Bulk Operations: Use Taiga’s bulk endpoints (e.g., updateUserStoriesBulk) for batch updates.
• Webhook Validation: Validate Taiga webhook payloads with Taiga\Webhook\Validator.
• Local Development: Use Taiga’s Docker setup for testing.
• Monitoring: Log Taiga API calls to track usage patterns (e.g., with Monolog).