Philarmony User Bundle Laravel Package

Getting Started

Minimal Setup

1. Installation

   composer require deozza/philarmony-user-bundle
   

   Add the bundle to config/bundles.php (Symfony) or config/app.php (Laravel via Symfony bridge):

   Deozza\PhilarmonyUserBundle\PhilarmonyUserBundle::class => ['all' => true],
   

2. Publish Configuration

   php artisan vendor:publish --provider="Deozza\PhilarmonyUserBundle\PhilarmonyUserBundle" --tag="config"
   

   Edit config/philarmony_user.php to define:

   • user_model (e.g., App\Models\User)
   • auth_driver (e.g., session, api_token)
   • guard_name (e.g., web)

3. First Use Case: Basic Authentication Inject the PhilarmonyUserManager service into a controller:

   use Deozza\PhilarmonyUserBundle\Services\PhilarmonyUserManager;
   
   class AuthController extends Controller {
       public function __construct(private PhilarmonyUserManager $userManager) {}
   
       public function login(Request $request) {
           $credentials = $request->validate([
               'email' => 'required|email',
               'password' => 'required',
           ]);
   
           if ($this->userManager->authenticate($credentials)) {
               return redirect()->route('dashboard');
           }
           return back()->withErrors(['email' => 'Invalid credentials']);
       }
   }
   

Implementation Patterns

Core Workflows

1. User Registration

   $user = $this->userManager->create([
       'name' => 'John Doe',
       'email' => 'john@example.com',
       'password' => 'secure123',
       'roles' => ['ROLE_USER'], // Philarmony-specific
   ]);
   

2. Role-Based Access Control (RBAC)

   // Assign roles
   $this->userManager->addRolesToUser($user, ['ROLE_ADMIN', 'ROLE_EDITOR']);
   
   // Check permissions
   if ($this->userManager->hasRole('ROLE_ADMIN')) {
       // Admin-only logic
   }
   

3. Session/Token Management

   // Generate API token (if configured)
   $token = $this->userManager->generateApiToken($user);
   
   // Logout
   $this->userManager->logout();
   

Integration Tips

• Laravel-Specific: Use Auth::guard($guardName) to align with Philarmony’s guard system:

  $user = Auth::guard('web')->user();
  $this->userManager->setGuard('web'); // Explicitly set guard
  

• Event Listeners: Bind to Philarmony events (e.g., PhilarmonyUserEvents::USER_CREATED):

  event(new UserCreated($user));
  

• Custom User Models: Extend Philarmony’s base model:

  class User extends \Deozza\PhilarmonyUserBundle\Entity\User {
      protected $customField;
  }
  

Gotchas and Tips

Pitfalls

1. Guard Mismatch:

   • Issue: Forgetting to set the correct guard_name in config or via setGuard().
   • Fix: Verify config/philarmony_user.php and ensure Auth::guard() matches.

2. Role Hierarchy Conflicts:

   • Issue: Philarmony uses role inheritance (e.g., ROLE_ADMIN implies ROLE_USER). Overriding roles may break expectations.
   • Fix: Use replaceRoles() instead of addRolesToUser() for full role replacement.

3. Token Expiry:

   • Issue: API tokens may not auto-refresh if not configured in philarmony_user.php.
   • Fix: Set 'token_ttl' (e.g., 604800 for 7 days) and implement TokenRefreshed listener.

Debugging

• Enable Verbose Logging:

  $this->userManager->setDebug(true); // Logs auth attempts to storage/logs/philarmony.log
  

• Common Errors:

  • UserNotFoundException: Check if the user exists and the guard is correct.
  • AuthenticationFailedException: Validate credentials and auth_driver config.

Extension Points

1. Custom Auth Drivers: Override PhilarmonyUserBundle\Security\Authenticator\AuthenticatorInterface for OAuth/LDAP.

2. Event Customization: Extend PhilarmonyUserEvents or create custom events:

   class CustomUserEvent extends Event {
       // Extend with your logic
   }
   

3. Database Schema: Modify migrations in src/Resources/migrations/ to add custom fields to the users table.

Config Quirks

• Default Guard: If guard_name is omitted, defaults to web. Explicitly define it to avoid ambiguity.

• Password Hashing: Uses Symfony’s UserPasswordHasher. For Laravel, ensure PASSWORD_DEFAULT is set in .env.