Userbundle Laravel Package

Getting Started

Minimal Steps

1. Installation Add the bundle to your composer.json:

   composer require cekurte/userbundle
   

   Enable it in config/bundles.php:

   return [
       // ...
       Cekurte\UserBundle\CekurteUserBundle::class => ['all' => true],
   ];
   

2. Database Setup Run migrations (if using Doctrine):

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

   The bundle extends FOSUserBundle, so ensure your User entity extends Cekurte\UserBundle\Entity\User.

3. First Use Case Register a new user via the built-in registration form (Bootstrap 3 templates included):

   php bin/console fos:user:create
   

   Access /register in your browser to test the registration flow.

Where to Look First

• Documentation: Check Resources/doc/index.md for setup and configuration.
• Templates: Bootstrap 3 templates are in Resources/views/FOSUserBundle/ (override these in your project).
• Routing: Default routes are defined in Resources/config/routing.yml (extend or override as needed).

Implementation Patterns

Core Workflows

1. User Management

   • Use Symfony’s built-in commands for user CRUD:

     php bin/console fos:user:create --super-admin  # Admin user
     php bin/console fos:user:list                 # List users
     

   • Customize user fields by extending Cekurte\UserBundle\Entity\User:

     use Cekurte\UserBundle\Entity\User as BaseUser;
     
     class User extends BaseUser {
         // Add custom fields/methods
     }
     

2. OAuth Integration (HWIOAuthBundle)

   • Configure hwioauth_bundle in config/packages/hwioauth_bundle.yaml:

     hwioauth_bundle:
         resources:
             - "CekurteUserBundle::oauth"
     

   • Add providers (e.g., Facebook) in config/packages/cekurte_user.yaml:

     cekurte_user:
         oauth:
             facebook:
                 app_id: "your_app_id"
                 app_secret: "your_secret"
     

   • Use the /login/check-{provider} route (e.g., /login/check-facebook).

3. Template Overrides Override Bootstrap 3 templates by copying files from:

   vendor/cekurte/userbundle/Resources/views/FOSUserBundle/
   

   to:

   templates/FOSUserBundle/
   

   Example: Override registration.html.twig for custom styling.

4. Event Listeners Extend functionality via Symfony events (e.g., fos_user_registered):

   // src/EventListener/UserListener.php
   namespace App\EventListener;
   
   use FOS\UserBundle\FOSUserEvents;
   use Symfony\Component\EventDispatcher\EventSubscriberInterface;
   
   class UserListener implements EventSubscriberInterface {
       public static function getSubscribedEvents() {
           return [
               FOSUserEvents::REGISTERED => 'onUserRegistered',
           ];
       }
   
       public function onUserRegistered($event) {
           // Custom logic (e.g., send welcome email)
       }
   }
   

Integration Tips

• Security Ensure security.yaml includes the bundle’s firewall:

  firewalls:
      main:
          form_login:
              provider: fos_userbundle
          logout: true
          anonymous: true
  

• Asset Management Bundle includes Bootstrap 3 CSS/JS. Load them in base.html.twig:

  {{ encore_entry_link_tags('app') }}
  {{ cekurte_user_assets() }}  {# If bundle provides helper #}
  

• Custom Routes Extend routing in config/routes.yaml:

  cekurte_user:
      resource: "@CekurteUserBundle/Resources/config/routing.yml"
      prefix:   /
  

Gotchas and Tips

Pitfalls

1. Namespace Conflicts

   • The bundle extends FOSUserBundle. If you’re using a custom User entity, ensure it only extends Cekurte\UserBundle\Entity\User (not FOS\UserBundle\Model\User directly).
   • Fix: Clear cache after extending the entity:

     php bin/console cache:clear
     

2. OAuth Misconfiguration

   • HWIOAuthBundle must be installed (composer require hwioauth/bundle).
   • Error: ServiceNotFoundException for OAuth services.
   • Fix: Verify hwioauth_bundle is enabled in bundles.php and config is correct.

3. Template Caching

   • Overridden templates may not reflect changes if cached. Use:

     php bin/console assets:install
     php bin/console cache:clear
     

4. Deprecated FOSUserBundle Methods

   • The bundle may lag behind FOSUserBundle updates. Check the FOSUserBundle docs for breaking changes.

Debugging

1. Enable Debug Mode Set APP_DEBUG=true in .env to see detailed errors (e.g., OAuth failures).

2. Check Logs

   • OAuth logs: var/log/dev.log (look for HWI entries).
   • User events: Enable fos_user logging in config/packages/monolog.yaml:

     handlers:
         fos_user:
             type: stream
             path: "%kernel.logs_dir%/fos_user.log"
             level: debug
             channels: ["fos_user"]
     

3. Common Errors

   • 404 on /register: Missing route or template. Verify routing.yml and template paths.
   • OAuth Redirect Loop: Invalid app_id/app_secret in cekurte_user.yaml.
   • CSRF Token Errors: Ensure {{ csrf_token('fos_user_registration_register') }} is in forms.

Extension Points

1. Custom User Fields Add fields to the User entity and update the form type:

   // src/Form/RegistrationFormType.php
   namespace App\Form;
   
   use Cekurte\UserBundle\Form\Type\RegistrationFormType as BaseType;
   use Symfony\Component\Form\AbstractType;
   use Symfony\Component\Form\FormBuilderInterface;
   
   class RegistrationFormType extends BaseType {
       public function buildForm(FormBuilderInterface $builder, array $options) {
           parent::buildForm($builder, $options);
           $builder->add('custom_field', TextType::class);
       }
   }
   

   Update services.yaml to override the form:

   services:
       App\Form\RegistrationFormType: ~
   

2. Custom OAuth Providers Extend HWIOAuthBundle’s provider logic in a custom bundle or service.

3. Email Templates Override Twig templates for emails (e.g., registration.html.twig) in:

   templates/FOSUserBundle/Registration/
   

4. Validation Rules Add constraints to the User entity:

   use Symfony\Component\Validator\Constraints as Assert;
   
   /**
    * @Assert\NotBlank
    * @Assert\Length(min=8)
    */
   private $customField;
   

Configuration Quirks

1. Bootstrap Assets The bundle assumes Bootstrap 3 is installed via encore or manually. If missing, add:

   yarn add bootstrap@3
   

   Or include manually in base.html.twig.

2. Locale Support The bundle inherits FOSUserBundle’s locale settings. Override in config/packages/fos_user.yaml:

   fos_user:
       locale: pt_BR
   

3. Super Admin Role The fos:user:create --super-admin command grants the ROLE_SUPER_ADMIN role. Ensure your firewall allows it:

   access_control:
       - { path: ^/admin, roles: ROLE_SUPER_ADMIN }