User Bundle Laravel Package

Getting Started

Minimal Setup for Laravel (Symfony) Projects

Since this is a Symfony bundle, Laravel developers would need to integrate it via Symfony’s ecosystem (e.g., via Laravel Symfony Bridge or a Symfony microkernel). Below are the first steps to leverage it in a Laravel-like workflow:

1. Install the Bundle Add the bundle to your Symfony/Laravel project (if using Symfony components):

   composer require connectholland/user-bundle
   

2. Enable the Bundle Register the bundle in config/bundles.php (Symfony) or adapt for Laravel:

   // config/bundles.php
   return [
       // ...
       ConnectHolland\UserBundle\ConnectHollandUserBundle::class => ['all' => true],
   ];
   

3. Configure Environment Variables Set up email and OAuth (if needed) in .env:

   [email protected]
   # OAuth example (Google)
   USERBUNDLE_OAUTH_GOOGLE_ID=your-client-id.apps.googleusercontent.com
   USERBUNDLE_OAUTH_GOOGLE_SECRET=your-client-secret
   

4. Run Database Migrations The bundle includes a User entity. Run migrations:

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

5. First Use Case: CLI User Creation Create a user via command line (useful for seeding or admin tasks):

   php bin/console connectholland:user:create [email protected] P@ssw0rd --role=ROLE_USER
   

6. Enable Routing Import the bundle’s routes in config/routes.yaml:

   connectholland_user:
       resource: '@ConnectHollandUserBundle/Resources/config/routing.yaml'
   

7. Test the Login/Registration Flow

   • Visit /register (or /inloggen for Dutch localization).
   • Verify email activation via the sent link.
   • Test password reset at /password-reset.

Implementation Patterns

Core Workflows

1. Registration & Activation

• Frontend: Use the pre-built Twig templates (@ConnectHollandUser/registration.html.twig) or override them in your theme.
• Backend: The bundle handles:
  • Form validation (email uniqueness, password strength).
  • Email activation link generation (secure, one-time-use tokens).
  • User activation on link click.
• API: For API registrations, send a POST to /api/register with:

  {
      "email": "[email protected]",
      "password": "P@ssw0rd",
      "plainPassword": "P@ssw0rd"  // Required for API
  }
  

  Response: Returns a 200 status (no body) with the user activated.

2. OAuth Integration

• Prerequisite: Install hwi/oauth-bundle:

  composer require hwi/oauth-bundle
  

• Configuration:
  • Add OAuth provider keys to .env (e.g., USERBUNDLE_OAUTH_GOOGLE_ID).
  • Enable routing in config/routes.yaml:

    connectholland_user_oauth:
        resource: '@ConnectHollandUserBundle/Resources/config/routing_oauth.yaml'
    

  • Configure security firewall (see README).
• User Flow:
  • Redirect users to /connect/google (or /connect/facebook).
  • The bundle auto-links OAuth accounts to existing users or creates new ones.

3. JWT API Authentication

• Prerequisite: Install lexik/jwt-authentication-bundle and api-platform/core:

  composer require lexik/jwt-authentication-bundle api
  

• Configuration:
  • Generate JWT keys (private.pem, public.pem) and set in .env:

    JWT_SECRET_KEY=config/jwt/private.pem
    JWT_PUBLIC_KEY=config/jwt/public.pem
    

  • Configure security firewall for API routes (see README).
• Authentication Flow:
  • Users authenticate via POST /api/users/authenticate:

    {
        "email": "[email protected]",
        "password": "P@ssw0rd"
    }
    

  • Response: Returns a JWT token for subsequent API requests.

4. Password Reset

• Frontend: Trigger reset via /password-reset.
• Backend: The bundle sends a reset link to the user’s email.
• API: Reset via POST /api/password-reset with:

  {
      "email": "[email protected]"
  }
  

  Response: 200 status (no body). User clicks the link and submits a new password.

5. User Management (Admin)

• CLI: Create/admin users:

  php bin/console connectholland:user:create [email protected] AdminP@ss --role=ROLE_ADMIN
  

• API: Fetch/update user details via /api/account/details (requires authentication).

Integration Tips

Laravel-Symfony Interop

• For Laravel Developers:
  • Use Symfony’s HTTP Foundation components (e.g., Request, Response) in controllers.
  • Override Twig templates in templates/ConnectHollandUser/ to customize views.
  • Use Symfony’s Dependency Injection for services (e.g., UserManager).

Extending the User Entity

1. Clone the User Entity:

   cp vendor/connectholland/user-bundle/src/Entity/User.php src/Entity/
   

2. Add Custom Fields:

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

3. Update Migrations:

   php bin/console make:migration
   php bin/console doctrine:migrations:migrate
   

4. Update Bundle Configuration: In config/packages/connectholland_user.yaml, set:

   user_entity: App\Entity\User
   

Theming

• Override templates by copying them from: vendor/connectholland/user-bundle/templates/ to templates/ConnectHollandUser/.
• Example: Customize registration form:

  {# templates/ConnectHollandUser/registration.html.twig #}
  {% extends '@ConnectHollandUser/registration.html.twig' %}
  {% block title %}Custom Registration{% endblock %}
  

API Best Practices

• Validation: Use API Platform’s validation (e.g., @Assert\Email).
• Pagination: For user lists, implement ApiPlatform\Metadata\Operation with pagination.
• CORS: Configure CORS headers in Symfony’s security.yaml:

  access_control:
      - { path: ^/api, roles: ROLE_USER, methods: [GET, POST, PUT, DELETE] }
  

Gotchas and Tips

Pitfalls

1. API Response Quirks:

   • POST endpoints (e.g., /api/register) return 200 (not 201) due to API Platform fixes in v4.0.6. Avoid assuming 201 Created responses.
   • OpenAPI Schemas: Inline schemas (e.g., in /api/account/details) were replaced with $ref in v4.0.5. Regenerate API docs if using Swagger/OpenAPI tools.

2. OAuth Configuration:

   • Missing Routes: Forgetting to enable OAuth routes (routing_oauth.yaml) will break /connect/google links.
   • Resource Owners: Ensure resource_owners in security.yaml matches your provider names (e.g., google: connectholland_user_oauth_check_main_google).

3. Email Delivery:

   • Environment Variables: If emails aren’t sent, verify USERBUNDLE_FROM_EMAILADDRESS and Symfony’s mailer config (framework/mailer).
   • Transport: Use symfony/mailer with a real transport (e.g., SMTP) in production:

     # config/packages/mailer.yaml
     framework:
         mailer:
             dsn: '%env(MAILER_DSN)%'
     

4. User Entity Overrides:

   • Doctrine Proxy Issues: If extending User, ensure your entity is properly mapped in orm/EntityManager to avoid proxy conflicts.
   • Migration Conflicts: After extending User, run make:migration to avoid schema mismatches.

5. JWT Token Handling:

   • Key Paths: JWT_SECRET_KEY and `JWT_P