Array Converter Bundle Laravel Package

Getting Started

Minimal Steps

1. Installation

   composer require dlin/array-converter-bundle
   

   Add to config/bundles.php:

   return [
       // ...
       Dlin\ArrayConverterBundle\DlinArrayConverterBundle::class => ['all' => true],
   ];
   

2. First Use Case Annotate a Doctrine entity or custom object:

   use Dlin\ArrayConverterBundle\Annotation\ArrayConverter;
   
   /**
    * @ArrayConverter(
    *     properties={
    *         "id": "getId",
    *         "name": "getName",
    *         "customKey": "getCustomValue"
    *     },
    *     exclude={"sensitiveField"}
    * )
    */
   class User {}
   

3. Convert to Array Use the converter service in a controller:

   use Dlin\ArrayConverterBundle\Converter\ArrayConverter;
   
   public function showAction(User $user, ArrayConverter $converter)
   {
       $array = $converter->toArray($user);
       return new JsonResponse($array);
   }
   

Implementation Patterns

Core Workflows

1. Serialization

   • Convert entities/objects to arrays for API responses:

     $converter->toArray($entity, ['group' => 'api']);
     

   • Use groups to control which properties are included:

     /**
      * @ArrayConverter(
      *     groups={"api", "admin"},
      *     properties={
      *         "id": "getId",
      *         "name": {"getName", "api"}
      *     }
      * )
      */
     

2. Deserialization

   • Convert arrays back to objects (e.g., for form submissions):

     $user = new User();
     $converter->fromArray($request->request->all(), $user);
     

3. Custom Converters

   • Extend the base converter for domain-specific logic:

     class CustomConverter extends ArrayConverter
     {
         public function toArray($object, array $options = [])
         {
             $array = parent::toArray($object, $options);
             $array['customField'] = $this->getCustomValue($object);
             return $array;
         }
     }
     

4. Integration with Controllers

   • Use dependency injection for reusable logic:

     public function updateAction(Request $request, User $user, ArrayConverter $converter)
     {
         $converter->fromArray($request->request->all(), $user);
         $em->persist($user);
         $em->flush();
         return $this->showAction($user, $converter);
     }
     

5. Response Wrapping

   • Wrap converted arrays with metadata:

     $data = $converter->toArray($entity);
     return new JsonResponse([
         'data' => $data,
         'meta' => ['timestamp' => now()->toIso8601String()]
     ]);
     

Integration Tips

• Doctrine Entities: Works seamlessly with Doctrine ORM entities.
• Custom Objects: Annotate any PHP object (e.g., DTOs, services).
• Symfony Forms: Use fromArray() to populate form data before validation.
• API Versioning: Combine with API platform or custom routing for versioned endpoints.
• Caching: Cache converted arrays if serialization is performance-critical:

  $cacheKey = md5(serialize($entity) . serialize($options));
  $array = $cache->get($cacheKey, function() use ($entity, $converter, $options) {
      return $converter->toArray($entity, $options);
  });
  

Gotchas and Tips

Pitfalls

1. Annotation Parsing

   • Ensure doctrine/annotations is installed and configured in composer.json:

     "require": {
         "doctrine/annotations": "^1.0"
     }
     

   • Clear cache after adding/removing annotations:

     php bin/console cache:clear
     

2. Circular References

   • Avoid circular references in objects (e.g., User ↔ Post with bidirectional relations). Use exclude or custom logic to break cycles:

     /**
      * @ArrayConverter(exclude={"posts"})
      */
     class User {}
     

3. Type Safety

   • The bundle assumes getter methods exist. Missing getters throw BadMethodCallException.
   • Validate property names in annotations match actual getter methods.

4. Legacy Code

   • The bundle is Symfony 2.x-only. Avoid mixing with Symfony 3+/4+/5+ features (e.g., autowiring, PHP 7.4+ attributes).

5. Performance

   • Reflection is used under the hood. Heavy use may impact performance. Cache converted arrays or use simpler serialization for high-traffic APIs.

Debugging

1. Annotation Errors

   • Check for syntax errors in annotations. Use @ArrayConverter without spaces:

     // Correct
     @ArrayConverter(properties={"id": "getId"})
     
     // Incorrect (throws error)
     @ArrayConverter (properties = {"id": "getId"})
     

2. Converter Not Found

   • Ensure the bundle is enabled in config/bundles.php and dependencies are installed.

3. Property Mapping Issues

   • Verify getter methods are public and follow naming conventions (e.g., getName() for property name).
   • Use var_dump() to inspect the converter’s output:

     $array = $converter->toArray($object);
     var_dump($array);
     

Extension Points

1. Custom Annotations

   • Extend the annotation parser to support custom logic:

     use Dlin\ArrayConverterBundle\Annotation\ArrayConverterParser;
     
     class CustomParser extends ArrayConverterParser
     {
         public function parse($method, $annotation)
         {
             // Custom parsing logic
             return parent::parse($method, $annotation);
         }
     }
     

   • Register the parser in services.yaml:

     services:
         App\CustomParser:
             tags: [dlin_array_converter.parser]
     

2. Event Listeners

   • Hook into the conversion process via events (if the bundle supports them; may require extension):

     // Hypothetical event listener
     $converter->addListener('preConvert', function($object, &$options) {
         $options['customFlag'] = true;
     });
     

3. Override Default Converter

   • Replace the default converter service:

     services:
         dlin_array_converter.converter:
             class: App\CustomConverter
             arguments: ['@annotation_reader']
     

4. Add Custom Data Transformers

   • Implement Dlin\ArrayConverterBundle\Converter\DataTransformerInterface:

     class DateTransformer implements DataTransformerInterface
     {
         public function transform($data)
         {
             return $data instanceof \DateTime ? $data->format('Y-m-d') : $data;
         }
     }
     

   • Register the transformer in the converter’s configuration.

Configuration Quirks

1. Annotation Reader

   • The bundle uses Symfony’s AnnotationReader. Ensure it’s configured in config/packages/doctrine.yaml:

     doctrine:
         orm:
             annotations:
                 listener: true
     

2. Service Autowiring

   • The bundle predates Symfony’s autowiring. Manually bind the converter if needed:

     services:
         Dlin\ArrayConverterBundle\Converter\ArrayConverter:
             arguments: ['@annotation_reader']
     

3. Group-Based Filtering

   • Groups are case-sensitive. Define groups explicitly in annotations:

     @ArrayConverter(groups={"api", "public"})
     

4. Exclusion Logic

   • exclude takes precedence over properties. Excluded fields are omitted even if listed in properties.

Pro Tips

1. Use for DTOs

   • Convert entities to DTOs for API responses:

     $dto = new UserDto();
     $converter->toArray($entity, $dto);
     

2. Combine with Serializer

   • Use alongside symfony/serializer for complex types (e.g., nested objects):

     $serializer = $container->get('serializer');
     $data = $serializer->serialize($object, 'json');
     

3. API Documentation

   • Generate OpenAPI/Swagger specs by inspecting annotations:

     // Pseudocode: Extract @ArrayConverter metadata for API docs
     $reflection = new \ReflectionClass($entity);
     $annotation = $reflection->getAnnotation('ArrayConverter');
     

4. Testing

   • Mock the converter in tests:

     $converter = $this->createMock(ArrayConverter::class);
     $converter->method('toArray')->