Relay Cabinet Bundle Laravel Package

Getting Started

Minimal Setup

1. Installation:

   composer require dbp/relay-cabinet-bundle
   

   Add to config/bundles.php:

   return [
       // ...
       DigitalBlueprint\RelayCabinetBundle\RelayCabinetBundle::class => ['all' => true],
   ];
   

2. Publish Config:

   php artisan vendor:publish --provider="DigitalBlueprint\RelayCabinetBundle\RelayCabinetBundle" --tag="config"
   

   Edit config/relay_cabinet.php to match your database schema (e.g., student_records table).

3. First Use Case: Inject the RelayCabinetService into a controller/service:

   use DigitalBlueprint\RelayCabinetBundle\Service\RelayCabinetService;
   
   public function __construct(private RelayCabinetService $cabinet) {}
   
   // Fetch a student record by ID
   $student = $this->cabinet->getStudentRecord(1);
   

4. Migrations: Run the bundle’s migrations (if provided) or adapt your existing student_records table to match the expected schema (check docs/schema.md if available).

Implementation Patterns

Core Workflows

1. CRUD Operations: Use the service methods for standard operations:

   // Create
   $this->cabinet->createStudentRecord([
       'first_name' => 'John',
       'last_name' => 'Doe',
       'email' => 'john@example.com',
       // ... other fields
   ]);
   
   // Update
   $this->cabinet->updateStudentRecord(1, ['email' => 'new@example.com']);
   
   // Delete
   $this->cabinet->deleteStudentRecord(1);
   

2. Querying Records: Leverage the findStudentRecords() method with filters:

   $students = $this->cabinet->findStudentRecords([
       'grade_level' => '10',
       'active' => true,
   ]);
   

3. Event Integration: Listen for bundle events (if documented) to extend functionality:

   // Example: Listen for record creation
   event(new CreatingStudentRecord($data));
   

4. API Integration: Pair with the Cabinet Frontend for a pre-built UI. Expose API endpoints via Laravel’s Route::apiResource():

   Route::apiResource('students', StudentController::class);
   

Advanced Patterns

1. Custom Validation: Extend the bundle’s validation rules by overriding the RelayCabinetService or creating a decorator:

   class CustomRelayCabinetService extends RelayCabinetService {
       protected function validateCreate(array $data): void {
           parent::validateCreate($data);
           // Add custom rules
       }
   }
   

2. Repository Pattern: Decouple the service by implementing a repository interface:

   interface StudentRecordRepository {
       public function findById(int $id);
   }
   

3. Testing: Mock the RelayCabinetService in unit tests:

   $mock = $this->createMock(RelayCabinetService::class);
   $mock->method('getStudentRecord')->willReturn($fakeStudent);
   

Gotchas and Tips

Pitfalls

1. Schema Mismatch:

   • The bundle assumes a specific student_records table structure. Always verify the expected schema in docs/schema.md or inspect the service’s createStudentRecord() method for required fields.
   • Fix: Adjust your migrations or extend the service to handle custom schemas.

2. Undocumented Methods:

   • The package has no dependents or stars, so some methods may be undocumented. Use php artisan ide-helper:generate to auto-generate PHPDoc stubs for safer usage.

3. AGPL License:

   • The AGPL-3.0 license requires open-sourcing your project if you use this bundle in a SaaS product. Review compliance with your project’s licensing.

4. No Built-in API Resources:

   • The bundle provides a service layer but no API controllers or resources. You’ll need to create these manually (e.g., using Laravel’s make:controller).

5. Frontend Dependency:

   • The bundle is tightly coupled with the Cabinet Frontend. If you’re not using the frontend, expect to build your own UI or adapt the API responses.

Debugging Tips

1. Enable Query Logging: Add to config/database.php to debug SQL queries:

   'log' => env('DB_LOG_QUERIES', true),
   'log_query_params' => true,
   

2. Check Event Dispatching: If events aren’t firing, verify the bundle’s EventDispatcher is registered in the service container.

3. Validate Input Early: Use Laravel’s Validator to catch issues before they reach the bundle:

   $validator = Validator::make($request->all(), [
       'email' => 'required|email',
       // ...
   ]);
   

Extension Points

1. Custom Fields: Extend the StudentRecord model (if provided) or override the service to support additional fields:

   class ExtendedRelayCabinetService extends RelayCabinetService {
       public function getStudentRecord(int $id, bool $withCustomFields = false) {
           $record = parent::getStudentRecord($id);
           if ($withCustomFields) {
               $record->custom_field = $this->getCustomField($id);
           }
           return $record;
       }
   }
   

2. Add Indexes: Optimize queries by adding indexes to your student_records table:

   Schema::table('student_records', function (Blueprint $table) {
       $table->index('grade_level');
       $table->index('email');
   });
   

3. Rate Limiting: Protect API endpoints with Laravel’s throttle middleware:

   Route::middleware('throttle:60,1')->group(function () {
       Route::apiResource('students', StudentController::class);
   });
   

4. Caching: Cache frequent queries using Laravel’s cache:

   $students = Cache::remember("students_{$gradeLevel}", now()->addHours(1), function () use ($gradeLevel) {
       return $this->cabinet->findStudentRecords(['grade_level' => $gradeLevel]);
   });