User Bundle Laravel Package

Getting Started

Minimal Steps to Begin

1. Installation

   composer require c975l/user-bundle
   

   Ensure v3.x for Symfony 4.x or v2.x for Symfony 3.x.

2. Configure Security Update config/packages/security.yml to specify your chosen User entity (e.g., User, UserAddress, UserBusiness) and define role hierarchies:

   security:
       encoders:
           c975L\UserBundle\Entity\User: auto
       providers:
           c975_l_userbundle:
               entity:
                   class: c975L\UserBundle\Entity\User
   

3. Database Setup Run the SQL script from /Resources/sql/user.sql to create user and user_archives tables.

4. Enable Routes Add to config/routes.yaml:

   c975_l_user:
       resource: "@c975LUserBundle/Controller/"
       type: annotation
       prefix: /
   

5. Install Assets

   php bin/console assets:install --symlink
   

6. First Use Case Access /user_signup to test the registration flow. Override templates in /templates/bundles/c975LUserBundle/ (e.g., layout.html.twig) to customize the UI.

Implementation Patterns

Core Workflows

1. User Management

   • Registration: Extend UserSignupType to add custom fields (e.g., src/App/Form/UserSignupType).
   • Profile Updates: Override UserProfileType to modify editable fields (e.g., disable fields during signup).
   • Password Reset: Leverage the built-in /user_reset_password route; customize the email template via c975LEmailBundle.

2. GDPR Compliance

   • Data Export: Use /user_export to provide users with their data in JSON/CSV.
   • Opt-Out: Disable user accounts via allow_use flag (set to false in UserAbstract).

3. Social Logins

   • Configure HWIOAuthBundle (e.g., Facebook/Google) and enable in config_bundles.yaml:

     c975LUser:
         hwiOauth: ['facebook', 'google']
         social: true
     

   • Add OAuth routes to routes.yaml and register OAuthUserProvider in services.yaml.

4. API Integration Use the built-in API endpoints (e.g., /api/user) for JSON-based CRUD operations. Authenticate via JWT (configure lcobucci/jwt).

5. Event-Driven Extensions Subscribe to events (e.g., UserEvent::USER_DELETE) to trigger custom logic:

   // src/EventListener/UserDeleteListener.php
   public static function getSubscribedEvents() {
       return [UserEvent::USER_DELETE => 'onUserDelete'];
   }
   

Integration Tips

• Twig Extensions: Use user_divData() to pass user data to JavaScript or user_avatar() for profile pictures.
• Validation: Extend entities to add custom validators (e.g., for business_siret).
• Localization: Support multilingual fields via UserFull entity or override templates with _locale routing.
• Security: Enable rate-limiting for login attempts via security.yml:

  firewalls:
      main:
          form_login:
              check_path: user_signin
              failure_path: user_signin_failure
  

Gotchas and Tips

Pitfalls

1. Entity Selection

   • Mismatch Errors: Ensure the security.yml class matches your extended entity (e.g., App\Entity\User).
   • Field Overrides: If extending UserAbstract, ensure all required fields (e.g., email, roles) are preserved.

2. Template Overrides

   • Path Conflicts: Place overrides in /templates/bundles/c975LUserBundle/ to avoid Symfony’s cache issues.
   • Missing Fragments: Override navbarMenuActions.html.twig if extending the navbar without full template duplication.

3. Social Login Quirks

   • HWIOAuthBundle Dependency: Configure OAuth providers separately (e.g., Facebook app IDs in parameters.yml).
   • Token Storage: Social tokens (social_token) are stored in the UserSocial entity but require manual HWIOAuth setup.

4. API Limitations

   • JWT Configuration: Ensure lcobucci/jwt is installed and configured for API auth.
   • CORS: Explicitly configure CORS for API routes if accessed from frontend frameworks.

5. GDPR Edge Cases

   • Data Deletion: Use sp_UserArchive() stored procedure to archive user data before deletion.
   • Email Validation: The reset password form does not validate email existence (design choice).

Debugging Tips

• Route Conflicts: Clear cache (php bin/console cache:clear) after adding routes or services.
• Form Errors: Check UserProfileType/UserSignupType for field constraints (e.g., business_siret requires validation).
• Event Propagation: Use $event->stopPropagation() in listeners to halt default behavior (e.g., during deletion).

Extension Points

1. Custom Fields Extend UserAbstract and update UserProfileType:

   // src/App/Entity/CustomUser.php
   class CustomUser extends UserAbstract {
       private $customField;
       // Add getter/setter + validation.
   }
   

2. Email Templates Override c975LEmailBundle templates (e.g., reset_password.html.twig) in /templates/bundles/c975LEmailBundle/.

3. Dashboard Actions Modify dashboardActions.html.twig to add custom buttons (e.g., "Upload Documents").

4. Validation Rules Add constraints to extended entities:

   use Symfony\Component\Validator\Constraints as Assert;
   /**
    * @Assert\Length(min=14, max=14)
    */
   private $business_siret;
   

5. API Extensions Create custom controllers extending c975L\UserBundle\Controller\ApiController for additional endpoints.

Configuration Quirks

• Email Saving: Disable database storage for emails via c975LEmailBundle config:

  c975_l_email:
      save_emails: false
  

• Public Profiles: Disable via config.yml:

  c975_l_user:
      public_profile: false
  

• Locale Handling: For multilingual sites, use _locale routing and override UserFull fields (e.g., firstname_en, firstname_fr).

Performance Notes

• Avatar Handling: Use user_avatar() with cached sizes (e.g., user_avatar(128)) to avoid repeated image processing.
• Database Indexes: Add indexes to email and identifier fields in user.sql for large-scale apps.
• Event Listeners: Prioritize critical listeners (e.g., GDPR compliance) to avoid race conditions.