Relay Base Person Connector Campusonline Bundle Laravel Package

Getting Started

Minimal Steps

1. Install the Bundle

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

2. Register the Bundle Add to config/bundles.php (place before DbpRelayCoreBundle):

   Dbp\Relay\BasePersonConnectorCampusonlineBundle\DbpRelayBasePersonConnectorCampusonlineBundle::class => ['all' => true],
   

3. Configure the Bundle Add to config/packages/relay.yaml (or equivalent):

   dbp_relay_base_person_connector_campusonline:
       database_url: '%env(RELAY_CAMPUSONLINE_DB_URL)%'
   

4. Clear Caches

   php bin/console cache:clear
   

5. First Use Case Inject the connector into a service and fetch a user:

   use Dbp\Relay\BasePersonConnectorCampusonlineBundle\Service\CampusonlineConnector;
   
   class MyService {
       public function __construct(private CampusonlineConnector $connector) {}
   
       public function fetchUser(string $campusonlineId): array {
           return $this->connector->getPerson($campusonlineId);
       }
   }
   

Implementation Patterns

Core Workflows

1. Person Data Synchronization Use the connector to fetch or sync user data from Campusonline:

   $userData = $connector->syncPerson($campusonlineId);
   

2. Event-Driven Updates Subscribe to DbpRelayBasePersonConnectorCampusonlineBundle:person_updated events:

   // In a subscriber service
   public function onPersonUpdated(PersonUpdatedEvent $event) {
       $this->handleUpdatedPerson($event->getPerson());
   }
   

3. Batch Processing Fetch multiple users in bulk:

   $batch = $connector->getPersonsByIds([$id1, $id2, $id3]);
   

Integration Tips

• Dependency Injection Prefer constructor injection for the CampusonlineConnector to ensure testability:

  public function __construct(private CampusonlineConnector $connector) {}
  

• Configuration Overrides Override default config via config/packages/relay.yaml:

  dbp_relay_base_person_connector_campusonline:
      database_url: 'your_custom_url'
      timeout: 30 # seconds
  

• Logging Enable debug logging for troubleshooting:

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

• API Server Template If using the DBP API Server Template, the bundle is pre-configured. Focus on extending the Person entity or adding custom fields.

Gotchas and Tips

Pitfalls

1. Configuration Sensitivity

   • The database_url must be a valid Campusonline API endpoint (e.g., https://campusonline.example.edu/api/v1).
   • Gotcha: Hardcoding URLs in bundles.php violates the 12-factor app principle. Always use environment variables (%env()).

2. Rate Limiting

   • Campusonline APIs often enforce rate limits. Implement retries with exponential backoff:

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

3. Data Mismatches

   • Campusonline and your system may have differing field names (e.g., user_id vs. campusonline_id). Normalize mappings in a DTO:

     class CampusonlinePersonDto {
         public function __construct(
             public string $externalId,
             public ?string $email,
             public array $roles = []
         ) {}
     }
     

4. Circular Dependencies

   • Avoid injecting the connector into bundles that are loaded after it. Use lazy services or factory patterns:

     // services.yaml
     App\Service\PersonFactory:
         arguments:
             $connector: '@dbp_relay_base_person_connector_campusonline.connector'
         lazy: true
     

Debugging

• Enable API Debugging Add this to config/packages/dev/relay.yaml:

  dbp_relay_base_person_connector_campusonline:
      debug: true
  

  This logs raw API responses/errors to var/log/dev.log.

• Common Errors

  Error	Solution
  InvalidArgumentException	Check database_url format (must include /api/v1).
  HttpClientException	Verify API credentials or network connectivity.
  JsonException	Campusonline returned malformed JSON; inspect raw response in logs.
  PersonNotFoundException	Handle gracefully with a fallback (e.g., create a stub user).

Extension Points

1. Custom Fields Extend the Person entity to include Campusonline-specific fields:

   // src/Entity/Person.php
   #[ORM\Column(nullable: true)]
   private ?string $campusonlineEnrollmentStatus;
   

2. Event Listeners Add logic when users are synced:

   // src/EventListener/PersonSyncListener.php
   public function onPersonSynced(PersonSyncedEvent $event) {
       if ($event->getPerson()->isActive()) {
           $this->sendWelcomeEmail($event->getPerson());
       }
   }
   

3. Override API Client Replace the default HttpClient with a custom one (e.g., for mocking in tests):

   # config/services.yaml
   Dbp\Relay\BasePersonConnectorCampusonlineBundle\Client\CampusonlineApiClient:
       arguments:
           $client: '@your_custom_http_client'
   

4. Webhook Integration Campusonline may support webhooks. Create a controller to handle them:

   #[Route('/campusonline/webhook', name: 'campusonline_webhook', methods: ['POST'])]
   public function handleWebhook(Request $request, CampusonlineConnector $connector): Response {
       $data = json_decode($request->getContent(), true);
       $connector->processWebhook($data);
       return new Response('OK');
   }