Relay Core Connector Campusonline Bundle Laravel Package

Getting Started

Minimal Setup

1. Install the Bundle

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

   Ensure DigitalBlueprint\RelayCoreConnectorCampusonlineBundle\DigitalBlueprintRelayCoreConnectorCampusonlineBundle is registered in your config/bundles.php.

2. Configure the Bundle Add the bundle configuration to config/packages/digital_blueprint_relay_core_connector_campusonline.yaml:

   digital_blueprint_relay_core_connector_campusonline:
       campusonline:
           base_uri: "https://your-campusonline-instance.de"
           api_key: "%env(CAMPUSONLINE_API_KEY)%"
           client_id: "%env(CAMPUSONLINE_CLIENT_ID)%"
           client_secret: "%env(CAMPUSONLINE_CLIENT_SECRET)%"
   

   Populate .env with the required credentials.

3. First Use Case: Fetching a User Use the CampusOnlineClient service to interact with CAMPUSonline:

   use DigitalBlueprint\RelayCoreConnectorCampusonlineBundle\Service\CampusOnlineClient;
   
   class MyService
   {
       public function __construct(private CampusOnlineClient $campusOnlineClient) {}
   
       public function getUserData(int $userId): array
       {
           return $this->campusOnlineClient->getUser($userId);
       }
   }
   

   Inject CampusOnlineClient into your controller or service.

Implementation Patterns

Workflows

1. Authentication & API Calls The bundle abstracts OAuth2 authentication. Use the CampusOnlineClient for authenticated requests:

   $this->campusOnlineClient->getCourse($courseId); // Automatically handles auth
   

2. Event Synchronization Leverage the CampusOnlineEventListener to sync events (e.g., user enrollments) between Relay and CAMPUSonline:

   # config/packages/digital_blueprint_relay_core_connector_campusonline.yaml
   digital_blueprint_relay_core_connector_campusonline:
       sync:
           enabled: true
           events:
               - "user.created"
               - "course.enrolled"
   

3. Custom Mappings Extend default entity mappings (e.g., User, Course) via configuration:

   digital_blueprint_relay_core_connector_campusonline:
       mappings:
           user:
               fields:
                   relay_id: "external_id"
                   email: "email_address"
   

4. Batch Processing Use the CampusOnlineBulkService for bulk operations (e.g., syncing 100+ users):

   $this->campusOnlineBulkService->syncUsers($userIds);
   

Integration Tips

• Relay API Gateway: Ensure your Relay API is configured to route CAMPUSonline-specific endpoints to this bundle.
• Logging: Enable debug logging for API calls:

  monolog:
      handlers:
          campusonline:
              type: stream
              path: "%kernel.logs_dir%/campusonline.log"
              level: debug
  

• Testing: Use the CampusOnlineClientTest trait for unit tests:

  use DigitalBlueprint\RelayCoreConnectorCampusonlineBundle\Tests\CampusOnlineClientTest;
  
  class MyTest extends TestCase
  {
      use CampusOnlineClientTest;
  
      public function testUserSync()
      {
          $this->mockCampusOnlineResponse(['id' => 123]);
          $this->assertEquals(123, $this->campusOnlineClient->getUser(1)->getId());
      }
  }
  

Gotchas and Tips

Pitfalls

1. API Rate Limits CAMPUSonline may throttle requests. Implement exponential backoff in custom services:

   use Symfony\Component\HttpClient\RetryableHttpClient;
   
   $client = new RetryableHttpClient(
       $baseClient,
       [
           'max_retries' => 3,
           'delay' => 1000,
           'multiplier' => 2,
           'statuses' => [429],
       ]
   );
   

2. Field Mismatches Default field mappings may not align with your Relay schema. Override mappings in config or via a custom service:

   $this->campusOnlineClient->setFieldMapper(new CustomFieldMapper());
   

3. OAuth2 Token Expiry Tokens expire after 1 hour. The bundle auto-refreshes, but handle silent failures:

   try {
       $data = $this->campusOnlineClient->getUser($id);
   } catch (\League\OAuth2\Client\Provider\Exception\TokenExpiredException $e) {
       $this->campusOnlineClient->refreshToken();
       retry();
   }
   

4. Idempotency Ensure sync operations are idempotent. Use upsert for writes:

   $this->campusOnlineClient->upsertUser($userData);
   

Debugging

• Enable API Debugging:

  digital_blueprint_relay_core_connector_campusonline:
      debug: true
  

  Logs raw API responses to var/log/campusonline.log.

• Mock Responses for Testing: Use the CampusOnlineClientTest trait to simulate API failures:

  $this->mockCampusOnlineError(404);
  $this->expectException(\RuntimeException::class);
  

Extension Points

1. Custom Endpoints Extend the CampusOnlineClient to add custom API routes:

   namespace App\Service;
   
   use DigitalBlueprint\RelayCoreConnectorCampusonlineBundle\Service\CampusOnlineClient;
   
   class ExtendedCampusOnlineClient extends CampusOnlineClient
   {
       public function getCustomEndpoint(): array
       {
           return $this->get('custom/endpoint');
       }
   }
   

2. Event Subscribers Listen to sync events and trigger custom logic:

   use DigitalBlueprint\RelayCoreConnectorCampusonlineBundle\Event\SyncEvent;
   
   class MySyncSubscriber implements EventSubscriberInterface
   {
       public static function getSubscribedEvents(): array
       {
           return [
               SyncEvent::USER_SYNCED => 'onUserSynced',
           ];
       }
   
       public function onUserSynced(SyncEvent $event): void
       {
           // Custom logic
       }
   }
   

3. Custom Auth Providers Replace the default OAuth2 provider:

   digital_blueprint_relay_core_connector_campusonline:
       auth:
           provider: "App\Auth\CustomCampusOnlineProvider"
   

   namespace App\Auth;
   
   use DigitalBlueprint\RelayCoreConnectorCampusonlineBundle\Auth\CampusOnlineProviderInterface;
   
   class CustomCampusOnlineProvider implements CampusOnlineProviderInterface
   {
       // Implement custom auth logic
   }
   

4. Webhook Handling Validate and process CAMPUSonline webhooks:

   use DigitalBlueprint\RelayCoreConnectorCampusonlineBundle\Event\WebhookEvent;
   
   class WebhookSubscriber implements EventSubscriberInterface
   {
       public static function getSubscribedEvents(): array
       {
           return [
               WebhookEvent::WEBHOOK_RECEIVED => 'onWebhookReceived',
           ];
       }
   
       public function onWebhookReceived(WebhookEvent $event): void
       {
           $data = $event->getPayload();
           // Process webhook
       }
   }