Tracker Symfony Bundle Laravel Package

Getting Started

Minimal Setup

1. Install the Bundle

   composer require comindware/tracker-symfony-bundle
   

   Enable the bundle in config/bundles.php:

   Comindware\TrackerBundle\ComindwareTrackerBundle::class => ['all' => true],
   

2. Configure the Bundle Add your Comindware Tracker credentials to config/packages/comindware_tracker.yaml:

   comindware_tracker:
       api_url: 'https://your-tracker-instance.com/api'
       api_key: '%env(COMINDWARE_TRACKER_API_KEY)%'
       default_project_id: 123
   

3. First Use Case: Logging a Task Inject the TrackerClient service and log a task:

   use Comindware\TrackerBundle\Client\TrackerClientInterface;
   
   class MyController
   {
       public function __construct(private TrackerClientInterface $trackerClient) {}
   
       public function logTask()
       {
           $task = $this->trackerClient->createTask(
               projectId: 123,
               title: 'Fix login bug',
               description: 'Users report issues with authentication.'
           );
           // Handle response (e.g., redirect or return JSON)
       }
   }
   

4. Key Documentation

   • English: src/Resources/doc/index.en.md
   • Russian: src/Resources/doc/index.ru.md

Implementation Patterns

Core Workflows

1. Task Management

   • Create/Update Tasks:

     $this->trackerClient->createTask($projectId, $title, $description, $priority);
     $this->trackerClient->updateTask($taskId, ['status' => 'In Progress']);
     

   • Fetch Tasks:

     $tasks = $this->trackerClient->getTasks($projectId, ['limit' => 10]);
     

2. Integration with Symfony Events Use the bundle’s events to trigger actions (e.g., log tasks on form submission):

   // config/services.yaml
   services:
       App\EventListener\TaskLogger:
           tags:
               - { name: kernel.event_listener, event: app.form_submitted, method: logTask }
   

3. Dependency Injection Prefer dependency injection over direct instantiation. The bundle provides:

   • TrackerClientInterface (primary client)
   • TrackerTaskManager (task-specific operations)
   • TrackerProjectManager (project operations)

4. Batch Operations Use the batch() method for bulk actions:

   $this->trackerClient->batch([
       'createTask' => ['projectId' => 123, 'title' => 'Task 1'],
       'createTask' => ['projectId' 123, 'title' => 'Task 2'],
   ]);
   

Common Use Cases

Gotchas and Tips

Pitfalls

1. API Rate Limits

   • The bundle doesn’t handle rate limiting by default. Implement retry logic for 429 responses:

     try {
         $this->trackerClient->createTask(...);
     } catch (RateLimitExceededException $e) {
         sleep($e->getRetryAfter());
         retry();
     }
     

2. Project ID Validation

   • Always validate projectId exists before operations. Use:

     $project = $this->trackerClient->getProject($projectId);
     if (!$project) throw new \InvalidArgumentException("Project not found");
     

3. Field Mapping Quirks

   • Custom fields in Tracker may not map directly to Symfony entities. Use TrackerClient::mapFields():

     $mappedTask = $this->trackerClient->mapFields($rawTask, [
         'custom_field' => 'entity_property',
     ]);
     

4. Authentication Issues

   • If API calls fail, verify:
     • api_key in config matches Tracker’s API token.
     • api_url includes /api (e.g., https://tracker.com/api/).
     • CORS headers if calling from a frontend.

Debugging Tips

1. Enable Verbose Logging Add to config/packages/monolog.yaml:

   handlers:
       tracker:
           type: stream
           path: "%kernel.logs_dir%/tracker.log"
           level: debug
           channels: ["comindware_tracker"]
   

2. Inspect Raw Responses Use the TrackerClient’s debug mode:

   $this->trackerClient->setDebug(true);
   $response = $this->trackerClient->getTasks(...);
   // Check $response->getDebugInfo() for raw data
   

3. Common HTTP Errors

   Error Code	Cause	Solution
   401	Invalid API key	Regenerate key in Tracker
   403	Insufficient permissions	Check user role in Tracker
   404	Resource not found	Validate IDs/paths
   500	Server error	Check Tracker server logs

Extension Points

1. Custom DTOs Extend Comindware\TrackerBundle\Model\TaskDto to add project-specific fields:

   class CustomTaskDto extends TaskDto
   {
       public ?string $customField = null;
   
       public function toArray(): array
       {
           return array_merge(parent::toArray(), [
               'custom_field' => $this->customField,
           ]);
       }
   }
   

2. Event Subscribers Listen to tracker.task.created or tracker.task.updated:

   class TaskSubscriber implements EventSubscriberInterface
   {
       public static function getSubscribedEvents(): array
       {
           return [
               TrackerEvents::TASK_CREATED => 'onTaskCreated',
           ];
       }
   
       public function onTaskCreated(TaskEvent $event): void
       {
           // Custom logic (e.g., notify Slack)
       }
   }
   

3. Override HTTP Client Replace the default Guzzle client by binding your own:

   # config/services.yaml
   services:
       Comindware\TrackerBundle\Client\TrackerClient:
           arguments:
               $httpClient: '@your_custom_http_client'
   

4. Localization Override translations in translations/messages.en.yaml:

   comindware_tracker:
       task:
           created: "Task '{title}' was successfully created!"