Doctrine Bundle Laravel Package

Getting Started

Minimal Steps

1. Installation

   composer require adcog-cpi/doctrine-bundle
   

   Ensure EBDoctrineBundle is enabled in config/bundles.php:

   return [
       // ...
       AdcogCpi\DoctrineBundle\EBDoctrineBundle::class => ['all' => true],
   ];
   

2. Basic Configuration Publish the default config to customize:

   php bin/console config:dump-reference AdcogCpi\DoctrineBundle\Configuration
   

   Override in config/packages/eb_doctrine.yaml:

   eb_doctrine:
       filesystem:
           web_path: "/uploads"
           secured_path: "%kernel.project_dir%/var/uploads"
   

3. First Use Case: File Handling Use the FileManager service to handle file uploads/storing:

   use AdcogCpi\DoctrineBundle\Service\FileManager;
   
   class MyController extends AbstractController {
       public function upload(FileManager $fileManager, UploadedFile $file) {
           $path = $fileManager->store($file, 'user_avatars');
           // $path now contains the secured path (e.g., /var/uploads/user_avatars/...)
       }
   }
   

Implementation Patterns

File Management Workflow

1. Storing Files

   $fileManager->store($uploadedFile, 'entity_class_name', $entityId);
   

   • Automatically generates paths using web_path/secured_path + use_env_discriminator/use_class_discriminator.
   • Example output path: /var/uploads/dev/User/123/filename.ext (if use_env_discriminator and use_class_discriminator are true).

2. Retrieving Files

   $webUrl = $fileManager->getWebPath($securedPath);
   // Converts secured path to web-accessible URL (e.g., /uploads/dev/User/123/filename.ext)
   

3. Deleting Files

   $fileManager->delete($securedPath);
   

Pagination Integration

Use the Paginator service for consistent pagination across controllers:

use AdcogCpi\DoctrineBundle\Service\Paginator;

class ProductController {
    public function index(Paginator $paginator, EntityManagerInterface $em) {
        $query = $em->createQuery('SELECT p FROM App\Entity\Product p');
        $results = $paginator->paginate($query, $this->get('request_stack')->getCurrentRequest()->query->getInt('page', 1));
        // $results includes data + pagination metadata (total, limit, etc.)
    }
}

Logging Messages

Leverage the Logger service for standardized CRUD messages:

use AdcogCpi\DoctrineBundle\Service\Logger;

class ProductController {
    public function create(Logger $logger, Product $product) {
        $logger->persisted($product, 'product');
        // Logs: "L'élément product a été créé avec succès !"
    }
}

Gotchas and Tips

Pitfalls

1. Path Generation Quirks

   • If use_env_discriminator is false, paths ignore the environment (e.g., dev/prod).
   • If use_class_discriminator is false, paths flatten to /var/uploads/123/filename.ext instead of /var/uploads/User/123/filename.ext.
   • Fix: Verify paths after configuration changes with:

     $fileManager->getSecuredPath('test', 'User', 123);
     

2. Paginator Defaults

   • If default_limit is null, the bundle uses Symfony’s default (e.g., 30).
   • Tip: Explicitly set default_limit: 10 in config to avoid surprises.

3. File Deletion Race Conditions

   • The delete() method does not check if the file exists.
   • Tip: Wrap in a try-catch or use file_exists() first:

     if (file_exists($securedPath)) {
         $fileManager->delete($securedPath);
     }
     

Debugging

• Log Paths: Enable debug mode to log generated paths:

  eb_doctrine:
      filesystem:
          debug: true
  

• Check Config: Validate config with:

  php bin/console debug:config eb_doctrine
  

Extension Points

1. Custom File Naming Override the FileNamer service to implement custom logic (e.g., UUIDs):

   services:
       AdcogCpi\DoctrineBundle\Service\FileNamer:
           class: App\Service\CustomFileNamer
           arguments:
               $original: '@AdcogCpi\DoctrineBundle\Service\FileNamer'
   

2. Translation Keys Replace hardcoded messages with translation keys by extending the Logger:

   $logger->setTranslationDomain('messages');
   $logger->persisted($entity, 'product'); // Uses 'messages.product.created' key
   

3. Depth Handling

   • Set depth: 3 to limit path depth (e.g., /var/uploads/User/12/3/filename.ext).
   • Warning: Depth 0 disables directory structure entirely (files dumped in root).