Relay Campusonline Bundle Laravel Package

Getting Started

First Steps

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

   composer require dbp/relay-campusonline-bundle
   

   Register the bundle in config/app.php under providers:

   DBP\Relay\CampusOnlineBundle\CampusOnlineServiceProvider::class,
   

2. Configuration Publish the config file:

   php artisan vendor:publish --provider="DBP\Relay\CampusOnlineBundle\CampusOnlineServiceProvider" --tag="config"
   

   Update config/campusonline.php with your CampusOnline API credentials (client ID, secret, base URL).

3. Service Container Binding The bundle auto-registers a CampusOnline facade. Test basic connectivity:

   use DBP\Relay\CampusOnlineBundle\Facades\CampusOnline;
   
   $response = CampusOnline::get('/api/v1/users');
   

4. First Use Case: Fetching User Data

   $user = CampusOnline::get('/api/v1/users/123');
   // Handle response (e.g., map to a local model)
   

Implementation Patterns

Common Workflows

1. API Requests Use the facade for REST calls:

   // GET request
   $data = CampusOnline::get('/api/v1/courses', ['limit' => 10]);
   
   // POST request (e.g., create enrollment)
   $enrollment = CampusOnline::post('/api/v1/enrollments', [
       'user_id' => 123,
       'course_id' => 456,
   ]);
   

2. Authentication The bundle handles OAuth2 via the config. Refresh tokens automatically if expired:

   CampusOnline::withToken()->get('/api/v1/protected-data');
   

3. Response Handling Normalize responses into Laravel collections or models:

   $courses = collect(CampusOnline::get('/api/v1/courses')->json())->mapToModel(Course::class);
   

4. Webhook Listeners Register a listener for CampusOnline webhooks (e.g., enrollment events):

   // In EventServiceProvider
   protected $listen = [
       'DBP\Relay\CampusOnlineBundle\Events\EnrollmentCreated' => [
           CampusOnlineEnrollmentHandler::class,
       ],
   ];
   

5. Local Model Sync Use observers or jobs to sync CampusOnline data to local models:

   // Example: Sync courses nightly
   CampusOnline::syncCoursesToLocal();
   

Integration Tips

• Laravel Scout: Index CampusOnline search results for global search.
• Laravel Nova: Extend Nova with custom tools to manage CampusOnline data.
• Queues: Offload heavy syncs to queues (e.g., CampusOnline::syncAllUsers()->onQueue('campusonline')).
• Caching: Cache frequent API calls with Cache::remember():

  $courses = Cache::remember('campusonline_courses', now()->addHours(1), function () {
      return CampusOnline::get('/api/v1/courses');
  });
  

Gotchas and Tips

Pitfalls

1. Rate Limiting CampusOnline may throttle requests. Implement exponential backoff:

   try {
       $response = CampusOnline::get('/api/v1/large-dataset');
   } catch (\DBP\Relay\CampusOnlineBundle\Exceptions\RateLimitExceeded $e) {
       sleep($e->retryAfter);
       retry();
   }
   

2. Token Expiry Always handle TokenExpiredException:

   CampusOnline::withToken(function () {
       // Retry logic or fallback
   });
   

3. Data Mismatches Validate API responses against expected schemas (e.g., use spatie/laravel-data):

   $userData = CampusOnline::get('/api/v1/users/123')->json();
   User::fromApi($userData); // Custom validation
   

4. Webhook Verification CampusOnline webhooks require HMAC validation. Use the bundle’s verifyWebhook helper:

   if (!CampusOnline::verifyWebhook($request->header('X-Hub-Signature'), $request->getContent())) {
       abort(403);
   }
   

Debugging

• Enable Logging: Set debug to true in config/campusonline.php to log API calls.
• Mock API Calls: Use CampusOnline::shouldReceive() in tests:

  CampusOnline::shouldReceive('get')
      ->once()
      ->with('/api/v1/users/123')
      ->andReturn(response()->json(['id' => 123]));
  

Extension Points

1. Custom API Clients Extend the base client for custom headers or middleware:

   CampusOnline::extend(function ($client) {
       $client->withHeader('X-Custom-Header', 'value');
   });
   

2. Event Customization Publish and override event classes:

   php artisan vendor:publish --provider="DBP\Relay\CampusOnlineBundle\CampusOnlineServiceProvider" --tag="events"
   

3. Local Storage Adapters Replace the default Eloquent models with custom storage (e.g., DynamoDB):

   CampusOnline::setLocalStorageAdapter(new CustomAdapter());
   

4. API Versioning Use the version() method to switch endpoints:

   CampusOnline::version('v2')->get('/courses');