Campusonline Api Laravel Package

Technical Evaluation

Architecture Fit

• Pros:

  • Specialized for CAMPUSonline: The package is a dedicated PHP client for CAMPUSonline’s APIs (legacy REST, XML Web Services, and Public REST), reducing the need for manual API integration and error handling.
  • Modular Design: Supports multiple API endpoints (UCard, Generic Exports, Legacy XML, Public REST) under a unified Api facade, enabling selective adoption.
  • Caching Middleware: Leverages kevinrob/guzzle-cache-middleware (v5–v7) for performance optimization, aligning with Laravel’s caching strategies (e.g., Redis, file cache).
  • Pagination Support: Offers both offset- and cursor-based pagination for scalable data fetching, critical for large datasets (e.g., user lists, courses).
  • Filtering: Includes a FilterBuilder for complex queries, reducing backend processing in Laravel.

• Cons:

  • AGPL-3.0 License: May conflict with proprietary Laravel applications. Requires compliance with AGPL terms (e.g., open-sourcing modified versions).
  • Legacy APIs: Heavy reliance on deprecated/legacy endpoints (e.g., XML Web Services) could introduce technical debt if CAMPUSonline sunsets these APIs.
  • Experimental Features: Public REST API support is marked as experimental, implying potential instability or breaking changes.
  • No Laravel-Specific Integrations: Lacks built-in Laravel service providers, queue jobs, or Eloquent models, requiring manual adaptation.

Integration Feasibility

• Laravel Compatibility:
  • HTTP Client: Uses Guzzle under the hood, which Laravel already supports via HttpClient facade or GuzzleHttp\Client. Minimal conflict risk.
  • Dependency Management: Composer-based; no Laravel-specific service container integration required (but can be manually registered).
  • Authentication: Supports OAuth2 (client credentials) and API tokens, alignable with Laravel Passport or Sanctum for centralized auth.
• Data Mapping:
  • Returns raw arrays/objects (e.g., getCardsForIdentIdObfuscated()). Laravel can map these to Eloquent models or DTOs via Collection transformations or API resources.
  • XML Web Services return arrays of arrays, which may need serialization (e.g., json_encode()) for Laravel’s JSON responses.

Technical Risk

• High:
  • License Compliance: AGPL-3.0 may force open-sourcing of the entire Laravel application if modifications are made. Requires legal review.
  • API Stability: CAMPUSonline’s legacy APIs (XML Web Services) are at risk of deprecation. Public REST APIs are experimental.
  • Error Handling: Custom ApiException is HTTP-response-based; Laravel’s exception handling (e.g., render() in App\Exceptions\Handler) may need extension.
  • Caching Complexity: Guzzle cache middleware must be configured to avoid conflicts with Laravel’s cache (e.g., config('cache.default')).
• Medium:
  • Performance: Large exports (e.g., GenericApi::getResource()) could overwhelm Laravel’s memory limits. Requires chunking or streaming.
  • Pagination: Mixed pagination strategies (offset/cursor) may need normalization for Laravel’s pagination helpers (e.g., SimplePaginator).
• Low:
  • Dependency Conflicts: Guzzle and PHPUnit versions are loosely constrained, reducing version clashes.

Key Questions

1. License Alignment:
   • Can the AGPL-3.0 license be mitigated (e.g., via a commercial license from Digital Blueprint)?
   • Will the Laravel application need to be open-sourced if using this package?
2. API Strategy:
   • Is CAMPUSonline phasing out legacy APIs (XML Web Services)? If so, should integration focus on Public REST APIs only?
   • Are there rate limits or quotas on CAMPUSonline’s APIs that could impact Laravel’s scaling?
3. Data Flow:
   • How will Laravel map CAMPUSonline responses to Eloquent models or API resources? Will custom mappers be needed?
   • Are there sensitive fields (e.g., IdentIdObfuscated) that require additional encryption/decryption in Laravel?
4. Operational Resilience:
   • How will token refreshes (e.g., OAuth2) be handled in Laravel’s context (e.g., via Laravel Queues or cron jobs)?
   • What fallback mechanisms exist for API failures (e.g., retries, circuit breakers)?
