Fcaregisterlaravel Laravel Package

Getting Started

Minimal Setup

1. Installation

   composer require cyborgfinance/fcaregisterlaravel
   

   Publish the config file:

   php artisan vendor:publish --provider="CyborgFinance\FCARegisterLaravel\FCARegisterLaravelServiceProvider" --tag="config"
   

2. Configuration Edit .env with your FCA API credentials:

   FCA_REGISTER_API_KEY=your_api_key_here
   FCA_REGISTER_BASE_URL=https://api.fca.org.uk
   

3. First Use Case Fetch a firm by its FCA reference number (e.g., FRN=123456):

   use CyborgFinance\FCARegisterLaravel\Facades\FCARegister;
   
   $firm = FCARegister::firm('FRN=123456');
   dd($firm->name, $firm->registrationNumber);
   

Key Entry Points

• Facade: FCARegister (easiest for quick queries).
• Service Class: \CyborgFinance\FCARegisterLaravel\Services\FCARegisterService (for custom logic).
• Models: Firm, Individual, Product (auto-populated from API responses).

Implementation Patterns

Common Workflows

1. Searching Firms Use the search() method with filters (e.g., status=active, firmType=bank):

   $results = FCARegister::search([
       'status' => 'active',
       'firmType' => 'bank',
       'limit' => 10,
   ]);
   

2. Bulk Data Fetching Loop through paginated results:

   $page = 1;
   while (true) {
       $firms = FCARegister::search(['limit' => 100, 'page' => $page]);
       if ($firms->isEmpty()) break;
   
       foreach ($firms as $firm) {
           // Process firm (e.g., store in DB)
       }
       $page++;
   }
   

3. Caching Responses Leverage Laravel’s cache to avoid rate-limiting:

   $firm = FCARegister::firm('FRN=123456', cache: true, ttl: 3600);
   

4. Event-Driven Updates Use Laravel’s queue:work to fetch updates periodically:

   // In a scheduled job or command
   FCARegister::updateFirmCache('FRN=123456');
   

5. Custom Endpoints Extend the service for unsupported endpoints:

   $client = FCARegister::getClient();
   $response = $client->get('/firm-browse', [
       'query' => ['status' => 'active'],
   ]);
   

Integration Tips

• Database Sync: Use Eloquent models to sync FCA data to your DB:

  $firmData = FCARegister::firm('FRN=123456')->toArray();
  Firm::updateOrCreate(['fcaReference' => 'FRN=123456'], $firmData);
  

• API Rate Limits: Monitor X-RateLimit-* headers; implement exponential backoff for retries.
• Error Handling: Wrap calls in try-catch for FCAException:

  try {
      $firm = FCARegister::firm('FRN=invalid');
  } catch (\CyborgFinance\FCARegisterLaravel\Exceptions\FCAException $e) {
      Log::error("FCA API Error: " . $e->getMessage());
  }
  

Gotchas and Tips

Pitfalls

1. API Key Leaks

   • Never commit .env or hardcode keys. Use Laravel’s env() or a secure secrets manager.
   • Fix: Validate keys in config/fcaregister.php:

     'validate_key' => env('FCA_REGISTER_VALIDATE_KEY', false),
     

2. Rate Limiting

   • The FCA API enforces strict rate limits (e.g., 100 requests/minute).
   • Fix: Implement caching (as shown above) and log rate-limit headers:

     $response = FCARegister::getClient()->get('/firm', ['query' => [...]]);
     Log::debug('RateLimit-Remaining: ' . $response->getHeaderLine('X-RateLimit-Remaining'));
     

3. Deprecated Endpoints

   • The FCA API is in "early stages"; some endpoints may change.
   • Fix: Check the FCA API documentation for updates and extend the package if needed.

4. Data Mismatches

   • FCA data may not align with your schema (e.g., nested arrays vs. flat DB columns).
   • Fix: Use FCARegister::firm()->toArray() to inspect raw data before mapping.

5. Timeouts

   • Slow responses may time out during bulk operations.
   • Fix: Increase Laravel’s HTTP timeout in config/fcaregister.php:

     'timeout' => 30, // seconds
     

Debugging Tips

• Enable Debug Mode:

  FCARegister::setDebug(true); // Logs raw API responses
  

• Inspect Headers:

  $response = FCARegister::getClient()->get('/firm');
  dd($response->getHeaders());
  

• Mock API Calls (for testing): Use Laravel’s HTTP client mocking:

  $this->mock(\CyborgFinance\FCARegisterLaravel\Services\FCARegisterService::class)
       ->shouldReceive('getFirm')
       ->andReturn(new Firm(['name' => 'Test Firm']));
  

Extension Points

1. Custom Models Extend the base models to add business logic:

   namespace App\Models;
   
   use CyborgFinance\FCARegisterLaravel\Models\Firm as BaseFirm;
   
   class Firm extends BaseFirm {
       public function isAuthorised() {
           return $this->status === 'authorised';
       }
   }
   

2. New Endpoints Add support for unsupported endpoints by extending the service:

   namespace App\Services;
   
   use CyborgFinance\FCARegisterLaravel\Services\FCARegisterService;
   
   class ExtendedFCARegisterService extends FCARegisterService {
       public function getProducts() {
           return $this->get('/product', []);
       }
   }
   

3. Webhooks Poll for updates and trigger webhooks when data changes:

   $lastUpdated = Firm::where('fcaReference', 'FRN=123456')->value('lastUpdated');
   $firm = FCARegister::firm('FRN=123456');
   
   if ($firm->lastUpdated !== $lastUpdated) {
       event(new FirmUpdated($firm));
   }
   

Config Quirks

• Base URL: Ensure FCA_REGISTER_BASE_URL matches the FCA’s production/sandbox environment.
• Query Parameters: The package uses FRN=, status=, etc. Check the FCA API docs for exact parameter names.
• Pagination: Default limit is 100; adjust in config/fcaregister.php:

  'default_limit' => 500,