Doctrine Extensions Bundle Laravel Package

Getting Started

Minimal Steps

1. Installation Run:

   composer require byteincoffee/doctrine-extensions-bundle
   

   (Note: The README references fsi/doctrine-extensions-bundle, but the package name in the prompt is byteincoffee/doctrine-extensions-bundle. Adjust accordingly.)

2. Register the Bundle Add to config/bundles.php (Symfony 4+):

   return [
       // ...
       FSi\Bundle\DoctrineExtensionsBundle\FSiDoctrineExtensionsBundle::class => ['all' => true],
   ];
   

3. Configure Listeners Enable extensions in config/packages/fsi_doctrine_extensions.yaml:

   fsi_doctrine_extensions:
       orm:
           default:
               translatable: true
               uploadable: true
   

4. Enable Translations Ensure framework.yaml has:

   framework:
       translator:
           fallback: '%locale%'
   

5. First Use Case Create an entity with @FSi\Uploadable or @FSi\Translatable annotations and use them in forms/controllers.

Implementation Patterns

Common Workflows

1. Uploadable Fields

   • Use @FSi\Uploadable on properties to handle file uploads.
   • Example:

     use FSi\DoctrineExtensions\Uploadable\Mapping\Annotation as FSi;
     
     /**
      * @FSi\Uploadable
      * @Assert\File(maxSize="1024k")
      */
     private $file;
     

   • Form Integration:

     $builder->add('file', FileType::class, [
         'label' => 'Upload File',
     ]);
     

2. Translatable Entities

   • Use @FSi\Translatable on entities requiring translations.
   • Example:

     use FSi\DoctrineExtensions\Translatable\Mapping\Annotation as FSi;
     
     /**
      * @FSi\Translatable
      * @ORM\Entity
      */
     class Product {}
     

   • Translation Handling:

     $product->setTranslation('name', 'en', 'New Name');
     $translator->trans($product->getTranslation('name', 'en'));
     

3. Sluggable Fields

   • Use @FSi\Sluggable for auto-generated slugs.
   • Example:

     /**
      * @FSi\Sluggable(fields={"title"})
      */
     private $slug;
     

4. Soft-Deletable Entities

   • Use @FSi\SoftDeleteable for soft deletes.
   • Example:

     /**
      * @FSi\SoftDeleteable(fieldName="deletedAt")
      */
     private $deletedAt;
     

Integration Tips

• Doctrine Lifecycle Callbacks: Extend EntityListener for custom logic.
• Form Events: Use PRE_SET_DATA/PRE_SUBMIT to handle translations/uploads dynamically.
• QueryBuilder: Filter translatable entities with:

  $qb->andWhere('e.translations IS NOT NULL');
  

Gotchas and Tips

Pitfalls

1. Listener Configuration

   • Issue: Extensions won’t work if listeners aren’t enabled in config.yaml.
   • Fix: Always verify fsi_doctrine_extensions.orm.default settings.

2. File Uploads

   • Issue: Uploaded files may not persist if @FSi\Uploadable is misconfigured.
   • Fix: Ensure the property type is string (stores file paths) and validate with @Assert\File.

3. Translations

   • Issue: Missing translations throw TranslationNotFoundException.
   • Fix: Use getTranslation() with fallbacks:

     $product->getTranslation('name', 'en', 'Default Name');
     

4. Doctrine Events

   • Issue: Custom listeners may conflict with bundle defaults.
   • Fix: Override bundle services in config/services.yaml:

     FSi\DoctrineExtensions\Uploadable\UploadableListener: ~
     

Debugging

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

  doctrine:
      dbal:
          logging: true
          profiling: true
  

• Check Events: Use Symfony Profiler’s "Doctrine" tab to verify listeners are fired.

Extension Points

1. Custom Upload Handlers

   • Extend UploadableListener to modify file storage logic.

2. Translation Providers

   • Implement TranslationProviderInterface for custom translation sources.

3. Sluggable Strategies

   • Override SluggableListener to change slug generation rules.

Configuration Quirks

• Locale Fallback: Ensure %locale% in framework.translator.fallback matches your app’s default locale.
• Database Schema: Run php bin/console doctrine:schema:update --force after adding new extensions to update the schema.