Domainator9K Citype Jenkins Bundle Laravel Package

Getting Started

Minimal Setup

1. Installation Add the bundle to your composer.json:

   composer require district09/domainator9k-citype-jenkins-bundle
   

   Enable the bundle in config/bundles.php:

   return [
       // ...
       District09\Domainator9kCitypeJenkinsBundle\Domainator9kCitypeJenkinsBundle::class => ['all' => true],
   ];
   

2. Configuration Publish the default config (if needed) and update config/packages/domainator9k_citype_jenkins.yaml:

   php bin/console config:dump-reference District09\Domainator9kCitypeJenkinsBundle
   

   Example minimal config:

   domainator9k_citype_jenkins:
       jenkins_url: 'http://your-jenkins-server'
       api_token: '%env(JENKINS_API_TOKEN)%'
   

3. First Use Case: Trigger a Jenkins Job Inject the service and trigger a build:

   use District09\Domainator9kCitypeJenkinsBundle\Service\JenkinsService;
   
   class MyController extends AbstractController
   {
       public function __construct(private JenkinsService $jenkinsService) {}
   
       public function triggerBuild(): Response
       {
           $jobName = 'my-project';
           $this->jenkinsService->triggerJob($jobName);
           return new Response('Job triggered!');
       }
   }
   

Implementation Patterns

Common Workflows

1. Job Management

   • Trigger builds: Use triggerJob($jobName, $params = []) to start builds with parameters.
   • Poll job status: Use getJobStatus($jobName) to check build progress.
   • Fetch build logs: Use getBuildLog($jobName, $buildNumber) for debugging.

   $this->jenkinsService->triggerJob('deployment-pipeline', ['BRANCH' => 'main']);
   $status = $this->jenkinsService->getJobStatus('deployment-pipeline');
   

2. Parameterized Jobs Pass parameters as an associative array:

   $params = [
       'ENVIRONMENT' => 'staging',
       'DEPLOY_USER' => 'deploy-bot'
   ];
   $this->jenkinsService->triggerJob('deploy', $params);
   

3. Event Listeners Subscribe to Jenkins events (e.g., build completion) using Symfony’s event system:

   # config/services.yaml
   services:
       App\EventListener\JenkinsBuildListener:
           tags:
               - { name: kernel.event_listener, event: domainator9k.citype.jenkins.build_completed, method: onBuildCompleted }
   

4. Dependency Injection Prefer constructor injection for the JenkinsService to ensure testability:

   class MyService {
       public function __construct(private JenkinsService $jenkins) {}
   }
   

Integration Tips

1. Environment Variables Store sensitive data (e.g., JENKINS_API_TOKEN) in .env:

   JENKINS_API_TOKEN=your_token_here
   

2. Caching Responses Cache frequent API calls (e.g., job status) using Symfony’s cache system:

   $status = $this->jenkinsService->getJobStatus($jobName, 300); // Cache for 5 minutes
   

3. Error Handling Wrap Jenkins API calls in try-catch blocks to handle HTTP errors gracefully:

   try {
       $this->jenkinsService->triggerJob('failing-job');
   } catch (\RuntimeException $e) {
       $this->logger->error('Jenkins trigger failed: ' . $e->getMessage());
   }
   

4. Laravel-Specific Adaptations If using Laravel, bind the bundle’s services to the container in AppServiceProvider:

   public function register()
   {
       $this->app->bind(
           District09\Domainator9kCitypeJenkinsBundle\Service\JenkinsService::class,
           function ($app) {
               return new \District09\Domainator9kCitypeJenkinsBundle\Service\JenkinsService(
                   $app['config']['domainator9k_citype_jenkins.jenkins_url'],
                   $app['config']['domainator9k_citype_jenkins.api_token']
               );
           }
       );
   }
   

Gotchas and Tips

Pitfalls

1. Deprecated Symfony Version

   • The bundle was last updated in 2018 and may not support modern Symfony/Laravel versions (5.4+).
   • Workaround: Fork the repository and update dependencies (e.g., symfony/http-client, guzzlehttp/guzzle) to v6+.

2. No Official Laravel Support

   • The bundle is designed for Symfony. For Laravel, you’ll need to manually bind services or use a wrapper class.
   • Tip: Create a Laravel-specific facade or service to abstract the bundle’s logic.

3. API Token Security

   • Hardcoding tokens in config is risky. Always use environment variables or Symfony’s ParameterBag.
   • Example:

     # config/packages/domainator9k_citype_jenkins.yaml
     domainator9k_citype_jenkins:
         api_token: '%env(JENKINS_TOKEN)%'
     

4. Rate Limiting

   • Jenkins may throttle API requests. Implement exponential backoff in your service layer:

     use Symfony\Component\HttpClient\RetryableHttpClient;
     
     $client = new RetryableHttpClient(
         $baseClient,
         [
             'max_retries' => 3,
             'delay' => 1000, // 1 second
             'multiplier' => 2,
             'max_delay' => 60000, // 1 minute
         ]
     );
     

5. Job Name Sensitivity

   • Job names are case-sensitive. Verify names via the Jenkins UI or API before triggering builds.

Debugging Tips

1. Enable Debug Mode Set debug: true in the config to log raw API responses:

   domainator9k_citype_jenkins:
       debug: '%kernel.debug%'
   

2. Check HTTP Headers Use bin/console debug:config domainator9k_citype_jenkins to verify the Jenkins-User header is set correctly.

3. Mock Jenkins API for Tests Use a mock HTTP client in tests:

   use Symfony\Component\HttpClient\MockHttpClient;
   
   $mockClient = new MockHttpClient([
       new Response(200, [], json_encode(['queueId' => 123])),
   ]);
   $this->jenkinsService->setHttpClient($mockClient);
   

Extension Points

1. Custom Job Parameters Extend the JenkinsService to add domain-specific parameters:

   class CustomJenkinsService extends JenkinsService {
       public function triggerDeployment($branch, $environment) {
           $params = [
               'BRANCH' => $branch,
               'ENV' => strtoupper($environment),
           ];
           return $this->triggerJob('deploy', $params);
       }
   }
   

2. Webhook Integration Create a Symfony controller to handle Jenkins webhook callbacks:

   #[Route('/jenkins/webhook', name: 'jenkins_webhook', methods: ['POST'])]
   public function handleWebhook(Request $request): Response
   {
       $data = json_decode($request->getContent(), true);
       // Process webhook data (e.g., build status changes)
       return new Response('Webhook received');
   }
   

3. Event Dispatching Dispatch custom events for Jenkins actions (e.g., jenkins.job.triggered):

   use Symfony\Contracts\EventDispatcher\EventDispatcherInterface;
   
   $dispatcher->dispatch(new JenkinsJobTriggeredEvent($jobName, $params));