Aih Bundle Laravel Package

Getting Started

Minimal Setup

1. Installation Add the bundle via Composer:

   composer require aih/aih-bundle
   

   Enable it in config/bundles.php:

   return [
       // ...
       AlpesIsereHabitat\AihBundle\AihBundle::class => ['all' => true],
   ];
   

2. Configuration Publish the default config:

   php bin/console config:dump-reference aih
   

   Override settings in config/packages/aih.yaml (e.g., API endpoints, credentials).

3. First Use Case Fetch a user's city via MS Graph (most common entry point):

   use AlpesIsereHabitat\AihBundle\Service\MsGraphService;
   
   class MyController extends AbstractController {
       public function getUserCity(MsGraphService $msGraph): Response {
           $city = $msGraph->getUserCity('user@domain.com');
           return $this->json($city);
       }
   }
   

Implementation Patterns

Core Workflows

1. MS Graph Integration

   • User Data: Fetch cities, departments, or other MS Graph attributes via MsGraphService.
   • Caching: Results are cached by default (TTL configurable). Clear cache with:

     php bin/console cache:clear
     

   • Error Handling: Wrap calls in try-catch for MicrosoftGraphException (e.g., auth failures).

2. Communication Management

   • List Communications:

     $communications = $this->get('aih.communication_service')->getCommunications();
     

   • Bulk Fetch by IDs:

     $commIds = [1, 2, 3];
     $communications = $this->get('aih.communication_service')->getCommunicationsByIds($commIds);
     

3. SMS API

   • Check remaining SMS credits:

     $remainingSms = $this->get('aih.sms_service')->getRemainingSms();
     

4. Health Checks

   • Endpoint: /healthcheck (auto-registered). Use for monitoring:

     $this->get('aih.healthcheck_service')->check();
     

Integration Tips

• Dependency Injection: Prefer autowiring for services (e.g., MsGraphService, CommunicationService).
• Configuration Overrides: Extend aih.yaml for custom API endpoints or timeouts:

  aih:
      ms_graph:
          base_uri: 'https://your-graph-endpoint.com'
          timeout: 30
      cmt_client:
          api_key: '%env(AIH_CMT_API_KEY)%'
  

• GraphQL Queries: Extend existing queries via GraphQLService (see return ?array fix in v0.1.7).

Gotchas and Tips

Pitfalls

1. Symfony Version Mismatch

   • v1.0.0+: Drops Symfony 5 support. Ensure your project uses Symfony 6.2+/7.0+/8.0.
   • Debugging: Check composer.json for required Symfony versions.

2. Caching Quirks

   • Cache keys are prefixed with aih_. Clear manually if stale data persists:

     php bin/console cache:pool:clear cache.app
     

   • TTL: Default is 3600s (1 hour). Adjust in config:

     aih:
         cache_ttl: 7200 # 2 hours
     

3. MS Graph Auth

   • Token Expiry: Handle MicrosoftGraphException for expired tokens. Implement a retry logic or refresh token flow.
   • Null Departments: Wrapped in ?string (v0.1.3). Cast explicitly if needed:

     $department = $msGraph->getUserDepartment('user@domain.com') ?? 'N/A';
     

4. Deprecated Extensions

   • v0.4.0: Extension classes were deprecated. Use service containers directly (e.g., aih.communication_service).

Debugging Tips

• Logs: Enable debug mode to trace API calls:

  monolog:
      handlers:
          main:
              level: debug
  

• Healthcheck: Use the /healthcheck endpoint to verify bundle readiness:

  curl http://localhost:8000/healthcheck
  

Extension Points

1. Custom Clients

   • Extend HappilyApiGdClient or CmtClient for additional APIs. Example:

     class CustomClient extends HappilyApiGdClient {
         public function customMethod() { ... }
     }
     

   • Register as a service:

     services:
         aih.custom_client:
             class: App\Service\CustomClient
             arguments: ['@aih.http_client']
     

2. GraphQL Extensions

   • Override queries in GraphQLService by extending the base class:

     class CustomGraphQLService extends \AlpesIsereHabitat\AihBundle\Service\GraphQLService {
         protected function getCustomQuery(): string { ... }
     }
     

3. Backup Restoration

   • Use the backup:restore command (v0.3.0) for database backups:

     php bin/console aih:backup:restore /path/to/backup.sql