Chatea Secure Bundle Laravel Package

Getting Started

Minimal Setup

1. Install the Bundle Add the bundle to your composer.json:

   composer require antwebes/chatea-secure-bundle
   

   Register the bundle in config/bundles.php:

   return [
       // ...
       Antwebes\ChateaSecureBundle\AntwebesChateaSecureBundle::class => ['all' => true],
   ];
   

2. Configure the Bundle Add Chatea API credentials to config/packages/antwebes_chatea_secure.yaml:

   antwebes_chatea_secure:
       api_key: '%env(CHATEA_API_KEY)%'
       api_secret: '%env(CHATEA_API_SECRET)%'
       homepage_path: '/dashboard'  # Optional: Redirect path after login
   

3. First Use Case: Login Integration Use the built-in login form by adding the route to your routes.yaml:

   antwebes_chatea_secure_login:
       path: /login
       controller: Antwebes\ChateaSecureBundle\Controller\SecurityController::loginAction
   

   Customize the login template by extending AntwebesChateaSecureBundle:Security:login.html.twig.

Implementation Patterns

Workflow: User Authentication

1. Login Flow

   • Users access /login (default route).
   • The bundle handles form submission, validates credentials, and redirects to homepage_path on success.
   • On failure, it throws UsernameNotFoundException (Symfony handles this via security.yaml error handlers).

2. Auto-Login (Token-Based) Append ?autologin=<access_token> to a URL to auto-login users without a form:

   // Redirect with token (e.g., from an email link)
   return $this->redirectToRoute('home', [
       'autologin' => $user->getChateaAccessToken(),
   ]);
   

   The bundle checks the token against the current user’s token and logs them in if valid.

3. API Integration Use the underlying ChateaClient via the bundle’s service:

   // In a controller/service
   $chateaClient = $this->container->get('antwebes_chatea.client');
   $response = $chateaClient->getUserInfo($userId);
   

4. Form Customization Extend the login form in your template:

   {% extends 'AntwebesChateaSecureBundle:Security:login.html.twig' %}
   {% block form_label_username %}{% trans %}Nombre de usuario o email{% endtrans %}{% endblock %}
   

Integration Tips

• Symfony Security Integration Configure security.yaml to handle the UsernameNotFoundException:

  firewalls:
      main:
          form_login:
              login_path: antwebes_chatea_secure_login
              check_path: antwebes_chatea_secure_login_check
              default_target_path: homepage_path
          logout:
              path: antwebes_chatea_secure_logout
  

• Event Listeners Subscribe to chatea.login.success events to trigger post-login actions:

  // src/EventListener/ChateaLoginListener.php
  public function onLoginSuccess(LoginSuccessEvent $event) {
      // Custom logic (e.g., sync user data)
  }
  

  Register the listener in services.yaml:

  services:
      App\EventListener\ChateaLoginListener:
          tags:
              - { name: kernel.event_listener, event: chatea.login.success }
  

Gotchas and Tips

Pitfalls

1. Token Mismatch in Auto-Login

   • If autologin token doesn’t match the user’s stored token, the user is not logged in (silently fails). Verify tokens server-side before redirecting.

2. Locked Accounts

   • The bundle returns raw API error responses for locked accounts (e.g., {"error": "user_locked"}). Handle this in your security.yaml exception listener:

     // src/EventListener/ExceptionListener.php
     public function onKernelException(GetResponseForExceptionEvent $event) {
         $exception = $event->getThrowable();
         if ($exception instanceof UsernameNotFoundException) {
             $response = $exception->getResponse();
             if (strpos($response->getContent(), 'user_locked') !== false) {
                 $event->setResponse(new Response('Cuenta bloqueada. Contacta al soporte.'));
             }
         }
     }
     

3. Deprecated Guzzle Version

   • The bundle requires Guzzle ~3.7, which may conflict with newer Symfony projects. Pin Guzzle in composer.json:

     "require": {
         "guzzle/guzzle": "3.7.*"
     }
     

4. Translation Keys

   • Error messages (e.g., "Credenciales incorrectas") rely on Symfony’s translation system. Ensure your translations/messages.en.yaml includes:

     'Incorrect credentials.': 'Credenciales incorrectas.'
     'Username or email': 'Nombre de usuario o email'
     

Debugging Tips

1. Enable API Debugging Temporarily log raw API responses in GuzzleHttpAdapter (override the service):

   services:
       antwebes_chatea.client:
           class: Antwebes\ChateaSecureBundle\Client\ChateaClient
           arguments:
               - '@antwebes_chatea.http_adapter'
           calls:
               - [setDebug, [true]]
   

2. Check Token Storage Verify tokens are stored in the user entity (e.g., User::setChateaToken()). The bundle expects:

   // src/Entity/User.php
   private $chateaAccessToken;
   

3. Form Validation Ensure your login form includes csrf_token and validates fields:

   {{ form_start(form, {'attr': {'novalidate': 'novalidate'}}) }}
       {{ form_row(form._token) }}
       {{ form_row(form.username) }}
       {{ form_row(form.password) }}
   {{ form_end(form) }}
   

Extension Points

1. Custom HTTP Adapter Extend GuzzleHttpAdapter to add retry logic or headers:

   // src/Client/CustomHttpAdapter.php
   class CustomHttpAdapter extends \Antwebes\ChateaSecureBundle\Client\HttpAdapter\GuzzleHttpAdapter {
       protected function getDefaultOptions() {
           $options = parent::getDefaultOptions();
           $options['headers']['X-Custom-Header'] = 'value';
           return $options;
       }
   }
   

   Override the service in services.yaml:

   services:
       antwebes_chatea.http_adapter:
           class: App\Client\CustomHttpAdapter
   

2. Add API Endpoints Use the bundle’s ChateaClient to wrap additional API calls:

   // src/Service/ChateaService.php
   public function getUserMessages($userId) {
       return $this->chateaClient->callApi('GET', "/users/{$userId}/messages");
   }
   

3. Remember-Me Feature Leverage Symfony’s remember_me firewall option (configured in security.yaml) alongside the bundle’s autologin for persistent sessions.