Skeleton Bundle Laravel Package

Getting Started

Minimal Steps

1. Installation For quick setup (Codyas team members):

   curl -s https://gist.githubusercontent.com/leoantunez/0446c79dcc717de4fbbc0cb8214c26d9/raw | bash -s PROJECT_NAME
   

   For manual installation:

   composer require codyas/skeleton-bundle
   

2. Configure User Model Extend Codyas\Skeleton\Model\UserModel in your App\Entity\User:

   namespace App\Entity;
   use Codyas\Skeleton\Model\UserModel;
   
   class User extends UserModel {}
   

3. Update Configuration Configure config/packages/codyas_skeleton.yaml (if auto-generated) or manually set:

   codyas_skeleton:
       user_model: App\Entity\User
   

4. Run Migrations Generate and run migrations for the default user fields (id, email, enabled, etc.):

   php bin/console make:migration
   php bin/console doctrine:migrations:migrate
   

First Use Case

Register a new user via API/Controller:

use Codyas\Skeleton\Model\UserModelInterface;
use Symfony\Component\HttpFoundation\Request;

public function register(Request $request): Response
{
    $user = new User(); // Your extended UserModel
    $user->setEmail($request->request->get('email'));
    $user->setPassword($request->request->get('password')); // Auto-hashed by UserModel
    $user->setRoles(['ROLE_USER']);

    $entityManager = $this->getDoctrine()->getManager();
    $entityManager->persist($user);
    $entityManager->flush();

    return new JsonResponse(['success' => true]);
}

Implementation Patterns

Core Workflows

1. User Management

   • Registration: Use UserModel methods (setEmail, setPassword, setRoles).
   • Verification: Leverage isVerified flag and verify() method (if extended).
   • Role Assignment: Use addRole()/setRoles() with Symfony’s role hierarchy.

2. API Integration

   • Serialization: Override UserModel::serialize() for API responses.
   • Validation: Extend UserModel to add custom validation (e.g., isEmailUnique()).

3. Doctrine Events

   • Listen to prePersist/preUpdate for auto-tasks (e.g., password hashing):

     $user->addLifecycleCallback(function (UserModelInterface $user) {
         if ($user->isPasswordChanged()) {
             $user->hashPassword();
         }
     });
     

4. Security

   • Firewall: Configure Symfony’s security.yaml to use UserModelInterface:

     security:
         providers:
             app_user_provider:
                 entity: { class: App\Entity\User, property: email }
     

Integration Tips

• Custom Fields: Add fields to UserModel and update migrations:

  /**
   * @ORM\Column(type="string", nullable=true)
   */
  private ?string $phoneNumber = null;
  

• Event Dispatching: Trigger events (e.g., UserRegisteredEvent) in UserModel lifecycle methods.
• Testing: Use UserModel factories in PHPUnit:

  $user = UserModelFactory::create(['email' => 'test@example.com']);
  

Gotchas and Tips

Pitfalls

1. Email Uniqueness

   • Default UserModel lacks uniqueness validation. Add a custom validator or Doctrine constraint:

     use Doctrine\ORM\Mapping as ORM;
     /**
      * @ORM\UniqueEntity(fields="email", message="Email already taken")
      */
     

2. Password Hashing

   • Ensure UserModel uses Symfony’s PasswordHasherInterface. Override hashPassword() if needed:

     public function hashPassword(): void
     {
         $this->password = $this->passwordHasher->hashPassword(
             $this,
             $this->plainPassword
         );
     }
     

3. Role Hierarchy

   • Symfony’s role hierarchy may conflict with custom roles. Explicitly define roles in security.yaml:

     role_hierarchy:
         ROLE_ADMIN: [ROLE_USER, ROLE_ALLOWED_TO_SWITCH]
     

4. Migration Conflicts

   • If extending UserModel after initial migration, manually add new columns or use:

     php bin/console doctrine:schema:update --force
     

Debugging

• Doctrine Events: Enable debug mode for lifecycle callbacks:

  doctrine:
      orm:
          entity_listeners:
              Codyas\Skeleton\Model\UserModel: ~
  

• Validation Errors: Check Symfony’s validator component logs for UserModel constraints.

Extension Points

1. Custom User Interface Implement UserModelInterface methods (e.g., getFullName()) for reusable logic.

2. Audit Trails Extend UserModel to log changes via Doctrine extensions:

   use Gedmo\Mapping\Annotation as Gedmo;
   
   /**
    * @Gedmo\Timestampable(on="update")
    */
   private ?\DateTimeInterface $updatedAt = null;
   

3. Multi-Tenant Support Add a tenantId field to UserModel and filter queries in UserRepository:

   public function findByTenant(int $tenantId): array
   {
       return $this->createQueryBuilder('u')
           ->where('u.tenantId = :tenantId')
           ->setParameter('tenantId', $tenantId)
           ->getQuery()
           ->getResult();
   }
   

4. API Resources Use Symfony’s ApiPlatform to expose UserModel as a resource:

   # config/packages/api_platform.yaml
   resources:
       App\Entity\User:
           collectionOperations:
               post:
                   validation_context: ['registration']