Profile Bundle Laravel Package

Getting Started

Minimal Setup Steps

1. Install the Bundle

   composer require avanzu/profile-bundle
   

   Ensure your composer.json meets the package's PHP/Symfony version constraints (PHP ≥5.3.2, Symfony 2.1–<3.0).

2. Enable the Bundle Add to app/AppKernel.php:

   new Avanzu\ProfileBundle\AvanzuProfileBundle(),
   

3. Create a User Entity Extend Avanzu\ProfileBundle\Entity\User and annotate with @ORM\Entity:

   use Avanzu\ProfileBundle\Entity\User as BaseUser;
   
   class User extends BaseUser {}
   

4. Configure the Bundle Update config.yml with your user_class and form type:

   avanzu_profile:
       user_class: AppBundle\Entity\User
       form:
           class:
               user: AppBundle\Form\Type\UserType
   

5. Set Up Routing Import routes in app/config/routing.yml:

   avanzu_profile:
       resource: "@AvanzuProfileBundle/Resources/config/routing.yml"
       prefix: /
   

6. Configure Security Define encoders, providers, and firewalls in security.yml:

   security:
       encoders:
           AppBundle\Entity\User: sha512
       providers:
           avanzu_profile_bundle:
               entity: { class: AppBundle\Entity\User, property: username }
   

7. First Use Case Access /profile (protected by ROLE_USER) or /register to test registration/login flows.

Where to Look First

• Documentation: The README provides a clear, step-by-step guide. Focus on:
  • Entity/User.php for base user traits.
  • Resources/config/routing.yml for default routes.
  • Controller/ for built-in actions (e.g., ProfileController, RegistrationController).
• Templates: Check Resources/views/ for Twig templates (e.g., profile/edit.html.twig).
• Forms: Review Form/Type/UserType.php to customize fields.

Implementation Patterns

Core Workflows

1. User Registration

   • Extend RegistrationController or override templates (registration/register.html.twig).
   • Customize validation by modifying the UserType form.

2. Profile Management

   • Users edit profiles via /profile/edit. Override ProfileController or templates:

     {% extends 'AvanzuProfileBundle::profile/edit.html.twig' %}
     {% block profile_fields %}
         {{ form_row(form.custom_field) }}
     {% endblock %}
     

3. Password Resetting

   • Use /resetting/request and /resetting/reset. Extend ResettingController or templates:

     {% extends 'AvanzuProfileBundle::resetting/reset.html.twig' %}
     

4. Security Integration

   • Leverage Symfony’s security component for custom roles/access control:

     access_control:
         - { path: ^/admin, roles: ROLE_ADMIN }
     

Integration Tips

1. Doctrine Events Listen to user lifecycle events (e.g., post-persist) in your bundle:

   // src/AppBundle/EventListener/UserListener.php
   public function postPersist(User $user)
   {
       $user->setLastLogin(new \DateTime());
   }
   

2. Custom Fields Add fields to UserType and entity:

   // User.php
   /**
    * @ORM\Column(type="string")
    */
   private $customField;
   
   // UserType.php
   $builder->add('customField');
   

3. API Endpoints Expose profile data via API (e.g., FOSRestBundle):

   # routing.yml
   app_profile_api:
       path: /api/profile
       defaults: { _controller: AppBundle\Controller\ProfileApiController::getProfile }
   

4. Testing Use Symfony’s WebTestCase to test controllers:

   $client->request('GET', '/profile');
   $this->assertTrue($client->getResponse()->isSuccessful());
   

Gotchas and Tips

Pitfalls

1. Symfony Version Mismatch

   • The bundle targets Symfony 2.1–<3.0. Avoid using with Symfony 4+ without forks/patches.
   • Fix: Use a compatible fork (e.g., symfony/security-bundle:^2.8) or migrate to a modern alternative like FOSUserBundle.

2. Password Encoding

   • Defaults to sha512. For modern apps, use bcrypt or argon2:

     security:
         encoders:
             AppBundle\Entity\User: bcrypt
     

   • Note: Requires symfony/security-core:^3.0 or manual encoder setup.

3. Routing Conflicts

   • Prefixes (/profile, /register) may clash with existing routes.
   • Fix: Adjust routing.yml prefixes or use _controller overrides.

4. Template Overrides

   • Forgetting to extend base templates (e.g., AvanzuProfileBundle::profile/edit.html.twig) breaks layouts.
   • Tip: Use {% extends %} and {% block %} for partial overrides.

Debugging

1. Form Validation Errors

   • Check UserType constraints and Symfony’s Validator component:

     // UserType.php
     $builder->add('email', EmailType::class, [
         'constraints' => [new NotBlank(), new Email()]
     ]);
     

2. Authentication Failures

   • Verify security.yml provider/class matches your user_class.
   • Test login with:

     php bin/console debug:security
     

3. Doctrine Migrations

   • After adding fields to User, generate migrations:

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

Extension Points

1. Custom Controllers Override bundle controllers by re-routing:

   # routing.yml
   app_profile:
       resource: "@AppBundle/Controller/ProfileController.php"
       type: annotation
       prefix: /profile
   

2. Event Subscribers Hook into user events (e.g., UserEvents::POST_REGISTER):

   // src/AppBundle/EventListener/RegistrationListener.php
   public function onRegistration(UserEvent $event)
   {
       $user = $event->getUser();
       $user->setActive(true);
   }
   

3. API Integration Use Symfony’s Serializer to expose user data:

   // src/AppBundle/Serializer/UserNormalizer.php
   public function normalize($user, $format = null, array $context = [])
   {
       return [
           'id' => $user->getId(),
           'email' => $user->getEmail(),
       ];
   }
   

4. Custom Roles Add roles to User entity and update security.yml:

   // User.php
   private $roles = ['ROLE_USER'];
   
   // security.yml
   access_control:
       - { path: ^/admin, roles: ROLE_ADMIN }
   

Pro Tips

• Use avanzu/tools-bundle (dev dependency) for helper utilities like form builders.
• Leverage Twig Extensions to add user-specific filters:

  {{ user.full_name }} {# Calls a custom method #}
  

• Monitor Deprecations: The bundle is unmaintained. Plan to migrate to LexikJWTAuthenticationBundle or FOSUserBundle for long-term projects.