User Bundle Laravel Package

Getting Started

Minimal Setup for Laravel Integration

1. Install the Bundle (via Composer):

   composer require connectholland/user-bundle
   

   Note: This bundle is Symfony-based, but can be adapted for Laravel via Symfony Bridge or by leveraging its core logic (e.g., OAuth, JWT, and user management) in a Laravel context.

2. Configure Environment Variables (.env):

   USERBUNDLE_FROM_EMAILADDRESS=your@email.com
   JWT_SECRET_KEY=path/to/private.pem
   JWT_PUBLIC_KEY=path/to/public.pem
   JWT_PASSPHRASE=your-passphrase
   

3. Set Up Database & Migrations:

   • The bundle uses Doctrine ORM. For Laravel, manually create a User entity mirroring this structure and configure Doctrine via config/packages/doctrine.yaml.

4. First Use Case: CLI User Creation

   php artisan connectholland:user:create user@example.com P@ssw0rd --role=ROLE_USER
   

   For Laravel, adapt this command via a custom Artisan command or use Laravel’s make:user with similar logic.

Key Entry Points for Laravel Developers

Implementation Patterns

1. User Management Workflow

Registration Flow

1. Frontend: Submit form to /api/register (POST).
2. Backend:
   • Validate input (use Laravel’s FormRequest).
   • Trigger UserCreatedEvent (adapt Symfony’s UserBundleEvents::USER_CREATED).
   • Send verification email (reuse Symfony’s Twig-based template or convert to Laravel’s Mailable).
3. Response: Return 200 (no body) due to the bundle’s fix for API Platform 2.x.

Laravel-Specific Adaptation

// routes/api.php
Route::post('/register', [UserController::class, 'register']);

// app/Http/Controllers/UserController.php
public function register(RegisterRequest $request) {
    $user = User::create($request->validated());
    event(new Registered($user)); // Trigger email
    return response()->noContent(); // 200 + no body
}

2. OAuth Integration

Symfony → Laravel Migration

1. Install Dependencies:

   composer require socialiteproviders/google
   

2. Configure .env:

   GOOGLE_CLIENT_ID=your_id
   GOOGLE_CLIENT_SECRET=your_secret
   

3. Create OAuth Controller:

   use Laravel\Socialite\Facades\Socialite;
   
   public function redirectToGoogle() {
       return Socialite::driver('google')->redirect();
   }
   
   public function handleGoogleCallback() {
       $user = Socialite::driver('google')->user();
       // Link to existing user or create new
   }
   

   Replace Symfony’s HWI logic with Laravel’s socialiteproviders.

3. API + JWT Authentication

Laravel JWT Setup

1. Install:

   composer require typset/laravel-jwt-auth
   

2. Configure config/jwt.php and generate keys:

   php artisan jwt:secret
   

3. Protect Routes:

   Route::middleware('auth:api')->group(function () {
       Route::get('/account', [AccountController::class, 'details']);
   });
   

   Mirror Symfony’s lexik/jwt-authentication-bundle behavior.

4. Extending the User Entity

Laravel-Specific Approach

1. Create a Custom User Model:

   php artisan make:model User -m --api
   

2. Extend with Traits:

   use Illuminate\Foundation\Auth\User as Authenticatable;
   use ConnectHolland\UserBundle\Entity\Traits\Timestampable; // Hypothetical trait
   
   class User extends Authenticatable {
       use Timestampable;
       // Add custom fields (e.g., `profilePicture`)
   }
   

3. Update Migration:

   Schema::create('users', function (Blueprint $table) {
       $table->id();
       $table->string('profile_picture')->nullable();
       // ... other fields
   });
   

5. Password Reset Flow

Laravel Integration

1. Use Laravel’s Built-in Reset:

   php artisan make:controller Auth/ResetPasswordController
   

2. Customize Email:

   // app/Mail/ResetPasswordMail.php
   public function build() {
       return $this->subject('Reset Password')
                   ->markdown('emails.password_reset');
   }
   

   Adapt Symfony’s UserBundle email templates to Laravel’s markdown system.

Gotchas and Tips

Pitfalls

1. API Platform Version Mismatch:

   • The bundle’s 200 response fix only applies to API Platform 2.x. If using 3.x, responses may behave differently (e.g., 201 for POSTs is now standard).
   • Workaround: Manually set status: 200 in API resource metadata:

     # config/api_platform/resources.yaml
     App\Entity\User:
         attributes:
             status: 200
     

2. Doctrine ORM vs. Eloquent:

   • The bundle uses Doctrine. For Laravel, avoid direct Doctrine calls (e.g., EntityManager). Instead:
     • Use Eloquent models.
     • Replace UserBundle\Repository\UserRepository with Laravel’s User::query().

3. OAuth Provider Quirks:

   • Symfony’s HWI bundle expects specific provider configurations. In Laravel:
     • Ensure socialiteproviders/google matches Symfony’s USERBUNDLE_OAUTH_GOOGLE_SCOPE.
     • Example: Add hd: "your-domain.com" to Google’s config if using domain restriction.

4. Email Templates:

   • Symfony uses Twig. Convert templates to Laravel’s Blade:

     {# Symfony Twig #}
     <a href="{{ url }}">Verify Email</a>
     

     {# Laravel Blade #}
     <a href="{{ $url }}">Verify Email</a>
     

5. JWT Key Paths:

   • Symfony expects absolute paths (e.g., config/jwt/private.pem). In Laravel:
     • Store keys in storage/app/jwt/ and use relative paths:

       JWT_SECRET_KEY=storage/app/jwt/private.pem
       

Debugging Tips

1. Check HTTP Responses:

   • Use dd(response()->getContent()) to inspect API responses. Ensure POSTs return 200 (not 201) for non-resource operations.

2. OAuth Debugging:

   • Enable Laravel’s Socialite logging:

     Socialite::with('google')->scopes(['email'])->redirect();
     

   • Check logs for provider errors (e.g., missing USERBUNDLE_OAUTH_GOOGLE_ID).

3. Email Delivery:

   • Test locally with Laravel’s Mail::fake():

     Mail::fake();
     event(new Registered($user));
     Mail::assertSent(ResetPasswordMail::class);
     

4. Doctrine vs. Eloquent Conflicts:

   • If using both, ensure:
     • No EntityManager calls in controllers.
     • Migrations use Laravel’s schema builder (not Doctrine’s SchemaTool).

Extension Points

1. Custom User Fields:

   • Extend the User model in Laravel:

     class User extends Authenticatable {
         protected $casts = [
             'is_active' => 'boolean',
             'last_login_at' => 'datetime',
         ];
     }
     

2. Override Email Logic:

   • Replace Symfony’s UserConfirmationController with a Laravel EventListener:

     public function handle(Registered $event) {
         Mail::to($event->user->email)->send(new VerifyEmail($event->user));
     }
     

3. API Response Customization:

   • Override the bundle’s ApiPlatform metadata in Laravel: