Relay Base Course Connector Campusonline Bundle Laravel Package

Getting Started

Minimal Setup

1. Install the Bundle

   composer require dbp/relay-base-course-connector-campusonline-bundle
   

   Ensure Dbp\Relay\BasePersonBundle\DbpRelayBaseCourseBundle and this bundle are enabled in config/bundles.php.

2. Configure Environment Variables Add these to .env (or your environment config):

   CAMPUS_ONLINE_API_TOKEN=your_token_here
   CAMPUS_ONLINE_API_URL=https://api.campusonline.example
   ORG_ROOT_ID=your_org_root_id
   

3. Verify Configuration Create config/packages/dbp_relay_base_course_connector_campusonline.yaml with the required YAML snippet.

4. First Use Case: Sync Courses Trigger a course sync via a command or API endpoint (if exposed by the bundle):

   php bin/console dbp:relay:campusonline:sync-courses
   

   Check logs (storage/logs/) for sync results.

Implementation Patterns

Workflow: Course Integration

1. API Integration The bundle abstracts CampusOnline API calls (e.g., fetching courses, enrollments). Use its services to interact with CampusOnline without direct API calls:

   // Inject the service (via autowiring or manual binding)
   $campusOnlineService = $this->container->get('dbp_relay.campusonline.client');
   
   $courses = $campusOnlineService->getCourses($orgRootId);
   

2. Event-Driven Syncs Listen for course updates via Symfony events (if the bundle emits them). Example:

   // In a service or event subscriber
   $eventDispatcher->addListener(
       'dbp_relay.campusonline.course.sync',
       function (CourseSyncEvent $event) {
           // Process synced courses (e.g., update local DB)
       }
   );
   

3. Command-Line Automation Schedule periodic syncs with Symfony’s CronBundle or Laravel’s task scheduler:

   # config/packages/cron.yaml
   cron:
       jobs:
           sync_campusonline_courses:
               command: 'dbp:relay:campusonline:sync-courses'
               schedule: '0 3 * * *'  # Daily at 3 AM
   

4. Data Mapping Use the bundle’s mappers to transform CampusOnline data into Relay-compatible formats:

   $mapper = $this->container->get('dbp_relay.campusonline.course_mapper');
   $relayCourse = $mapper->mapCampusOnlineCourseToRelay($campusOnlineCourse);
   

5. Testing Mock the CampusOnlineClient service in tests:

   $client = $this->createMock(CampusOnlineClient::class);
   $client->method('getCourses')->willReturn([...]);
   $this->container->set('dbp_relay.campusonline.client', $client);
   

Gotchas and Tips

Pitfalls

1. API Token Security

   • Never hardcode api_token in YAML. Always use %env() and restrict .env file permissions (chmod 600 .env).
   • Rotate tokens periodically and update them in the environment.

2. Rate Limiting

   • CampusOnline APIs may throttle requests. Implement exponential backoff in custom services if syncs fail:

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

3. Data Conflicts

   • Syncs may overwrite local data. Use upsert strategies or versioning (e.g., updated_at timestamps) to resolve conflicts:

     if ($localCourse->updated_at < $campusOnlineCourse->lastUpdated) {
         $localCourse->updateFromCampusOnline($campusOnlineCourse);
     }
     

4. Dependency on Base Bundles

   • This bundle depends on DbpRelayBaseCourseBundle. Ensure it’s installed and configured first. Check for version compatibility in composer.json.

5. Logging

   • Enable debug logging for API calls in config/packages/monolog.yaml:

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

Tips

1. Extend the Client Create a decorator to add custom logic (e.g., caching, retries):

   // src/Service/CampusOnlineClientDecorator.php
   class CampusOnlineClientDecorator implements CampusOnlineClientInterface {
       public function __construct(private CampusOnlineClientInterface $client) {}
   
       public function getCourses($orgId) {
           $cacheKey = "campusonline_courses_{$orgId}";
           if (Cache::has($cacheKey)) {
               return Cache::get($cacheKey);
           }
           $courses = $this->client->getCourses($orgId);
           Cache::put($cacheKey, $courses, '1 hour');
           return $courses;
       }
   }
   

   Register the decorator in services.yaml:

   services:
       dbp_relay.campusonline.client:
           decorates: 'dbp_relay.campusonline.client'
           arguments: ['@dbp_relay.campusonline.client.inner']
   

2. Webhook Integration If CampusOnline supports webhooks, create a Symfony controller to handle real-time updates:

   #[Route('/campusonline/webhook', name: 'campusonline_webhook', methods: ['POST'])]
   public function handleWebhook(Request $request): Response {
       $payload = json_decode($request->getContent(), true);
       $this->eventDispatcher->dispatch(
           new CampusOnlineWebhookEvent($payload)
       );
       return new Response('OK');
   }
   

3. Testing API Responses Use HttpClient to mock API responses in tests:

   $httpClient = new HttpClient([
       'base_uri' => 'https://api.campusonline.example',
   ]);
   $httpClient->addSubscriber(new MockApiSubscriber([...])); // Custom subscriber
   $this->container->set('http_client', $httpClient);
   

4. Error Handling Centralize API error handling in a middleware or subscriber:

   $eventDispatcher->addListener(
       'kernel.exception',
       function (GetResponseForExceptionEvent $event) {
           $exception = $event->getThrowable();
           if ($exception instanceof \Symfony\Contracts\HttpClient\Exception\ClientExceptionInterface) {
               // Log CampusOnline-specific errors
           }
       }
   );
   

5. Configuration Validation Validate YAML config at runtime using Symfony’s ParameterBag:

   $config = $this->container->getParameter('dbp_relay_base_course_connector_campusonline');
   if (empty($config['campus_online']['api_token'])) {
       throw new \RuntimeException('CampusOnline API token is required.');
   }