Base Entity Bundle Laravel Package

Getting Started

Minimal Setup

1. Installation

   composer require schvoy/base-entity-bundle
   

   Add to config/bundles.php:

   return [
       // ...
       Schvoy\BaseEntityBundle\SchvoyBaseEntityBundle::class => ['all' => true],
   ];
   

2. First Use Case: Create a Base Entity Extend Schvoy\BaseEntityBundle\Entity\BaseEntity in your custom entity:

   namespace App\Entity;
   
   use Schvoy\BaseEntityBundle\Entity\BaseEntity as BaseEntityBundle;
   
   class User extends BaseEntityBundle
   {
       // Your custom fields/methods
   }
   

3. Key Features to Explore

   • Traits: Check Schvoy\BaseEntityBundle\Traits for reusable behaviors (e.g., Timestampable, SoftDeletable).
   • Repositories: Override Schvoy\BaseEntityBundle\Repository\BaseRepository for custom logic.
   • Doctrine Events: Built-in listeners for common operations (e.g., prePersist, preUpdate).

Implementation Patterns

Workflow: CRUD with Base Features

1. Entity Creation

   use Schvoy\BaseEntityBundle\Entity\BaseEntity;
   
   class Product extends BaseEntity
   {
       #[ORM\Column]
       private string $name;
   
       // Auto-generated: id, createdAt, updatedAt, deletedAt (if SoftDeletable)
   }
   

2. Repository Integration

   use Schvoy\BaseEntityBundle\Repository\BaseRepository;
   
   class ProductRepository extends BaseRepository
   {
       public function findActive(): array
       {
           return $this->createQueryBuilder('p')
               ->where('p.deletedAt IS NULL')
               ->getQuery()
               ->getResult();
       }
   }
   

3. Service Layer Use traits like Timestampable to auto-manage timestamps:

   use Schvoy\BaseEntityBundle\Traits\Timestampable;
   
   class ProductService
   {
       use Timestampable;
   
       public function createProduct(string $name): Product
       {
           $product = new Product();
           $product->setName($name);
           $this->setCreatedAt($product); // Auto-set via trait
           return $product;
       }
   }
   

Common Patterns

• Soft Deletes: Enable via SoftDeletable trait and configure deletedAt column.
• Audit Logs: Extend Schvoy\BaseEntityBundle\Traits\AuditLoggable for change tracking.
• Validation: Use Schvoy\BaseEntityBundle\Validator\Constraints (e.g., @UniqueEntity) in entities.

Gotchas and Tips

Pitfalls

1. Doctrine Events Collisions

   • If extending BaseRepository, ensure your event subscribers don’t conflict with the bundle’s default listeners.
   • Fix: Use priority in subscriber services or override methods explicitly.

2. Soft Delete Quirks

   • deletedAt is nullable by default. Ensure your ProductRepository filters for IS NULL when querying "active" records.
   • Tip: Add a isDeleted() method to BaseEntity for consistency:

     public function isDeleted(): bool
     {
         return $this->deletedAt !== null;
     }
     

3. Timestamp Precision

   • The bundle uses DateTimeImmutable for timestamps. If your app uses DateTime, conflicts may arise.
   • Fix: Standardize on one type in your project.

Debugging Tips

• Enable SQL Logging: Add to config/packages/dev/doctrine.yaml:

  doctrine:
      dbal:
          logging: true
          profiling: true
  

  Helps verify if deletedAt/timestamps are updating as expected.

• Check Event Order: Use Symfony’s debug:event-dispatcher to inspect event priorities:

  php bin/console debug:event-dispatcher
  

Extension Points

1. Custom Traits Add your own traits to Schvoy\BaseEntityBundle\Entity\BaseEntity:

   namespace App\Entity;
   
   use Schvoy\BaseEntityBundle\Entity\BaseEntity;
   use App\Traits\CustomBehavior;
   
   class User extends BaseEntity
   {
       use CustomBehavior;
   }
   

2. Override Base Methods Extend BaseRepository to modify default queries:

   class ProductRepository extends BaseRepository
   {
       public function findByName(string $name): ?Product
       {
           return $this->createQueryBuilder('p')
               ->andWhere('p.name = :name')
               ->setParameter('name', $name)
               ->getOneOrNullResult();
       }
   }
   

3. Configuration Override bundle defaults in config/packages/schvoy_base_entity.yaml:

   schvoy_base_entity:
       soft_delete_column: 'is_deleted' # Custom column name
       timestamp_precision: 3 # Milliseconds