5. Testing:
   • Are there mockable interfaces for unit testing Laravel services that depend on this package?
   • How will integration tests verify API responses against Laravel’s expectations?

Integration Approach

Stack Fit

• Laravel Integration Points:
  • Service Layer: Inject the Dbp\CampusonlineApi\Rest\Api instance into Laravel services (e.g., app/Services/CampusonlineService) for business logic.
  • HTTP Client: Use Laravel’s HttpClient facade to wrap the package’s Guzzle client for consistency (optional).
  • Authentication: Centralize OAuth2 token management via Laravel Passport or Sanctum, with token refresh logic in a custom CampusonlineTokenManager.
  • Caching: Configure kevinrob/guzzle-cache-middleware to use Laravel’s cache store (e.g., Redis) via CacheMiddleware::withStore().
  • Events/Jobs: Offload long-running operations (e.g., large exports) to Laravel Queues with ShouldQueue jobs.
• Database:
  • Use Eloquent models to persist CAMPUSonline data (e.g., Course, User) with custom accessors/mutators for API-specific fields.
  • Consider a campusonline database prefix to avoid naming conflicts.

Migration Path

1. Phase 1: Legacy APIs (Low Risk)
   • Integrate UCardApi, GenericApi, and LegacyWebService\Api for immediate use cases (e.g., student card validation, data exports).
   • Implement a Laravel service facade (e.g., Campusonline::ucard()->getCardsForIdentIdObfuscated()) to abstract the package.
2. Phase 2: Public REST APIs (Medium Risk)
   • Adopt PublicRestApi for modern endpoints (e.g., courses, rooms) once stability is confirmed.
   • Deprecate legacy APIs in favor of Public REST where possible.
3. Phase 3: Full Feature Parity
   • Extend Laravel API resources to normalize responses (e.g., CourseResource, UserResource).
   • Add Laravel-specific features (e.g., rate limiting, request validation) around the package’s methods.

Compatibility

• Laravel Versions:
  • PHP 8.2+ required (package drops PHP 8.1 support). Ensure Laravel’s config('app.php_version') aligns.
  • Tested with PHPUnit 10; Laravel’s default PHPUnit version should suffice.
• Guzzle Middleware:
  • Configure guzzle-cache-middleware to avoid conflicts with Laravel’s cache (e.g., exclude Laravel’s cache keys from Guzzle’s cache).
  • Example:

    $client = new Client([
        'middleware' => [
            new CacheMiddleware([
                'store' => new RedisStore(config('cache.redis')),
                'expiration' => 60,
            ]),
        ],
    ]);
    

• Pagination:
  • Normalize CAMPUSonline’s pagination (offset/cursor) to Laravel’s LengthAwarePaginator or SimplePaginator:

    $data = $api->GenericApi('loc_apiMyExport')->getResource('ID', 42, ['limit' => 50]);
    return new LengthAwarePaginator(
        collect($data['results']),
        $data['total'],
        $data['limit'],
        $data['page']
    );
    

Sequencing

1. Setup:
   • Install the package: composer require dbp/campusonline-api.
   • Publish config files (if any) or define Laravel config (e.g., config/campusonline.php) for API endpoints/credentials.
2. Authentication:
   • Implement token management (e.g., CampusonlineTokenManager) with refresh logic.
   • Store tokens securely (e.g., Laravel’s encryption or sanctum).
3. Core Integration:
   • Create Laravel services to wrap the package’s APIs (e.g., app/Services/Campusonline/UCardService).
   • Example:

     class UCardService {
         public function __construct(private Api $api) {}
     
         public function getCard(string $obfuscatedId): array {
             return $this->api->UCard()->getCardsForIdentIdObfuscated($obfuscatedId);
         }
     }
     

4. Data Layer:
   • Map API responses to Eloquent models or DTOs.
   • Example model:

     class CampusonlineUser extends Model {
         protected $fillable = ['person_uid', 'name', 'email'];
     
         public static function fromApi(array $data): self {
             return self::create([
                 'person_uid' => $data['personUid'],
                 'name' => $data