Cms User Bundle Laravel Package

Getting Started

First Steps

1. Installation Add the bundle via Composer:

   composer require canabelle/cms-user-bundle
   

   Register the bundle in config/bundles.php (Symfony):

   return [
       // ...
       Canabelle\CMSUserBundle\CanabelleCMSUserBundle::class => ['all' => true],
   ];
   

2. Publish Assets Run the following to publish migrations, config, and translations:

   php bin/console canabelle:cms-user:install
   

   This creates:

   • Database migrations (database/migrations/...)
   • Configuration (config/packages/canabelle_cms_user.yaml)
   • Translations (if applicable)

3. Run Migrations

   php bin/console doctrine:migrations:migrate
   

4. Basic Usage The bundle provides a User entity (likely extending Symfony’s UserInterface). Check the generated User class in src/Entity/User.php (or app/Entity/User.php if using legacy structure). Example of fetching a user:

   use Canabelle\CMSUserBundle\Entity\User;
   
   $user = $entityManager->getRepository(User::class)->find(1);
   

5. Routing & Controllers The bundle may include basic CRUD routes (check config/routes/canabelle_cms_user.yaml or src/Kernel.php for registration). Override or extend these in your own controllers if needed.

Implementation Patterns

Common Workflows

1. User Management

   • Registration: Extend the bundle’s registration logic by overriding the RegistrationController or creating a custom form type.

     // Example: Custom registration form
     namespace App\Form;
     use Symfony\Component\Form\AbstractType;
     use Canabelle\CMSUserBundle\Form\UserType;
     
     class CustomUserType extends UserType {
         public function buildForm(FormBuilderInterface $builder, array $options) {
             parent::buildForm($builder, $options);
             $builder->add('custom_field', TextType::class);
         }
     }
     

   • Authentication: Use Symfony’s security system with the bundle’s User entity. Configure firewalls in config/packages/security.yaml:

     firewalls:
         main:
             form_login:
                 login_path: canabelle_cms_user_login
                 check_path: canabelle_cms_user_login_check
     

2. Role-Based Access The bundle likely uses Symfony’s role hierarchy. Assign roles in the User entity or via a listener:

   $user->setRoles(['ROLE_USER', 'ROLE_CMS_EDITOR']);
   $entityManager->persist($user);
   

3. Profile Management Extend the User entity to add custom fields (e.g., avatar, bio):

   // src/Entity/User.php
   /**
    * @ORM\Column(type="string", length=255, nullable=true)
    */
   private $avatar;
   

   Update the form type (UserType) to include these fields.

4. API Integration If using API Platform or similar, expose the User entity with serialization groups:

   use Symfony\Component\Serializer\Annotation\Groups;
   
   class User {
       /**
        * @Groups({"user:read"})
        */
       public $email;
   }
   

5. Event Listeners Hook into user lifecycle events (e.g., PrePersist, PostUpdate) via Symfony events:

   // src/EventListener/UserListener.php
   namespace App\EventListener;
   use Canabelle\CMSUserBundle\Entity\User;
   use Doctrine\ORM\Event\LifecycleEventArgs;
   
   class UserListener {
       public function prePersist(User $user, LifecycleEventArgs $args) {
           $user->setCreatedAt(new \DateTime());
       }
   }
   

   Register the listener in services.yaml:

   services:
       App\EventListener\UserListener:
           tags:
               - { name: doctrine.event_listener, event: prePersist }
   

Integration Tips

• Custom Templates: Override Twig templates in templates/canabelle_cms_user/ to modify login/registration views.
• Validation: Extend the User entity’s validation constraints:

  use Symfony\Component\Validator\Constraints as Assert;
  
  class User {
      /**
       * @Assert\NotBlank
       * @Assert\Length(min=8)
       */
      private $plainPassword;
  }
  

• Doctrine Extensions: Use StoDoctrineExtensionsBundle for soft deletes or timestamps if the bundle doesn’t include them natively.
• Testing: Mock the User entity in PHPUnit tests:

  $user = $this->createMock(User::class);
  $user->method('getRoles')->willReturn(['ROLE_USER']);
  

Gotchas and Tips

Pitfalls

1. Outdated Codebase

   • The last release was in 2018, so:
     • Symfony 5/6 compatibility: Test thoroughly. May require patches (e.g., make:auth changes in Symfony 5+).
     • Doctrine ORM: Assumes older Doctrine versions (e.g., lifecycle_callbacks may need adjustment for newer versions).
   • Solution: Fork the repo and update dependencies incrementally.

2. Missing Documentation

   • No built-in docs or examples. Key classes to inspect:
     • Canabelle\CMSUserBundle\Entity\User
     • Canabelle\CMSUserBundle\Form\UserType
     • Canabelle\CMSUserBundle\Controller\RegistrationController
   • Tip: Use php bin/console debug:container Canabelle\CMSUserBundle to list services.

3. Hardcoded Configurations

   • Some paths (e.g., template locations) may be hardcoded. Override via configuration:

     # config/packages/canabelle_cms_user.yaml
     canabelle_cms_user:
         templates:
             registration: 'custom/path/registration.html.twig'
     

4. Security Risks

   • Default implementations may lack modern security features (e.g., password hashing with argon2i). Update the UserPasswordHasher service:

     services:
         Symfony\Component\Security\Core\Encoder\UserPasswordHasher:
             arguments:
                 - '@security.user_password_hasher.legacy'
     

5. Migration Conflicts

   • If the bundle’s migrations conflict with existing ones, manually adjust the User table schema or use doctrine:migrations:diff to generate a custom migration.

Debugging Tips

1. Enable Debug Mode Set APP_DEBUG=true in .env to see detailed errors (e.g., missing templates or services).

2. Check Event Dispatchers Use debug:event-dispatcher to verify if bundle events (e.g., user.registered) are firing:

   php bin/console debug:event-dispatcher
   

3. Database Schema Issues Dump the schema to compare with the bundle’s expectations:

   php bin/console doctrine:schema:update --dump-sql
   

4. Symfony Profiler Use the profiler to inspect:

   • Twig template rendering (for login/registration pages).
   • Doctrine queries (slow user lookups).

Extension Points

1. Custom User Provider Replace the default user provider (e.g., for LDAP or API-based auth):

   security:
       providers:
           custom_user_provider:
               id: App\Security\CustomUserProvider
   

2. Add Fields Dynamically Use Doctrine extensions or traits to add fields without modifying the User entity directly:

   // src/Entity/UserTrait.php
   trait UserTrait {
       private $customField;
       // Getters/setters...
   }
   

3. Override Controllers Extend or replace controllers (e.g., RegistrationController) by defining your own service with the same interface.

4. Custom Roles Define roles in security.yaml and assign them via a listener:

   security:
       role_hierarchy:
           ROLE_CMS_ADMIN: [ROLE_USER, ROLE_CMS_EDITOR]
   

5. API Tokens Integrate with lexik/jwt-authentication-bundle for token-based auth:

   composer require lexik/jwt-authentication-bundle
   

   Configure in security.yaml to work with the bundle’s User entity.

Pro Tips

• Use Symfony’s MakerBundle to scaffold custom user-related commands or CRUD operations alongside the bundle.
• Leverage Symfony UX for modern frontend integration (e.g., Turbo Links for profile updates).
• Monitor Deprecations: If upgrading Symfony, check deprecation-notices in logs for bundle-specific warnings.