Userbundle Laravel Package

Getting Started

Minimal Setup

1. Install via Composer Add to composer.json:

   "require": {
       "ais/userbundle": "dev-master"
   }
   

   Run:

   composer update
   

2. Register Bundle Add to app/AppKernel.php:

   new Ais\UserBundle\AisUserBundle(),
   new Nelmio\ApiDocBundle\NelmioApiDocBundle(),
   new FOS\RestBundle\FOSRestBundle(),
   new JMS\SerializerBundle\JMSSerializerBundle()
   

3. Configure Routing Add to app/config/routing.yml:

   ais_users:
     type: rest
     prefix: /api
     resource: "@AisUserBundle/Resources/config/routes.yml"
   

4. Verify API Docs Access /api/doc (e.g., http://localhost/web/app_dev.php/api/doc) to explore endpoints.

First Use Case: User Registration

1. Trigger Registration Endpoint Use POST /api/users/register with JSON payload:

   {
       "username": "testuser",
       "email": "test@example.com",
       "password": "secure123"
   }
   

   • Note: The bundle assumes OAuth2 (via FOSOAuthServerBundle) for authentication.

Implementation Patterns

Core Workflows

1. User CRUD via REST

   • Create: POST /api/users (with FOSRestBundle serialization).
   • Read: GET /api/users/{id} (JMS Serializer handles output).
   • Update: PUT /api/users/{id} (patchable via WillDurand/RestExtraBundle).
   • Delete: DELETE /api/users/{id}.

2. Authentication Flow

   • Use FOSOAuthServerBundle for token-based auth (e.g., /oauth/v2/token).
   • Attach tokens to headers: Authorization: Bearer <token>.

3. Event-Driven Extensions

   • Listen to AisUserEvents (e.g., USER_REGISTERED) via Symfony’s event dispatcher:

     $dispatcher->addListener('AisUserEvents::USER_REGISTERED', function ($event) {
         // Custom logic (e.g., send welcome email)
     });
     

Integration Tips

1. Custom User Fields Extend the User entity (located in AisUserBundle/Entity/User.php):

   namespace AppBundle\Entity;
   
   use Ais\UserBundle\Entity\User as BaseUser;
   
   class User extends BaseUser {
       /**
        * @ORM\Column(type="string", nullable=true)
        */
       private $customField;
   }
   

   Update config.yml to override the entity:

   ais_user:
       user_class: AppBundle\Entity\User
   

2. API Documentation Leverage NelmioApiDocBundle to auto-generate Swagger docs. Annotate controllers:

   use Nelmio\ApiDocBundle\Annotation\ApiDoc;
   
   /**
    * @ApiDoc(
    *   resource=true,
    *   description="User registration"
    * )
    */
   class UserController extends FOSRestController
   

3. Testing Use LiipFunctionalTestBundle for API tests:

   $client = static::createClient();
   $client->request('POST', '/api/users/register', [
       'json' => ['username' => 'test', 'password' => 'pass']
   ]);
   

Gotchas and Tips

Pitfalls

1. Deprecated Symfony 2.7

   • Avoid using modern Laravel/Lumen patterns (e.g., Eloquent). Stick to Doctrine ORM.
   • Fix: Use Doctrine\ORM\EntityManager directly or wrap in a repository.

2. Missing Laravel-Specific Features

   • No built-in support for Laravel’s Auth facade or HasApiTokens traits.
   • Workaround: Manually implement token logic via FOSOAuthServerBundle.

3. Route Conflicts

   • ais_users routes may clash with existing /api/users endpoints.
   • Solution: Override routes.yml or use _format suffixes:

     ais_users:
       type: rest
       prefix: /api/v1
       resource: "@AisUserBundle/Resources/config/routes.yml"
     

Debugging Tips

1. Enable API Debugging Add to config.yml:

   nelmio_api_doc:
       areas: { path_patterns: ['^/api'] }
       sandbox:
           method: POST
           headers:
               Authorization: "Bearer {token}"
   

2. Check Event Dispatching Verify events fire in app_dev.php:

   $dispatcher = $this->get('event_dispatcher');
   $dispatcher->addListener('AisUserEvents::USER_REGISTERED', function ($event) {
       error_log('Event triggered: ' . print_r($event->getUser(), true));
   });
   

3. Serializer Issues

   • If responses are malformed, clear the JMS cache:

     php app/console jms:serializer:update-cache-proxies
     

Extension Points

1. Custom Controllers Override the default UserController by configuring:

   ais_user:
       controller:
           user: AppBundle\Controller\UserController
   

2. Validation Rules Extend validation via Symfony’s constraints:

   use Symfony\Component\Validator\Constraints as Assert;
   
   /**
    * @Assert\NotBlank()
    * @Assert\Length(min=6)
    */
   private $password;
   

3. Email Templates Override Twig templates in app/Resources/AisUserBundle/views/ (e.g., Registration/email.txt.twig).