User Bundle Laravel Package

Getting Started

Minimal Setup

1. Installation

   composer require aescarcha/user-bundle
   php bin/console cache:clear
   

2. Configure config.yml Update with the provided snippet, replacing placeholders (Your-client-id, your-client-secret) with actual Facebook OAuth credentials.

3. Enable Bundles Ensure AescarchaUserBundle is enabled in app/AppKernel.php:

   new Aescarcha\UserBundle\AescarchaUserBundle(),
   new FOS\UserBundle\FOSUserBundle(),
   new FOS\RestBundle\FOSRestBundle(),
   

4. First Use Case: User Registration Extend the default registration form by creating a custom type (app_user_profile):

   php bin/console generate:fos:user
   

   Override User entity if needed (e.g., add custom fields).

5. REST API Endpoint Test the API endpoint (default: /api/users):

   curl -X GET http://your-app/api/users -H "Authorization: Bearer YOUR_TOKEN"
   

Implementation Patterns

Workflows

1. User Authentication & OAuth

• Facebook Login Flow:

  • Configure hwi_oauth routes (e.g., /login/check-facebook).
  • Use FOSUserBundle's built-in OAuth logic with HWI.
  • Customize user data mapping in fosub (e.g., facebookId field).

  hwi_oauth:
    fosub:
      properties:
        facebook: facebookId  # Maps Facebook ID to User entity
  

• Post-OAuth User Creation: Override Aescarcha\UserBundle\Services\CustomFOSUBUserProvider to handle custom logic (e.g., role assignment):

  public function connect(User $user, $resourceOwnerId)
  {
      $user->setFacebookId($resourceOwnerId);
      $user->addRole('ROLE_USER');
      $this->userManager->updateUser($user);
  }
  

2. REST API Integration

• Fractal Serialization: Customize serializers for User entity in src/Aescarcha/UserBundle/Resources/config/fractal.yml:

  fractal:
    transformers:
      user:
        include: [id, email, facebookId, createdAt]
  

  Access via /api/users with JSON responses.

• API Routes: Extend routing.yml for custom endpoints:

  api_users:
      path: /api/users/{id}
      defaults: { _controller: aescarcha_user.controller.user:getUser }
      requirements:
          id: \d+
  

3. Entity Extensions

• Custom Fields: Extend the User entity (e.g., src/Aescarcha/UserBundle/Entity/User.php):

  /**
   * @ORM\Column(type="string", nullable=true)
   */
  private $facebookId;
  

  Update migrations and doctrine schema:

  php bin/console doctrine:schema:update --force
  

• Profile Management: Use app_user_profile form type to add fields (e.g., birthday, locale):

  // src/AppBundle/Form/Type/AppUserProfileType.php
  $builder->add('birthday', DateType::class);
  

Integration Tips

Symfony Security

• Secure API routes with fos_rest:

  # config/security.yml
  firewalls:
      secured_area:
          pattern: ^/api
          fos_oauth: true
          stateless: true
  

Event Listeners

• Hook into user lifecycle events (e.g., post-registration):

  // src/Aescarcha/UserBundle/EventListener/UserListener.php
  public function onUserRegistered(UserEvent $event)
  {
      $user = $event->getUser();
      $user->addRole('ROLE_ACTIVE');
      $this->userManager->updateUser($user);
  }
  

  Register in services.yml:

  services:
      aescarcha_user.listener.user:
          class: Aescarcha\UserBundle\EventListener\UserListener
          tags:
              - { name: kernel.event_listener, event: fos_user.registered, method: onUserRegistered }
  

Testing

• Use HWIOAuthBundle's test clients for OAuth flows:

  $client = static::createClient([
      'environment' => ['HWI_OAUTH_CONNECT' => 'facebook'],
  ]);
  $crawler = $client->request('GET', '/login/check-facebook');
  

Gotchas and Tips

Pitfalls

1. Configuration Overrides

• Issue: fos_user.user_class must point to Aescarcha\UserBundle\Entity\User. Fix: Ensure no other bundle overrides this in config.yml.

  fos_user:
      user_class: Aescarcha\UserBundle\Entity\User  # Critical!
  

2. HWI OAuth Misconfigurations

• Issue: Facebook login fails silently if infos_url fields are invalid. Fix: Validate the infos_url fields against Facebook Graph API docs. Example:

  infos_url: "https://graph.facebook.com/me?fields=id,name,email,picture.type(square)"  # Minimal viable set
  

3. REST API CORS

• Issue: API endpoints may block requests from frontend. Fix: Configure CORS in config.yml:

  fos_rest:
      param_fetcher_listener: true
      body_listener: true
      format_listener: true
      view:
          view_response_listener: 'force'
      routing_loader:
          default_format: json
      exception:
          enabled: true
      allowed_methods_listener: true
      access_denied_listener:
          json: true
      cors:
          enabled: true
          allow_origin: ["*"]
          allow_methods: ["GET", "POST", "PUT", "DELETE", "OPTIONS"]
          allow_headers: ["Content-Type", "Authorization"]
          expose_headers: ["Link"]
          max_age: 86400
  

4. Doctrine Migrations

• Issue: Adding custom fields to User entity may break migrations. Fix: Use doctrine:migrations:diff and review changes:

  php bin/console doctrine:migrations:diff
  php bin/console doctrine:migrations:migrate
  

5. Fractal Serialization Conflicts

• Issue: API returns unexpected fields due to missing transformers. Fix: Explicitly define transformers in fractal.yml:

  fractal:
      transformers:
          user:
              include: [id, email, facebookId]  # Whitelist fields
  

Debugging Tips

1. OAuth Debugging

• Enable HWI debug mode in config.yml:

  hwi_oauth:
      debug: true  # Logs OAuth requests/responses
  

• Check logs for hwi_oauth errors in var/log/dev.log.

2. REST API Debugging

• Use fos:rest:debug to inspect routes and formats:

  php bin/console fos:rest:debug
  

• Validate Fractal responses with:

  curl -v http://your-app/api/users
  

3. Event Debugging

• Dump events in listeners:

  public function onUserRegistered(UserEvent $event)
  {
      dump($event->getUser());  // Debug user data
  }
  

Extension Points

1. Custom User Provider

• Extend CustomFOSUBUserProvider for complex OAuth logic:

  // src/Aescarcha/UserBundle/Services/CustomFOSUBUserProvider.php
  public function connect(User $user, $resourceOwnerId)
  {
      // Custom logic (e.g., sync with external API)
      $user->setExternalId($resourceOwnerId);
      $this->userManager->updateUser($user);
  }
  

2. Dynamic API Fields

• Use Fractal include parameters for dynamic responses:

  // In your controller
  $serializer = $this->get('fractal.manager');
  $data = $serializer->createData($user)->toArray();
  return $this->handleView($this->view($data, 200));
  

3. Role-Based API Access

• Secure API endpoints with voter logic:

  // src/Aescarcha/UserBundle/Security/Voter/UserVoter.php
  public function supportsAttribute($attribute)
  {
      return in_array($attribute, ['EDIT', 'DELETE']);
  }
  

  Register in security.yml:

  access_control:
      - { path: ^/api/users, roles: [ROLE_ADMIN] }
  

4. Webhook Integration

• Trigger