User Bundle Laravel Package

Getting Started

Minimal Steps

1. Installation Run composer require chaplean/user-bundle in your Laravel project (note: this bundle is Symfony-based, so ensure compatibility via a bridge like symfony/bridge if needed). Add the bundle to config/app.php under providers:

   Chaplean\UserBundle\ChapleanUserBundle::class,
   FOS\UserBundle\FOSUserBundle::class,
   

   Place it after Illuminate\Auth\AuthServiceProvider::class.

2. Publish Config Run php artisan vendor:publish --provider="Chaplean\UserBundle\ChapleanUserBundle" to publish the bundle’s config and migrations. Update config/chaplean_user.php with your custom routes and entity paths.

3. Define User Entity Extend Chaplean\UserBundle\Model\User in app/Models/User.php:

   <?php
   namespace App\Models;
   
   use Chaplean\UserBundle\Model\User as BaseUser;
   use Illuminate\Database\Eloquent\Model;
   
   class User extends BaseUser {
       protected $table = 'users'; // Customize table name if needed
   }
   

4. Run Migrations Execute php artisan migrate to create the user table.

5. First Use Case Register a user via the default route (e.g., /register) or manually via Eloquent:

   use App\Models\User;
   
   $user = User::create([
       'email' => 'test@example.com',
       'plainPassword' => 'securepassword123',
   ]);
   

Implementation Patterns

Workflows

1. Authentication Use the bundle’s built-in controllers for login/logout:

   // Login route (configured in chaplean_user.php)
   Route::get('/login', [ChapleanUserBundle::class, 'SecurityController', 'login']);
   

   Customize the login form in resources/views/ChapleanUserBundle/Security/login.html.twig (Symfony template).

2. Registration Extend the registration process by overriding the RegistrationController:

   // app/Http/Controllers/RegisterController.php
   namespace App\Http\Controllers;
   
   use Chaplean\UserBundle\Controller\RegistrationController as BaseRegistrationController;
   
   class RegisterController extends BaseRegistrationController {
       protected function getUserClass() {
           return \App\Models\User::class;
       }
   }
   

3. Password Reset Leverage the ResettingController for password resets. Customize the email template in resources/views/ChapleanUserBundle/Resetting/email.html.twig.

4. Profile Management Use the ProfileController to handle profile updates:

   // Update profile (example)
   $user = auth()->user();
   $user->firstName = 'John';
   $user->save();
   

Integration Tips

• Laravel-Specific Bridge: Create a facade to interact with the bundle’s services:

  // app/Facades/UserFacade.php
  namespace App\Facades;
  
  use Illuminate\Support\Facades\Facade;
  
  class UserFacade extends Facade {
      protected static function getFacadeAccessor() {
          return 'chaplean.user.manager';
      }
  }
  

  Bind the service in AppServiceProvider:

  $this->app->bind('chaplean.user.manager', function ($app) {
      return $app->make(\Chaplean\UserBundle\Manager\UserManager::class);
  });
  

• Custom Fields: Add fields to the User model and update the registration form:

  // User.php
  protected $fillable = ['email', 'plainPassword', 'custom_field'];
  

  Extend the registration form template to include custom_field.

• Events: Listen to bundle events (e.g., user.registered) via Laravel’s event system:

  // app/Providers/EventServiceProvider.php
  protected $listen = [
      'Chaplean\UserBundle\Event\UserEvent' => [
          'App\Listeners\HandleUserRegistered',
      ],
  ];
  

Gotchas and Tips

Pitfalls

1. Symfony vs. Laravel Conflicts:

   • The bundle assumes Symfony’s Request and Twig; use Laravel’s Request facade or bridge Symfony components.
   • Fix: Wrap Symfony services in Laravel-compatible facades (as shown above).

2. Route Conflicts:

   • Default routes (e.g., /login) may clash with Laravel’s built-in routes.
   • Fix: Override routes in routes/web.php:

     Route::get('/custom-login', [ChapleanUserBundle::class, 'SecurityController', 'login'])
          ->name('chaplean_user_login');
     

     Update chaplean_user.php to reflect the new route name.

3. Migration Issues:

   • The bundle’s migrations may not align with Laravel’s schema conventions (e.g., snake_case vs. camelCase).
   • Fix: Publish and customize migrations:

     php artisan vendor:publish --tag=chaplean-user-migrations
     

     Modify database/migrations/..._create_users_table.php.

4. Authentication Guard:

   • The bundle uses Symfony’s security component, which may not integrate seamlessly with Laravel’s auth helper.
   • Fix: Extend Laravel’s AuthManager to include the bundle’s user provider:

     // app/Providers/AuthServiceProvider.php
     protected function registerUserProviders() {
         $this->app['auth']->provider('chaplean', function ($app) {
             return new ChapleanUserProvider($app['chaplean.user.manager']);
         });
     }
     

Debugging

1. Enable Debug Mode: Set debug: true in config/chaplean_user.php to log detailed errors.

2. Check Events: Use dd() in event listeners to inspect payloads:

   public function handle(UserEvent $event) {
       dd($event->getUser()->toArray());
   }
   

3. Symfony Dump: Use Symfony’s var_dump() helper for complex objects:

   use Symfony\Component\VarDumper\VarDumper;
   
   VarDumper\cli(var_export($user, true));
   

Extension Points

1. Custom User Manager: Override the default UserManager to add logic:

   // app/Services/CustomUserManager.php
   namespace App\Services;
   
   use Chaplean\UserBundle\Manager\UserManager as BaseUserManager;
   
   class CustomUserManager extends BaseUserManager {
       public function createUser(array $data) {
           $user = parent::createUser($data);
           $user->custom_field = $data['custom_field'];
           return $user;
       }
   }
   

   Bind it in AppServiceProvider:

   $this->app->bind(\Chaplean\UserBundle\Manager\UserManager::class, function ($app) {
       return new \App\Services\CustomUserManager($app['fos_user.user_manager.default']);
   });
   

2. Form Extensions: Extend Symfony forms by creating custom types:

   // app/Form/Type/CustomUserType.php
   namespace App\Form\Type;
   
   use Symfony\Component\Form\AbstractType;
   use Symfony\Component\Form\FormBuilderInterface;
   
   class CustomUserType extends AbstractType {
       public function buildForm(FormBuilderInterface $builder, array $options) {
           $builder->add('custom_field');
       }
   }
   

   Update the registration form in config/chaplean_user.yml:

   registration:
       form:
           type: App\Form\Type\CustomUserType
   

3. API Integration: Use the bundle’s UserManager to fetch users in API routes:

   Route::get('/api/users', function () {
       $users = app(\Chaplean\UserBundle\Manager\UserManager::class)->findUsers();
       return response()->json($users);
   });