Bitbucket Api Bundle Laravel Package

Getting Started

Minimal Setup

1. Install the Bundle Add to composer.json:

   composer require cocciagialla/bitbucket-api-bundle
   

   Enable in config/bundles.php:

   Cocciagialla\BitbucketApiBundle\BitbucketApiBundle::class => ['all' => true],
   

2. Configure OAuth2 Credentials Add to config/packages/bitbucket_api.yaml:

   bitbucket_api:
       client_id: '%env(BITBUCKET_CLIENT_ID)%'
       client_secret: '%env(BITBUCKET_CLIENT_SECRET)%'
   

   Store secrets in .env:

   BITBUCKET_CLIENT_ID=your_client_id
   BITBUCKET_CLIENT_SECRET=your_secret
   

3. First Use Case: Fetch Repository Data Inject the API client and call a method (e.g., list repositories):

   use Bitbucket\API\Api;
   
   public function listRepos(Api $bitbucketApi) {
       $repos = $bitbucketApi->repository()->get();
       return $this->json($repos);
   }
   

Implementation Patterns

Common Workflows

1. Authentication & Token Management

   • Use the bundle’s built-in OAuth2 flow for authentication.
   • Cache tokens in Symfony’s cache system (e.g., CacheInterface) for reuse:

     $token = $bitbucketApi->getAccessToken(); // Auto-refreshes if expired
     

2. Repository Operations

   • List Repositories:

     $repos = $bitbucketApi->repository()->get(['pagelen' => 10]);
     

   • Fetch Repository Details:

     $repo = $bitbucketApi->repository()->get('owner/repo-slug');
     

3. Pull Request Workflows

   • List PRs:

     $prs = $bitbucketApi->pullrequest()->get('owner/repo-slug');
     

   • Create PR:

     $newPr = $bitbucketApi->pullrequest()->create(
         'owner/repo-slug',
         ['title' => 'Fix bug', 'source' => 'branch-name']
     );
     

4. Webhooks & Events

   • Use the webhook service to verify and process incoming events:

     $payload = $request->getContent();
     $signature = $request->headers->get('X-Hub-Signature-256');
     $verified = $bitbucketApi->webhook()->verify($payload, $signature);
     

Integration Tips

• Symfony Events: Trigger events (e.g., bitbucket.api.event) after API calls for logging/auditing.
• Dependency Injection: Prefer autowiring (Api $bitbucketApi) over manual container access.
• Rate Limiting: Implement a decorator around Api to handle rate limits (Bitbucket’s default is 100 requests/10 minutes).

Gotchas and Tips

Pitfalls

1. Token Expiry Handling

   • The bundle auto-refreshes tokens, but ensure your client_id/secret are correct. Test with:

     try {
         $token = $bitbucketApi->getAccessToken();
     } catch (\Bitbucket\API\Exception\RuntimeException $e) {
         // Log or rethrow for OAuth issues
     }
     

2. Pagination Quirks

   • Paginated responses (e.g., /repositories) require manual iteration:

     $page = 1;
     do {
         $repos = $bitbucketApi->repository()->get(['page' => $page, 'pagelen' => 50]);
         $page++;
     } while (!empty($repos));
     

3. Webhook Verification

   • Always verify signatures in production:

     if (!$bitbucketApi->webhook()->verify($payload, $signature)) {
         throw new \RuntimeException('Invalid webhook signature');
     }
     

4. Deprecated Methods

   • The underlying bitbucket-api library may change. Check its docs for breaking changes.

Debugging Tips

• Enable API Debugging:

  # config/packages/bitbucket_api.yaml
  bitbucket_api:
      debug: true  # Logs raw API responses
  

• Mock the API for Tests: Use Symfony’s HttpClient mock or replace the Api service in tests:

  $container->set('Bitbucket\API\Api', $this->createMock(Api::class));
  

Extension Points

1. Custom API Clients

   • Extend the bundle’s Api service by creating a decorator:

     class CustomBitbucketApiDecorator implements ApiInterface {
         private $decorated;
     
         public function __construct(Api $decorated) {
             $this->decorated = $decorated;
         }
     
         public function repository() {
             // Add custom logic (e.g., logging)
             return $this->decorated->repository();
         }
     }
     

   • Register the decorator in services.yaml:

     services:
         App\Service\CustomBitbucketApiDecorator:
             decorates: 'Bitbucket\API\Api'
             arguments: ['@App\Service\CustomBitbucketApiDecorator.inner']
     

2. Event Listeners

   • Subscribe to API events (e.g., after a PR is created):

     // src/EventListener/BitbucketListener.php
     public static function getSubscribedEvents() {
         return [
             'bitbucket.api.event' => 'onBitbucketEvent',
         ];
     }