Relay Sublibrary Connector Campusonline Bundle Laravel Package

## Getting Started

### Minimal Setup
1. **Installation**:
   ```bash
   composer require dbp/relay-sublibrary-connector-campusonline-bundle

Ensure your Laravel app meets the Relay API Gateway requirements (PHP 8.1+, Symfony 5.4+).

2. Bundle Registration: Add the bundle to config/bundles.php:

   return [
       // ...
       DigitalBlueprint\Relay\SublibraryConnector\CampusOnlineBundle\DbpRelaySublibraryConnectorCampusonlineBundle::class => ['all' => true],
   ];
   

3. Configuration: Publish the default config:

   php artisan vendor:publish --tag="campusonline-bundle-config"
   

   Update config/campusonline.php with your CampusOnline API credentials and endpoint.

4. First Use Case: Trigger a sync via CLI:

   php artisan campusonline:sync
   

   Verify logs in storage/logs/laravel.log for API responses.

Implementation Patterns

Core Workflows

1. API Integration:

   • Use the CampusOnlineClient service (autowired via Symfony DI) to interact with CampusOnline.
   • Example:

     use DigitalBlueprint\Relay\SublibraryConnector\CampusOnlineBundle\Service\CampusOnlineClient;
     
     public function __construct(private CampusOnlineClient $client) {}
     
     public function fetchCourses() {
         return $this->client->get('/courses', ['limit' => 100]);
     }
     

2. Event-Driven Syncs:

   • Extend CampusOnlineSyncCommand to customize sync logic:

     protected function execute(InputInterface $input, OutputInterface $output): int {
         $data = $this->client->get('/sync-data');
         $this->processData($data); // Custom logic
         return Command::SUCCESS;
     }
     

3. Data Transformation:

   • Use CampusOnlineDataMapper to convert raw API responses to Laravel models:

     $mapper = new CampusOnlineDataMapper();
     $course = $mapper->mapToCourse($apiResponse);
     

4. Scheduled Syncs:

   • Register a cron job in app/Console/Kernel.php:

     protected function schedule(Schedule $schedule) {
         $schedule->command('campusonline:sync')->dailyAt('03:00');
     }
     

Integration Tips

• Relay API Gateway: Proxy requests through Relay by extending RelayConnectorInterface:

  class CampusOnlineRelayConnector implements RelayConnectorInterface {
      public function connect(): array {
          return $this->client->authenticate();
      }
  }
  

• Testing: Mock CampusOnlineClient in unit tests:

  $mockClient = Mockery::mock(CampusOnlineClient::class);
  $mockClient->shouldReceive('get')->andReturn(['data' => []]);
  $this->app->instance(CampusOnlineClient::class, $mockClient);
  

Gotchas and Tips

Pitfalls

1. Authentication Failures:

   • Ensure CAMPUSONLINE_API_KEY and CAMPUSONLINE_API_SECRET are set in .env.
   • Debug with:

     php artisan campusonline:debug-auth
     

2. Rate Limiting:

   • CampusOnline may throttle requests. Implement exponential backoff in custom sync logic:

     use Symfony\Component\HttpClient\RetryableHttpClient;
     $client = new RetryableHttpClient($baseClient, [
         'max_retries' => 3,
         'delay_between_retries' => 1000,
     ]);
     

3. Data Schema Mismatches:

   • Validate API responses against expected schemas using RelaySchemaValidator:

     $validator = new RelaySchemaValidator();
     $validator->validate($apiResponse, Course::class);
     

4. Archived Package:

   • No active maintenance. Fork the repo if critical fixes are needed.

Debugging

• Enable verbose logging in config/campusonline.php:

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

• Use php artisan campusonline:log-request to dump raw API requests/responses.

Extension Points

1. Custom Endpoints: Override CampusOnlineClient to add endpoints:

   class CustomCampusOnlineClient extends CampusOnlineClient {
       public function getEnrollments() {
           return $this->request('GET', '/enrollments');
       }
   }
   

   Bind it in config/services.php:

   'campusonline' => [
       'client' => CustomCampusOnlineClient::class,
   ],
   

2. Webhooks: Extend CampusOnlineWebhookController to handle real-time updates:

   public function handleWebhook(Request $request) {
       $payload = $request->json()->all();
       $this->dispatch(new CampusOnlineWebhookEvent($payload));
   }
   

3. Model Events: Listen for model events (e.g., CourseSynced) to trigger side effects:

   Course::synced(function ($course) {
       // Send notification, update cache, etc.
   });
   

Config Quirks

• Caching: Disable caching in config/campusonline.php if testing:

  'cache' => [
      'enabled' => env('CAMPUSONLINE_CACHE_ENABLED', false),
  ],
  

• Environment Variables: Prefix all .env vars with CAMPUSONLINE_ to avoid conflicts:

  CAMPUSONLINE_API_URL=https://api.campusonline.example