Companies House Bundle Laravel Package

Getting Started

Minimal Steps

1. Installation

   composer require capitalise/companies-house-bundle
   

   Add the bundle to config/bundles.php:

   return [
       // ...
       Capitalise\CompaniesHouseBundle\CompaniesHouseBundle::class => ['all' => true],
   ];
   

2. Configuration Publish the default config:

   php bin/console capitalise:companies-house:install
   

   Update .env with your Companies House API key:

   COMPANIES_HOUSE_API_KEY=your_api_key_here
   

3. First Use Case Fetch a company profile by number:

   use Capitalise\CompaniesHouseBundle\Service\CompaniesHouseService;
   
   class CompanyController extends AbstractController
   {
       public function show(CompaniesHouseService $service, string $companyNumber)
       {
           $company = $service->getCompanyProfile($companyNumber);
           return $this->json($company);
       }
   }
   

   Route it:

   # config/routes.yaml
   company_profile:
       path: /company/{number}
       controller: App\Controller\CompanyController::show
   

Implementation Patterns

Core Workflows

1. Company Data Retrieval

   • Basic Profile:

     $profile = $service->getCompanyProfile('09725555');
     

   • Filtered Search:

     $companies = $service->searchCompanies(['company_name' => 'Acme']);
     

2. API Rate Limiting Handle throttling gracefully:

   try {
       $data = $service->getCompanyAccounts('09725555');
   } catch (RateLimitExceededException $e) {
       $this->addFlash('error', 'API rate limit exceeded. Retry later.');
       return $this->redirectToRoute('home');
   }
   

3. Data Transformation Use DTOs or custom mappings:

   $mapper = new CompanyProfileMapper();
   $dto = $mapper->map($service->getCompanyProfile('09725555'));
   

Integration Tips

• Caching Responses Cache API responses for 5–10 minutes (respecting cache-control headers):

  $cacheKey = 'ch_'.$companyNumber;
  if (!$company = $this->cache->get($cacheKey)) {
      $company = $service->getCompanyProfile($companyNumber);
      $this->cache->set($cacheKey, $company, 600);
  }
  

• Event-Driven Updates Subscribe to CompaniesHouseEvents for real-time updates:

  $dispatcher->addListener(CompanyProfileUpdatedEvent::class, function ($event) {
      // Sync with your database or trigger notifications
  });
  

• Batch Processing Use getCompanyAccounts() with pagination:

  $accounts = $service->getCompanyAccounts('09725555', ['items_per_page' => 100]);
  

Gotchas and Tips

Pitfalls

1. API Key Management

   • Never hardcode the API key. Use .env and restrict access via Symfony’s env() function.
   • Rotate keys if exposed (monitor via Companies House API dashboard).

2. Rate Limits

   • Default limit: 1,000 requests/day. Exceeding this returns 429 Too Many Requests.
   • Solution: Implement exponential backoff or queue delayed requests:

     $service->setRateLimitHandler(new ExponentialBackoffHandler());
     

3. Data Freshness

   • Some endpoints (e.g., company-status) return stale data. Use as_at parameter for historical accuracy:

     $service->getCompanyProfile('09725555', ['as_at' => '2023-01-01']);
     

4. Error Handling

   • HTTP 404 may return null or throw NotFoundException. Normalize responses:

     $company = $service->getCompanyProfile($number) ?? throw new CompanyNotFoundException();
     

Debugging

• Enable API Logging Configure Monolog in config/packages/monolog.yaml:

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

• Validate Requests Use CompaniesHouseValidator to check API responses:

  $validator = new CompaniesHouseValidator();
  $errors = $validator->validateCompanyProfile($response);
  

Extension Points

1. Custom Endpoints Extend CompaniesHouseClient to add unsupported endpoints:

   class CustomCompaniesHouseClient extends CompaniesHouseClient
   {
       public function getCustomData(string $endpoint, array $params = [])
       {
           return $this->request('GET', $endpoint, $params);
       }
   }
   

2. Response Transformers Override CompaniesHouseResponseTransformer to modify payloads:

   $transformer = new CustomResponseTransformer();
   $service->setTransformer($transformer);
   

3. Mocking for Tests Use the CompaniesHouseMockClient in PHPUnit:

   $mockClient = new CompaniesHouseMockClient();
   $service = new CompaniesHouseService($mockClient);
   $service->getCompanyProfile('12345678'); // Returns mocked data
   

Configuration Quirks

• Base URL: Defaults to https://api.company-information.service.gov.uk. Override in config/packages/companies_house.yaml:

  companies_house:
      base_uri: 'https://api.test.company-information.service.gov.uk'
  

• Timeouts: Increase for slow responses:

  companies_house:
      timeout: 30 # seconds