Chatea Client Bundle Laravel Package

Getting Started

Minimal Setup

1. Installation:

   • Add bundles to AppKernel.php:

     new Ant\Bundle\ChateaClientBundle\ChateaClientBundle(),
     new Ant\Bundle\ChateaSecureBundle\ChateaSecureBundle()
     

   • Include routing in config/routing.yml:

     antwebes_chateclient:
         resource: '@ChateaClientBundle/Resources/config/routing.xml'
         prefix: /
     

2. Configuration:

   • Define credentials in config/config.yml:

     chatea_secure:
         app_auth:
             client_id: %chatea_client_id%
             secret: %chatea_secret_id%
             enviroment: %chatea_enviroment%
         api_endpoint: %api_endpoint%
     
     chatea_client:
         app_auth:
             client_id: %chatea_client_id%
             secret: %chatea_secret_id%
         api_endpoint: %api_endpoint%
         app_id: %chatea_app_id%
         authenticate_client_as_guest: false
     

3. Security:

   • Configure firewall in security.yml:

     firewalls:
         secured_area:
             antwebs_chateaclient_login:
                 check_path: _security_check
                 login_path: _antwebes_chateaclient_login
                 provider: antwebs_chateaclient_provider
     

4. First Use Case:

   • Use the @APIUser annotation to authenticate API calls with the logged-in user:

     use Ant\Bundle\ChateaClientBundle\Security\Authentication\Annotation\APIUser;
     
     class UserController {
         /**
          * @APIUser
          */
         public function updateProfileAction() {
             // API calls here will use the logged-in user's token
         }
     }
     

Implementation Patterns

Authentication Workflow

1. Default Behavior:

   • All API calls default to using the application's credentials (not user-specific).
   • Use @APIUser to switch to user-specific authentication.

2. Class-Level Annotation:

   • Apply @APIUser at the class level to enforce user authentication for all methods:

     /**
      * @APIUser
      */
     class RestrictedController {
         // All methods here use user-specific auth
     }
     

3. Guest Authentication:

   • Set authenticate_client_as_guest: true in config to authenticate as a guest user.

Common Use Cases

1. Profile Management:

   • Use UserManager to fetch/update user profiles:

     $userManager = $this->get('chatea_client.user_manager');
     $user = $userManager->findById($userId);
     

2. Photo Handling:

   • Upload/update profile photos with PhotoManager:

     $photoManager = $this->get('chatea_client.photo_manager');
     $photoManager->updatePhoto($userId, $file);
     

3. Search Users:

   • Paginate search results:

     $userManager->searchUserByNamePaginated('query', 1, 10);
     

4. Channels:

   • Manage channel subscriptions:

     $channelManager = $this->get('chatea_client.channel_manager');
     $channelManager->addFanToChannel($channelId, $userId);
     

Integration Tips

1. Twig Globals:

   • Configure base URLs for welcome/login pages:

     twig:
         globals:
             boilerplate_users_base_url: http://yourdomain.com/users
             boilerplate_channels_base_url: http://yourdomain.com/channels
     

2. Redirects:

   • Redirect post-login to the welcome page:

     firewalls:
         secured_area:
             default_target_path: chatea_client_welcome
             always_use_default_target_path: true
     

3. Notifications:

   • Check for incomplete profiles (e.g., missing photos/cities) and notify users:

     $this->get('chatea_client.notification_manager')->checkProfileCompletion($userId);
     

Gotchas and Tips

Pitfalls

1. Deprecated Methods:

   • UserController::confirmedAction is deprecated (use token-based auth instead).

2. Photo Uploads:

   • Ensure photos are ≤1MB. Validate before upload to avoid API errors:

     if ($file->getSize() > 1048576) {
         throw new \RuntimeException('Photo exceeds 1MB limit.');
     }
     

3. Country/City Fields:

   • Country is required during registration. Ensure your form includes it:

     <select name="country" required>
         {% for country in countries %}
             <option value="{{ country.id }}">{{ country.name }}</option>
         {% endfor %}
     </select>
     

4. Guest Authentication:

   • If authenticate_client_as_guest: true, API calls bypass user-specific auth. Verify this is intentional.

5. Token Refresh:

   • Avoid manually refreshing tokens. Use @APIUser to handle it automatically.

Debugging Tips

1. API Errors:

   • Wrap API calls with executeAndHandleApiException to catch malformed responses:

     $result = $manager->executeAndHandleApiException(function() use ($manager) {
         return $manager->findById($userId);
     });
     

2. Profile Completion:

   • Check if a profile is incomplete (e.g., missing gender, about):

     $profileManager->isProfileEmpty($userId, ['gender', 'about']);
     

3. Routing Issues:

   • Ensure routing.xml is properly included. Test routes with:

     php bin/console debug:router | grep chatea
     

Extension Points

1. Custom Templates:

   • Override Twig templates (e.g., register.html.twig) in your theme directory. Key templates:
     • ChateaClientBundle:Registration:register
     • ChateaClientBundle:Profile:edit

2. Event Listeners:

   • Extend the AuthTokenUpdaterListener to customize token handling:

     services:
         app.chatea_token_listener:
             class: AppBundle\EventListener\CustomTokenListener
             tags:
                 - { name: kernel.event_listener, event: kernel.controller, method: onKernelController }
     

3. Validation:

   • Add custom validation to registration forms (e.g., username availability):

     $constraint = new \Symfony\Component\Validator\Constraints\Callback([
         'callback' => [$this, 'validateUsername']
     ]);
     $builder->add('username', $constraint);
     

4. Analytics:

   • Track events (e.g., profile edits) via the analytics.js integration:

     // Example: Track photo uploads
     analytics.track('photo_uploaded', { userId: user.id });
     

Configuration Quirks

1. Environment Variables:

   • Use Symfony’s parameter system for secrets:

     parameters:
         chatea_client_id: %env(CHATEA_CLIENT_ID)%
         chatea_secret_id: %env(CHATEA_SECRET_ID)%
     

2. Recaptcha:

   • Ensure beelab_recaptcha2 is configured if using CAPTCHA:

     beelab_recaptcha2:
         site_key: %recaptcha_public_key%
         secret: %recaptcha_private_key%
         enabled: true
     

3. Countries File:

   • Specify a custom countries file if needed:

     chatea_client:
         countries_file: %kernel.root_dir%/config/countries.json
     

4. Visits Limit:

   • Control how many visits appear on the welcome page:

     chatea_client:
         visits_limit: 5  # Default: 3
     

Performance

1. Pagination:

   • Always paginate user searches to avoid large API responses:

     $users = $userManager->searchUserByNamePaginated('query', $page, $limit);
     

2. Caching:

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

     $cache = $this->get('chatea_client.cache');
     $user = $cache->get("user_{$userId}", function() use ($userId) {
         return $userManager->findById($userId);
     });
     

3. Batch Operations:

   • For bulk operations (e.g., updating multiple users), use the findAll method with filters:

     $users = $userManager->findAll(['filter' => 'active']);