Uca Office365 Laravel Package

Getting Started

Minimal Setup

1. Installation

   composer require bcedric/uca-office365:dev-main
   

   Register the bundle in config/bundle.php:

   BCedric\UCAOffice365\BCedricUCAOffice365Bundle::class => ['all' => true],
   

2. Environment Configuration Add these to your .env (choose one service):

   • For GraphAPI (Microsoft):

     GRAPH_TENANT=your_tenant_id
     GRAPH_CLIENT=your_client_id
     GRAPH_CLIENT_SECRET=your_client_secret
     PROXY_URL=http://your_proxy_url
     

   • For UCAOffice365 (internal API):

     APIO365_URL=https://your-api-url
     APIO365_LOGIN=your_login
     APIO365_PASSWORD=your_password
     

3. First Use Case Inject the service in a controller/service and call a method:

   use BCedric\UCAOffice365\Service\UCAOffice365;
   
   public function __construct(private UCAOffice365 $ucaOffice365) {}
   
   public function fetchUserData(string $uid) {
       return $this->ucaOffice365->getUser($uid);
   }
   

Implementation Patterns

Core Workflows

1. User Management

   • CRUD Operations: Use getUser(), createUser(), and deleteUser() for basic user lifecycle.
   • Booking Toggle: Enable/disable booking options with addBooking() and removeBooking().
   • Example:

     $user = $this->ucaOffice365->getUser('user123');
     $this->ucaOffice365->addBooking('user123'); // Enable booking
     

2. Calendar Integration

   • Retrieve calendar URLs for users/groups:

     $calendarUrl = $this->ucaOffice365->getCalendarURL($uid, $startDate, $endDate);
     

   • Use with Microsoft Graph API for deeper calendar operations (e.g., event creation).

3. Proxy Handling

   • Configure PROXY_URL in .env if your app routes through a proxy for Office365 API calls.

4. Error Handling

   • Wrap calls in try-catch blocks to handle API failures gracefully:

     try {
         $user = $this->ucaOffice365->getUser($uid);
     } catch (\Exception $e) {
         // Log or notify (e.g., Slack/email)
         throw new \RuntimeException("Failed to fetch user: " . $e->getMessage());
     }
     

Integration Tips

1. Dependency Injection

   • Prefer constructor injection for services:

     public function __construct(
         private UCAOffice365 $ucaOffice365,
         private GraphAPI $graphApi // If using Microsoft Graph
     ) {}
     

2. Command Bus Pattern

   • For complex workflows (e.g., bulk user updates), create console commands:

     use Symfony\Component\Console\Command\Command;
     use Symfony\Component\Console\Input\InputInterface;
     use Symfony\Component\Console\Output\OutputInterface;
     
     class SyncUsersCommand extends Command {
         protected function execute(InputInterface $input, OutputInterface $output) {
             $users = $this->ucaOffice365->getAllUsers(); // Hypothetical method
             foreach ($users as $user) {
                 $this->ucaOffice365->addBooking($user['uid']);
             }
             $output->writeln('Booking enabled for all users.');
         }
     }
     

3. Event-Driven Extensions

   • Listen for user events (e.g., UserCreated) to trigger Office365 actions:

     // In a subscriber or event listener
     public function onUserCreated(UserCreatedEvent $event) {
         $this->ucaOffice365->createUser($event->getUser()->getId());
     }
     

4. Caching

   • Cache frequent API calls (e.g., user data) using Laravel’s cache:

     $user = Cache::remember("user_{$uid}", now()->addHours(1), function() use ($uid) {
         return $this->ucaOffice365->getUser($uid);
     });
     

Gotchas and Tips

Pitfalls

1. Authentication Failures

   • Issue: Missing or incorrect .env variables cause silent failures.
   • Fix: Validate credentials early (e.g., in a health check route):

     Route::get('/health', function () {
         try {
             $this->ucaOffice365->getUser('test123');
             return response()->json(['status' => 'healthy']);
         } catch (\Exception $e) {
             return response()->json(['status' => 'unhealthy', 'error' => $e->getMessage()], 500);
         }
     });
     

2. Rate Limiting

   • Issue: The internal UCA API may throttle requests.
   • Fix: Implement exponential backoff in retries:

     use Symfony\Component\Process\Exception\TimeoutException;
     
     try {
         $user = $this->ucaOffice365->getUser($uid);
     } catch (TimeoutException $e) {
         sleep(2); // Wait before retry
         $user = $this->ucaOffice365->getUser($uid);
     }
     

3. Proxy Dependencies

   • Issue: PROXY_URL may break if the proxy is down.
   • Fix: Add a fallback mechanism or circuit breaker:

     if (env('USE_PROXY') && !filter_var(env('PROXY_URL'), FILTER_VALIDATE_URL)) {
         throw new \RuntimeException('Proxy URL is invalid. Disabling proxy.');
     }
     

4. Data Mismatches

   • Issue: User IDs or attributes may differ between your app and Office365.
   • Fix: Normalize data on ingestion:

     $userData = $this->ucaOffice365->getUser($uid);
     $normalizedUser = [
         'id' => strtolower($userData['uid']),
         'email' => strtolower($userData['email'] ?? ''),
     ];
     

Debugging Tips

1. Enable Verbose Logging

   • Add this to config/services.php to log API requests:

     'uca_office365' => [
         'debug' => env('APP_DEBUG', false),
     ],
     

   • Check logs in storage/logs/laravel.log for raw API responses.

2. Mocking for Tests

   • Use Laravel’s HTTP client to mock API responses:

     $this->mock(UCAOffice365::class)
         ->shouldReceive('getUser')
         ->once()
         ->andReturn(['uid' => 'test123', 'name' => 'Test User']);
     

3. API Response Inspection

   • Dump raw responses to debug:

     $response = $this->ucaOffice365->getUser($uid);
     \Log::debug('Raw API Response:', ['response' => $response]);
     

Extension Points

1. Custom API Endpoints

   • Extend the UCAOffice365 service by creating a decorator:

     class ExtendedUCAOffice365 extends UCAOffice365 {
         public function getCustomUserData($uid) {
             $user = parent::getUser($uid);
             return array_merge($user, ['custom_field' => 'value']);
         }
     }
     

   • Bind the decorator in config/services.php:

     'uca_office365' => [
         'class' => \App\Services\ExtendedUCAOffice365::class,
     ],
     

2. GraphAPI Integration

   • Combine with Microsoft Graph for advanced features:

     $events = $this->graphApi->getEvents($user['mail'], new \DateTime());
     

3. Webhook Listeners

   • Listen for Office365 webhooks (e.g., user updates) via a queue worker:

     public function handle(Office365Webhook $event) {
         $this->ucaOffice365->syncUser($event->getUserId());
     }
     

4. Batch Processing

   • Process large datasets in chunks to avoid timeouts:

     $users = $this->ucaOffice365->getAllUsers();
     foreach (array_chunk($users, 50) as $chunk) {
         foreach ($chunk as $user) {
             $this->ucaOffice365->addBooking($user['uid']);
         }
     }