Relay Sublibrary Bundle Laravel Package

Getting Started

Minimal Setup

1. Installation:

   composer require dbp/relay-sublibrary-bundle
   

   Publish the bundle configuration:

   php artisan vendor:publish --provider="Dbp\RelaySublibraryBundle\RelaySublibraryBundle" --tag="config"
   

2. Configuration:

   • Edit config/relay-sublibrary.php to define:
     • alma_api_key (shared ALMA API key)
     • sub_orgs (array of sub-organization IDs/keys)
     • default_sub_org (fallback sub-org for unauthenticated requests)
   • Set up .env with:

     RELAY_SUBLIBRARY_ALMA_API_KEY=your_key_here
     

3. First Use Case: Fetch a sub-org’s holdings via a controller:

   use Dbp\RelaySublibraryBundle\Service\AlmaService;
   
   public function getHoldings(AlmaService $almaService, string $subOrgKey) {
       $holdings = $almaService->getHoldings($subOrgKey);
       return response()->json($holdings);
   }
   

Implementation Patterns

Core Workflows

1. Sub-Organization Isolation:

   • Request Scoping: Prefix routes with {subOrgKey} (e.g., /api/{subOrgKey}/holdings). Use middleware to inject the sub-org context:

     // app/Http/Middleware/SubOrgMiddleware.php
     public function handle($request, Closure $next) {
         $subOrgKey = $request->route('subOrgKey');
         app('relay-sublibrary')->setCurrentSubOrg($subOrgKey);
         return $next($request);
     }
     

   • Service Layer: Use AlmaService to delegate ALMA API calls with auto-scoping:

     $service->createBook($subOrgKey, $bookData);
     

2. API Integration:

   • Rate Limiting: Configure config/relay-sublibrary.php to throttle requests per sub-org:

     'rate_limits' => [
         'holdings' => ['max' => 100, 'period' => 'minute'],
     ],
     

   • Error Handling: Extend Dbp\RelaySublibraryBundle\Exception\AlmaException for custom responses:

     try {
         $service->updateBudget($subOrgKey, $data);
     } catch (AlmaException $e) {
         return response()->json(['error' => $e->getSubOrgMessage()], 400);
     }
     

3. Frontend Sync:

   • Expose GraphQL mutations/resolvers for the Sublibrary Frontend:

     // app/GraphQL/Mutations/CreateBook.php
     public function resolve($root, array $args) {
         return app('relay-sublibrary')->createBook($args['subOrgKey'], $args['input']);
     }
     

Common Patterns

• Dependency Injection: Bind the bundle’s services in AppServiceProvider:

  $this->app->bind(AlmaService::class, function ($app) {
      return new AlmaService($app['config']['relay-sublibrary']);
  });
  

• Event Listeners: Hook into sub-org changes:

  // app/Listeners/LogSubOrgActivity.php
  public function handle(SubOrgChanged $event) {
      Log::info("Switched to sub-org: {$event->subOrgKey}");
  }
  

Gotchas and Tips

Pitfalls

1. API Key Leaks:

   • Risk: Hardcoding alma_api_key in config or logs.
   • Fix: Use Laravel’s .env and validate keys via middleware:

     // app/Http/Middleware/ValidateAlmaKey.php
     public function handle($request, Closure $next) {
         if (empty(config('relay-sublibrary.alma_api_key'))) {
             throw new \RuntimeException('ALMA API key not configured.');
         }
         return $next($request);
     }
     

2. Sub-Org Mismatches:

   • Issue: Frontend sends subOrgKey="org1" but backend processes as org2.
   • Debug: Add a SubOrgMiddleware log:

     Log::debug("Current sub-org: " . app('relay-sublibrary')->getCurrentSubOrg());
     

3. Rate Limiting:

   • Quirk: Default limits may throttle legitimate usage.
   • Tip: Adjust rate_limits per sub-org dynamically:

     $service->setRateLimit($subOrgKey, ['max' => 200, 'period' => 'hour']);
     

Debugging

• ALMA API Logs: Enable verbose logging in config/relay-sublibrary.php:

  'debug' => env('APP_DEBUG', false),
  

• HTTP Interceptor: Use Dbp\RelaySublibraryBundle\Service\AlmaHttpClient to inspect raw ALMA responses:

  $client = app(AlmaHttpClient::class);
  $client->setDebug(true); // Logs requests/responses to storage/logs/alma_debug.log
  

Extension Points

1. Custom ALMA Endpoints:

   • Extend AlmaService to add methods for unsupported ALMA API calls:

     // app/Services/ExtendedAlmaService.php
     public function customAlmaCall($subOrgKey, $endpoint, $data) {
         return $this->httpClient->post(
             "https://api.alma.exlibrisgroup.com/{$endpoint}",
             $this->preparePayload($subOrgKey, $data)
         );
     }
     

2. Sub-Org Validation:

   • Override SubOrgValidator to enforce custom rules (e.g., budget caps):

     // app/Services/CustomSubOrgValidator.php
     public function validate($subOrgKey, $action) {
         if ($action === 'update_budget' && $this->isOverBudget($subOrgKey)) {
             throw new \InvalidArgumentException("Budget exceeded for {$subOrgKey}.");
         }
         return parent::validate($subOrgKey, $action);
     }
     

3. Webhook Integration:

   • Listen for ALMA webhook events and sync sub-org data:

     // app/Listeners/SyncAlmaWebhook.php
     public function handle(AlmaWebhookReceived $event) {
         $subOrgKey = $event->payload['sub_org_key'];
         $this->syncHoldings($subOrgKey);
     }