Models Management Fractal Bundle Laravel Package

Getting Started

Minimal Setup

1. Install Dependencies

   composer require dmytrof/models-management-fractal-bundle league/fractal
   

   Ensure dmytrof/models-management-bundle is also installed (required dependency).

2. Enable the Bundle Add to config/bundles.php:

   Dmytrof\ModelsManagementFractalBundle\DmytrofModelsManagementFractalBundle::class => ['all' => true],
   

3. First Use Case: Transform a Model Create a transformer for your model (e.g., src/Transformer/UserTransformer.php):

   namespace App\Transformer;
   
   use Dmytrof\ModelsManagementFractalBundle\Transformer\AbstractTransformer;
   use App\Entity\User;
   
   class UserTransformer extends AbstractTransformer
   {
       public function transform(User $user): array
       {
           return [
               'id' => $user->getId(),
               'name' => $user->getName(),
               'email' => $user->getEmail(),
           ];
       }
   }
   

4. Register the Transformer Bind the transformer in a service configuration (e.g., config/services.yaml):

   services:
       App\Transformer\UserTransformer:
           tags: ['dmytrof_models_management.transformer']
   

5. Use in a Controller

   use Dmytrof\ModelsManagementFractalBundle\Manager\TransformerManagerInterface;
   
   class UserController
   {
       public function __construct(private TransformerManagerInterface $transformerManager)
       {
       }
   
       public function show(User $user)
       {
           $transformer = $this->transformerManager->getTransformer('App\Entity\User');
           $data = $transformer->transform($user);
   
           return $this->json($data);
       }
   }
   

Implementation Patterns

Core Workflow

1. Transformer Registration

   • Extend AbstractTransformer for each entity.
   • Tag transformers with dmytrof_models_management.transformer to auto-register.
   • Alternatively, manually register via TransformerManager.

2. Nested Transformations Use includeAntics or excludeAntics in the transformerManager->transform() method:

   $data = $this->transformerManager->transform(
       $user,
       null,
       ['includeAntics' => ['posts']]
   );
   

3. Collection Handling Transform collections of entities:

   $users = $this->userRepository->findAll();
   $data = $this->transformerManager->transformCollection($users);
   

4. Custom Serialization Override serialize() in AbstractTransformer for custom JSON/XML output:

   public function serialize($data): string
   {
       return json_encode($data, JSON_PRETTY_PRINT);
   }
   

Integration Tips

• Symfony Serializer Integration Combine with Symfony’s SerializerComponent for additional format support (e.g., XML, CSV):

  use Symfony\Component\Serializer\SerializerInterface;
  
  $serializer = $this->container->get(SerializerInterface::class);
  $serialized = $serializer->serialize($data, 'json');
  

• Event Listeners Attach listeners to dmytrof.models_management.transformer events for pre/post-processing:

  // src/EventListener/TransformListener.php
  class TransformListener
  {
      public function onTransform(object $entity, array $data): void
      {
          $data['custom_field'] = 'dynamic_value';
      }
  }
  

• API Platform Integration Use with API Platform for automatic API generation:

  # config/api_platform/resources.yaml
  resources:
      App\Entity\User:
          collectionOperations:
              get:
                  normalization_context:
                      groups: ['user:read']
          itemOperations:
              get:
                  normalization_context:
                      groups: ['user:read']
  

Gotchas and Tips

Pitfalls

1. Transformer Auto-Discovery

   • Transformers must be tagged with dmytrof_models_management.transformer or manually registered.
   • Forgetting this causes TransformerNotFoundException.

2. Circular References

   • Fractal’s default serializer may fail on circular references (e.g., User ↔ Post).
   • Fix: Use includeAntics or implement __toString() in entities.

3. Case Sensitivity

   • Transformer class names must match the entity namespace exactly (e.g., App\Entity\User → App\Transformer\UserTransformer).

4. Bundle Dependency

   • Requires dmytrof/models-management-bundle. Install it first:

     composer require dmytrof/models-management-bundle
     

Debugging Tips

1. Check Registered Transformers Dump available transformers:

   $transformers = $this->transformerManager->getTransformers();
   dump(array_keys($transformers));
   

2. Enable Fractal Debugging Set the FRACTAL_DEBUG environment variable to true for detailed error logs.

3. Override Default Manager Extend TransformerManager to add custom logic:

   class CustomTransformerManager extends TransformerManager
   {
       protected function createTransformer(string $entityClass): TransformerAbstract
       {
           // Custom logic here
           return parent::createTransformer($entityClass);
       }
   }
   

Extension Points

1. Custom Transformer Manager Replace the default manager in services.yaml:

   services:
       Dmytrof\ModelsManagementFractalBundle\Manager\TransformerManagerInterface: '@App\Service\CustomTransformerManager'
   

2. Add Serializer Formats Extend the bundle’s FractalManager to support additional formats:

   use League\Fractal\Manager;
   use League\Fractal\Serializer\DataArraySerializer;
   
   class CustomFractalManager extends Manager
   {
       public function __construct()
       {
           $this->parser = new DataArrayParser();
           $this->serializer = new DataArraySerializer();
       }
   }
   

3. Modify Transformer Resolution Override resolveTransformer() in a custom TransformerManager to implement custom resolution logic (e.g., fallback transformers).

Configuration Quirks

• Bundle Priority Ensure this bundle loads after dmytrof/models-management-bundle in bundles.php.

• Environment-Specific Transformers Use Symfony’s environment-aware services to load different transformers per environment:

  # config/services_test.yaml
  App\Transformer\UserTransformer:
      tags: ['dmytrof_models_management.transformer']
      calls:
          - [setEnvironment, ['test']]