Platform Serialised Fields Laravel Package

Getting Started

Minimal Setup

1. Installation:

   composer require oro/entity-serialized-fields-bundle
   

   Ensure Oro\Bundle\EntityExtendBundle\OroEntityExtendBundle is also installed (this package depends on it).

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

   Oro\Bundle\EntityExtendBundle\OroEntityExtendBundle::class => ['all' => true],
   Oro\EntitySerializedFieldsBundle\OroEntitySerializedFieldsBundle::class => ['all' => true],
   

3. First Use Case: Extend an entity (e.g., Product) with a serialized field:

   php bin/console oro:entity-extend:create-field --entity=Product --field-name=customAttributes --type=serialized
   

   This generates a migration and adds a customAttributes column (e.g., product_custom_attributes) to store JSON/array data.

4. Accessing Data:

   $product = $entityManager->getRepository(Product::class)->find(1);
   $customData = $product->getCustomAttributes(); // Returns array/JSON
   $product->setCustomAttributes(['key' => 'value']);
   

Implementation Patterns

Workflows

1. Dynamic Field Management:

   • Use the bundle to add fields (e.g., config, metadata) without schema migrations.
   • Example: Store multi-language descriptions or nested configurations.

   // In a form type
   $builder->add('customAttributes', SerializedFieldType::class, [
       'label' => 'Custom Attributes',
       'required' => false,
   ]);
   

2. Data Validation:

   • Validate serialized data via constraints (e.g., Assert\Json, Assert\Type).

   use Symfony\Component\Validator\Constraints as Assert;
   
   /**
    * @Assert\Type("array")
    * @Assert\Json()
    */
   private $customAttributes;
   

3. Querying Serialized Data:

   • Use Doctrine extensions or custom DQL for partial queries (e.g., WHERE customAttributes->>'$.key' = 'value').
   • For complex queries, denormalize data to a separate table via a listener.

4. Integration with OroPlatform:

   • Leverage Oro’s grid system to display/edit serialized fields:

   # oro/platform/src/Oro/Bundle/UIBundle/Resources/config/oro/grid.yml
   ProductGrid:
       columns:
           customAttributes:
               type: twig
               template: OroUIBundle:Grid:FieldValue.html.twig
               frontend_options:
                   field: customAttributes
   

5. Migration Strategy:

   • Use oro:entity-extend:create-field for new fields.
   • For existing data, write a data fixture or one-time migration:

   $product->setCustomAttributes(json_decode($oldData, true));
   $entityManager->flush();
   

Gotchas and Tips

Pitfalls

1. Performance:

   • Serialized fields disable Doctrine’s query cache for the column. Avoid deep nesting or large payloads.
   • Tip: Use jsonb (PostgreSQL) or JSON (MySQL 5.7+) for better indexing/querying.

2. Schema Locks:

   • The bundle adds a column during installation. Ensure no migrations are running in parallel.

3. Data Corruption:

   • Invalid JSON/array data can break serialization. Validate input rigorously.
   • Tip: Use json_last_error() in PHP to debug malformed data.

4. Doctrine Proxy Issues:

   • Serialized fields may cause proxy initialization problems. Use @ORM\LazyGroup or fetch data eagerly:

   $query->setHint(QueryHint::HINT_REFRESH, 'Product');
   

5. OroPlatform-Specific:

   • The bundle assumes Oro’s entity extension system. Custom field types (e.g., serialized) may conflict with other bundles.

Debugging

• DQL Errors: Use JSON_EXTRACT() (MySQL) or ->> (PostgreSQL) for partial queries. Example:

  SELECT p FROM Product p WHERE JSON_EXTRACT(p.customAttributes, '$.key') = 'value'
  

• Field Not Found: Verify the field was created via:

  php bin/console oro:entity-extend:list-fields Product
  

• Serialization Failures: Check for circular references or non-serializable objects (e.g., Doctrine proxies). Use json_encode($data, JSON_THROW_ON_ERROR).

Extension Points

1. Custom Serialization: Override the serializer via dependency injection:

   services:
       app.serialized_field_serializer:
           class: App\Serializer\CustomSerializer
           tags:
               - { name: oro_entity_extend.serializer, type: serialized }
   

2. Field Type Extensions: Extend the SerializedFieldType in Symfony forms to add custom widgets or validation.

3. Event Listeners: Hook into oro_entity_extend.field.create or oro_entity_extend.field.update to log changes or trigger actions.

Configuration Quirks

• Default Storage Engine: The bundle uses Doctrine’s json type by default. For MySQL < 5.7, configure a custom type:

  oro_entity_extend:
      field_types:
          serialized:
              type: string
              length: 65535
  

• Legacy Data: If migrating from a non-serialized field, ensure the new column is nullable during the transition.