Web Account Bundle Laravel Package

## Getting Started

### Minimal Setup
1. **Installation**:
   ```bash
   composer require atoolo/web-account-bundle

Add to config/bundles.php:

return [
    // ...
    Atoolo\WebAccountBundle\AtooloWebAccountBundle::class => ['all' => true],
];

2. Configuration: Publish the default config:

   php bin/console config:dump-reference AtooloWebAccountBundle
   

   Override in config/packages/atoolo_web_account.yaml:

   atoolo_web_account:
       ies_url: '%env(IES_URL)%'  # Required for GraphQL integration
       unauthorized_entry_point: '/login'  # Customize unauthorized redirect
   

3. First Use Case: Enable registration and login routes by configuring security.yaml:

   security:
       firewalls:
           main:
               form_login:
                   login_path: atoolo_web_account_login
                   check_path: atoolo_web_account_check
               logout:
                   path: atoolo_web_account_logout
   

4. User Model: Extend the default user entity (if needed):

   // src/Entity/CustomUser.php
   use Atoolo\WebAccountBundle\Entity\User;
   
   class CustomUser extends User
   {
       // Add custom fields/methods
   }
   

   Update security.yaml to point to your user provider:

   providers:
       app_user_provider:
           entity:
               class: App\Entity\CustomUser
               property: email
   

Implementation Patterns

Core Workflows

1. Registration Flow:

   • Use the built-in registration controller (Atoolo\WebAccountBundle\Controller\RegistrationController).
   • Customize the registration form by extending Atoolo\WebAccountBundle\Form\RegistrationType:

     // src/Form/ExtendedRegistrationType.php
     use Atoolo\WebAccountBundle\Form\RegistrationType as BaseType;
     
     class ExtendedRegistrationType extends BaseType
     {
         public function buildForm(FormBuilderInterface $builder, array $options)
         {
             parent::buildForm($builder, $options);
             $builder->add('customField', TextType::class);
         }
     }
     

   • Update services.yaml to replace the default form:

     services:
         Atoolo\WebAccountBundle\Form\RegistrationType:
             alias: App\Form\ExtendedRegistrationType
     

2. Authentication:

   • Leverage Symfony’s security system with the bundle’s provided routes:
     • atoolo_web_account_login (GET/POST)
     • atoolo_web_account_check (login check)
     • atoolo_web_account_logout (logout)
   • Customize login template by overriding: templates/atoolo_web_account/login.html.twig.

3. GraphQL Integration:

   • The bundle uses GraphQL for user management (e.g., registration, password recovery).
   • Extend the GraphQL schema by creating a custom resolver:

     // src/Resolver/CustomUserResolver.php
     use Overblog\GraphQLBundle\Resolver\ResolverInterface;
     
     class CustomUserResolver implements ResolverInterface
     {
         public function resolve($root, array $args, GraphQLContextInterface $context)
         {
             // Custom logic (e.g., fetch user from external API)
         }
     }
     

   • Register the resolver in config/graphql.yaml:

     resolvers:
         CustomUserResolver: ~
     

4. User-Specific Features:

   • Use the Atoolo\WebAccountBundle\Security\User\WebAccountUser trait to access user data in controllers:

     use Atoolo\WebAccountBundle\Security\User\WebAccountUser;
     
     class MyController
     {
         public function showProfile(WebAccountUser $user)
         {
             $user->getEmail(); // Access user data
         }
     }
     

   • Protect routes with custom roles (e.g., ROLE_USER):

     # config/routes.yaml
     app_profile:
         path: /profile
         controller: App\Controller\ProfileController::show
         roles: [ROLE_USER]
     

5. Password Recovery:

   • The bundle includes a password recovery workflow. Customize the email template by overriding: templates/atoolo_web_account/email/reset_password.html.twig.
   • Extend the recovery controller if needed:

     // src/Controller/CustomRecoveryController.php
     use Atoolo\WebAccountBundle\Controller\RecoveryController as BaseController;
     
     class CustomRecoveryController extends BaseController
     {
         protected function generateRecoveryToken(UserInterface $user)
         {
             // Custom token generation logic
         }
     }
     

Integration Tips

1. Event Listeners:

   • Listen to user events (e.g., registration, login) to trigger custom logic:

     // src/EventListener/CustomUserListener.php
     use Atoolo\WebAccountBundle\Event\UserEvents;
     use Symfony\Component\EventDispatcher\Attribute\AsEventListener;
     
     class CustomUserListener
     {
         #[AsEventListener(event: UserEvents::REGISTERED, method: 'onUserRegistered')]
         public function onUserRegistered(UserRegisteredEvent $event)
         {
             // Send welcome email, log activity, etc.
         }
     }
     

2. Extranet Support:

   • Enable extranet mode in config/packages/atoolo_web_account.yaml:

     atoolo_web_account:
         extranet: true
     

   • This restricts access to registered users only.

3. Custom User Provider:

   • Override the default user provider to fetch users from an external source (e.g., database or API):

     // src/Security/CustomUserProvider.php
     use Symfony\Component\Security\Core\User\UserProviderInterface;
     
     class CustomUserProvider implements UserProviderInterface
     {
         public function loadUserByIdentifier($identifier)
         {
             // Custom user loading logic
         }
     }
     

   • Register the provider in security.yaml:

     providers:
         custom_user_provider:
             id: App\Security\CustomUserProvider
     

4. API Authentication:

   • Use the bundle’s token-based authentication for APIs:

     # config/packages/security.yaml
     firewalls:
         api:
             pattern: ^/api
             stateless: true
             provider: custom_user_provider
             json_login:
                 check_path: /api/login_check
                 username_path: email
                 password_path: password
                 success_handler: lexik_jwt_authentication.handler.authentication_success
                 failure_handler: lexik_jwt_authentication.handler.authentication_failure
     

5. Testing:

   • Use the bundle’s test utilities to mock user authentication:

     use Atoolo\WebAccountBundle\Test\WebAccountTestTrait;
     
     class MyTest extends WebTestCase
     {
         use WebAccountTestTrait;
     
         public function testAuthenticatedRoute()
         {
             $client = static::createClient();
             $this->loginUser($client, ['email' => 'user@example.com', 'password' => 'password']);
             $client->request('GET', '/profile');
             // Assertions...
         }
     }
     

Gotchas and Tips

Pitfalls

1. IES URL Configuration:

   • The bundle requires ies_url in configuration for GraphQL operations. If missing, registration/password recovery will fail silently.
   • Fix: Ensure IES_URL is set in .env and referenced in atoolo_web_account.yaml:

     atoolo_web_account:
         ies_url: '%env(IES_URL)%'
     

2. Role Prefix:

   • The bundle prefixes roles with ROLE_ (e.g., ROLE_USER). Forgetting this prefix in security checks will cause authentication failures.
   • Fix: Always use ROLE_USER (not just USER) in YAML or annotations:

     # Correct:
     roles: [ROLE_USER]
     # Incorrect:
     roles: [USER]
     

3. Cookie Naming:

   • The bundle uses WEB_ACCOUNT_TOKEN for authentication cookies. Conflicts may arise with other bundles using similar names (e.g., WEB_TOKEN).
   • Fix: Rename the cookie in config/packages/atoolo_web_account.yaml:

     atoolo_web_account:
         cookie_name: CUSTOM_ACCOUNT_TOKEN
     

4. GraphQL Schema Mismatches:

   • Custom GraphQL resolvers must match the expected schema defined in the bundle. Incorrect types or fields will cause runtime errors.
   • Fix: Refer to the bundle documentation for schema details or extend the schema via overblog_graphql_bundle.

5. User Entity Inheritance:

   • Extending the default User entity requires proper mapping of custom fields. Forgetting to update the entity manager’s metadata can lead to "undefined property" errors.
   • Fix: Run php bin/console doctrine:schema:update --force after adding custom fields.