Relay Cabinet Connector Campusonline Bundle Laravel Package

Getting Started

Minimal Setup

1. Install the Bundle Add the bundle to your Laravel project via Composer:

   composer require dbp/relay-cabinet-connector-campusonline-bundle
   

   Register it in config/app.php under providers:

   DigitalBlueprint\RelayCabinetConnectorCampusonlineBundle\RelayCabinetConnectorCampusonlineBundle::class,
   

2. Publish Configuration Publish the bundle’s config file to customize API endpoints, credentials, and caching:

   php artisan vendor:publish --provider="DigitalBlueprint\RelayCabinetConnectorCampusonlineBundle\RelayCabinetConnectorCampusonlineBundle" --tag="config"
   

   Edit config/relay_cabinet_connector_campusonline.php to match your CAMPUSonline API credentials and endpoints.

3. First Use Case: Fetch Student Data Use the bundle’s service to fetch student data via the Relay API gateway:

   use DigitalBlueprint\RelayCabinetConnectorCampusonlineBundle\Service\CampusonlineService;
   
   $campusonlineService = app(CampusonlineService::class);
   $student = $campusonlineService->getStudentById('12345');
   

   The service abstracts API calls, handles authentication, and returns structured data (e.g., Student, Study, Application entities).

Where to Look First

• Documentation: Start with docs/README.md for API endpoints, response schemas, and authentication flow.
• Service Layer: Explore src/Service/CampusonlineService.php to understand available methods (e.g., getStudentById(), fetchApplications()).
• Configuration: Review config/relay_cabinet_connector_campusonline.php for API base URLs, rate limits, and caching settings.
• Events: Check src/Event/ for custom events (e.g., StudentFetchedEvent) to extend functionality.

Implementation Patterns

Core Workflow: Data Synchronization

1. Trigger Sync via Relay Use the Relay API gateway to initiate a sync request:

   $relay = app(\DigitalBlueprint\RelayCabinetBundle\Service\RelayService::class);
   $relay->syncConnector('campusonline', ['student_id' => '12345']);
   

   This delegates to the bundle’s connector logic.

2. Handle API Responses The bundle processes raw CAMPUSonline API responses into Laravel-friendly entities:

   $student = $campusonlineService->getStudentById('12345');
   // Returns an instance of \DigitalBlueprint\RelayCabinetConnectorCampusonlineBundle\Entity\Student
   

3. Cache Responses Leverage the built-in caching layer (default: Symfony Cache) to avoid redundant API calls:

   $campusonlineService->setCacheTTL(3600); // Cache for 1 hour
   

Integration Tips

• Entity Mapping Customize entity mappings in config/relay_cabinet_connector_campusonline.php to align with your Laravel models:

  'entity_mappings' => [
      'student' => \App\Models\Student::class,
      'study'   => \App\Models\Study::class,
  ],
  

• Event-Driven Extensions Listen to bundle events to react to API responses or sync failures:

  // In a service provider
  $this->app->booted(function () {
      event(new \DigitalBlueprint\RelayCabinetConnectorCampusonlineBundle\Event\StudentFetchedEvent($student));
  });
  

• Rate Limiting Configure rate limits in the config to comply with CAMPUSonline API policies:

  'api' => [
      'rate_limit' => 60, // Requests per minute
  ],
  

• Testing Use the bundle’s test utilities (e.g., CampusonlineServiceTest) as a foundation for your tests:

  $this->mock(CampusonlineService::class)
       ->shouldReceive('getStudentById')
       ->once()
       ->andReturn($mockStudent);
  

Gotchas and Tips

Pitfalls

1. Authentication Failures

   • Issue: Hardcoded credentials in config or expired tokens cause silent failures.
   • Fix: Use environment variables for credentials and implement token refresh logic:

     'auth' => [
         'client_id'     => env('CAMPUSONLINE_CLIENT_ID'),
         'client_secret' => env('CAMPUSONLINE_CLIENT_SECRET'),
         'token_url'     => env('CAMPUSONLINE_TOKEN_URL'),
     ],
     

   • Debug: Enable debug mode in config to log API errors:

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

2. Schema Mismatches

   • Issue: CAMPUSonline API response fields don’t map to your Laravel models.
   • Fix: Override entity hydrators in src/Hydrator/ or extend the base CampusonlineHydrator.

3. Caching Stale Data

   • Issue: Long TTLs cause outdated data to persist.
   • Fix: Implement cache invalidation via events or manual calls:

     $campusonlineService->invalidateCache('student:12345');
     

4. Relay Dependency

   • Issue: The bundle assumes dbp/relay-cabinet-bundle is installed and configured.
   • Fix: Verify the Relay gateway is running and properly configured before using this connector.

Debugging Tips

• Enable API Logging Add this to your config to log raw API requests/responses:

  'logging' => [
      'enabled' => true,
      'path'    => storage_path('logs/campusonline_api.log'),
  ],
  

• Mock the API for Local Development Use the CampusonlineApiClient interface to mock responses:

  $this->partialMock(CampusonlineApiClient::class, function ($mock) {
      $mock->shouldReceive('getStudentById')
           ->andReturn(['id' => '12345', 'name' => 'Test Student']);
  });
  

• Check HTTP Status Codes The bundle throws CampusonlineApiException for non-2xx responses. Catch and handle:

  try {
      $student = $campusonlineService->getStudentById('12345');
  } catch (\DigitalBlueprint\RelayCabinetConnectorCampusonlineBundle\Exception\CampusonlineApiException $e) {
      Log::error('CAMPUSonline API error: ' . $e->getMessage());
  }
  

Extension Points

1. Custom API Endpoints Extend the CampusonlineApiClient to support unsupported endpoints:

   // In a service provider
   $this->app->extend(CampusonlineApiClient::class, function ($client, $app) {
       $client->addEndpoint('custom', '/api/custom');
       return $client;
   });
   

2. Add New Entity Types Create a new hydrator and update the config:

   // config/relay_cabinet_connector_campusonline.php
   'entity_mappings' => [
       'custom_entity' => \App\Models\CustomEntity::class,
   ],
   

3. Modify Sync Logic Override the SyncConnector class to customize sync behavior:

   // app/Providers/CampusonlineConnectorServiceProvider.php
   $this->app->bind(SyncConnector::class, function ($app) {
       return new CustomSyncConnector(
           $app->make(CampusonlineService::class),
           $app->make(RelayService::class)
       );
   });
   

4. Add Webhooks Implement a WebhookListener to process CAMPUSonline webhook events:

   use DigitalBlueprint\RelayCabinetConnectorCampusonlineBundle\Event\WebhookReceivedEvent;
   
   event(new WebhookReceivedEvent($payload));