Entity Bundle Laravel Package

Getting Started

Minimal Setup

1. Installation Add the bundle via Composer:

   composer require austral/entity-bundle
   

   Enable the bundle in config/bundles.php:

   Austral\EntityBundle\EntityBundle::class => ['all' => true],
   

2. First Use Case: Entity Utilities The bundle provides core utilities for Symfony entities. Start by leveraging its EntityHelper service for common operations:

   use Austral\EntityBundle\Helper\EntityHelper;
   
   class SomeService {
       public function __construct(private EntityHelper $entityHelper) {}
   
       public function getEntityId(object $entity): ?int {
           return $this->entityHelper->getId($entity);
       }
   }
   

3. Key Entry Points

   • Interfaces: Check if an entity implements Austral\EntityBundle\Interfaces\TranslateMasterInterface for translation support.
   • Doctrine Integration: Works seamlessly with Doctrine ORM (v2.15+ or v3.2+). No extra config needed for basic usage.
   • UUID Support: Uses ramsey/uuid for UUID handling (e.g., EntityHelper::generateUuid()).

Implementation Patterns

Common Workflows

1. Entity Validation & Sanitization Use EntityHelper::sanitize() to clean entity properties (e.g., trimming strings, converting case):

   $entity = $this->entityHelper->sanitize($entity, ['name' => 'trim']);
   

2. Dot Notation Access Leverage adbario/php-dot-notation for nested property access:

   $value = $this->entityHelper->getProperty($entity, 'user.address.city');
   

3. Translation Handling For translatable entities (implementing TranslateMasterInterface), use:

   $translations = $this->entityHelper->getTranslations($entity);
   

4. Migration Utilities Combine with doctrine/doctrine-migrations-bundle for schema-aware migrations:

   use Austral\EntityBundle\Migration\MigrationHelper;
   
   $migrationHelper = new MigrationHelper($entityManager);
   $migrationHelper->addColumnIfNotExists('App\Entity\User', 'email_verified', 'boolean');
   

Integration Tips

• Event Subscribers: Extend entity lifecycle events (e.g., prePersist) using the bundle’s EntityEvents:

  use Austral\EntityBundle\Event\EntityEvents;
  
  $dispatcher->addListener(EntityEvents::PRE_PERSIST, function ($entity) {
      // Pre-persist logic
  });
  

• Custom Interfaces: Implement Austral\EntityBundle\Interfaces\EntityInterface for consistent entity behavior across projects.
• Doctrine Extensions: Works with gedmo/doctrine-extensions (e.g., timestamps, slugs) out of the box.

Gotchas and Tips

Pitfalls

1. UUID Generation

   • Issue: EntityHelper::generateUuid() may conflict with existing UUID fields if not handled carefully.
   • Fix: Explicitly set the UUID field name in the helper or override the method:

     $this->entityHelper->generateUuid('custom_uuid_field');
     

2. Translation Interface

   • Issue: TranslateMasterInterface checks can fail if the entity doesn’t properly implement the interface.
   • Fix: Use instanceof checks or extend the interface:

     if ($entity instanceof \Austral\EntityBundle\Interfaces\TranslateMasterInterface) {
         // Safe to use translation methods
     }
     

3. Doctrine Version Mismatch

   • Issue: Bundle requires Doctrine ORM 2.15.* || ^3.2. Mixing versions may cause errors.
   • Fix: Pin Doctrine versions in composer.json:

     "require": {
         "doctrine/orm": "^3.2"
     }
     

4. Dot Notation Edge Cases

   • Issue: getProperty() may throw exceptions for non-existent paths.
   • Fix: Use getPropertySafe() or validate paths first:

     $value = $this->entityHelper->getPropertySafe($entity, 'user.address.city');
     

Debugging Tips

• Enable Debug Mode: Set AUSTRL_ENTITY_DEBUG=true in .env to log entity operations.
• Check Interfaces: Use var_dump(get_class_implements($entity)) to verify implemented interfaces.
• Migration Conflicts: Run php bin/console doctrine:migrations:diff after changes to avoid schema issues.

Extension Points

1. Custom Helpers Extend Austral\EntityBundle\Helper\AbstractEntityHelper to add project-specific methods:

   class CustomEntityHelper extends AbstractEntityHelper {
       public function customMethod(object $entity) { ... }
   }
   

   Register as a service in services.yaml:

   services:
       App\Helper\CustomEntityHelper:
           arguments: ['@doctrine.orm.entity_manager']
           tags: ['austral.entity.helper']
   

2. Event Listeners Create listeners for EntityEvents::POST_LOAD or EntityEvents::PRE_REMOVE:

   use Austral\EntityBundle\Event\EntityEvents;
   
   $dispatcher->addListener(EntityEvents::POST_LOAD, function ($entity) {
       // Post-load logic (e.g., lazy-loading)
   });
   

3. Doctrine Extensions Override default behaviors by binding custom extensions to the EntityManager:

   $em->getConfiguration()->addCustomStringFunction(
       'CONCAT_WS',
       'Austral\EntityBundle\DBAL\Function\ConcatWs'
   );