Extended Attribute Type Laravel Package

Getting Started

Minimal Steps to Begin

1. Installation:

   composer require akeneo/extended-attribute-type:2.1
   

   Ensure your Akeneo PIM version matches the requirements.

2. Bundle Registration: Add the bundle to app/AppKernel.php:

   new Pim\Bundle\ExtendedAttributeTypeBundle\PimExtendedAttributeTypeBundle(),
   

3. Elasticsearch Configuration: Update app/config/pim_parameters.yml to include the new Elasticsearch mappings:

   elasticsearch_index_configuration_files:
       - '%kernel.root_dir%/../vendor/akeneo/pim-community-dev/src/Pim/Bundle/CatalogBundle/Resources/elasticsearch/index_configuration.yml'
       - '%kernel.root_dir%/../vendor/akeneo/extended-attribute-type/src/Resources/config/elasticsearch/index_configuration.yml'
   

   For Enterprise Edition, include the additional EE-specific file.

4. Reset Indexes (if upgrading or migrating):

   php bin/console cache:clear --no-warmup --env=prod
   php bin/console akeneo:elasticsearch:reset-indexes --env=prod
   php bin/console pim:product:index --all --env=prod
   php bin/console pim:product-model:index --all --env=prod
   

5. First Use Case: Create a TextCollection attribute type via the Akeneo UI:

   • Navigate to Attributes > Create Attribute.
   • Select TextCollection as the type.
   • Define a label (e.g., "Product Features") and save.
   • Assign it to a product family or model.

Implementation Patterns

Workflows

1. Attribute Creation & Management:

   • Use the Akeneo UI to define TextCollection attributes for structured data (e.g., lists of URLs, multi-line descriptions, or ordered features).
   • Example: Store a product’s "Key Selling Points" as a collection of strings.

2. Data Population:

   • Populate TextCollection attributes via:
     • UI: Manually add/remove items in the product edit form.
     • API: Use the Akeneo REST API to batch-update products with collections:

       {
         "data": {
           "item": {
             "identifier": "product_123",
             "values": {
               "pim_catalog_textcollection_attribute": {
                 "data": ["Feature 1", "Feature 2", "https://example.com"]
               }
             }
           }
         }
       }
       

     • CSV Import: Use the Akeneo CSV importer with the pim_catalog_textcollection_attribute column.

3. Querying & Filtering:

   • Elasticsearch: Leverage the bundle’s Elasticsearch mappings to search/filter products by TextCollection values. Example query (via Akeneo UI or custom API):

     {
       "query": {
         "bool": {
           "must": [
             {
               "nested": {
                 "path": "pim_catalog_textcollection_attribute",
                 "query": {
                   "match": {
                     "pim_catalog_textcollection_attribute.data": "Feature 1"
                   }
                 }
               }
             }
           ]
         }
       }
     }
     

   • PHP API: Use the Pim\Bundle\CatalogBundle\Provider\Product\Query\ProductQueryBuilder to filter products:

     $queryBuilder->addFilter('pim_catalog_textcollection_attribute', 'Feature 1', 'contains');
     

4. Template Integration:

   • Render TextCollection attributes in Twig templates:

     {% for item in product.get('pim_catalog_textcollection_attribute') %}
       <li>{{ item }}</li>
     {% endfor %}
     

   • For URLs, add hyperlinks:

     {% for item in product.get('pim_catalog_textcollection_attribute') %}
       {% if item matches '/^https?:\/\//' %}
         <a href="{{ item }}">{{ item }}</a>
       {% else %}
         {{ item }}
       {% endif %}
     {% endfor %}
     

5. Validation:

   • Enforce constraints via Akeneo’s attribute validation (e.g., max items, required fields).
   • Example: Set a TextCollection attribute to require at least 1 item.

Integration Tips

1. Custom Attribute Types:

   • Extend the bundle to add your own attribute types by:
     • Creating a new class extending Pim\Bundle\ExtendedAttributeTypeBundle\Model\Attribute\TextCollectionAttribute.
     • Registering it in services.yml and updating Elasticsearch mappings.

2. Event Listeners:

   • Hook into Akeneo events to manipulate TextCollection data:

     # app/config/services.yml
     services:
         app.textcollection_listener:
             class: AppBundle\EventListener\TextCollectionListener
             tags:
                 - { name: kernel.event_listener, event: pim_catalog.product.update.pre, method: onPreUpdate }
     

     public function onPreUpdate(ProductUpdateEvent $event) {
         $product = $event->getProduct();
         $collection = $product->get('pim_catalog_textcollection_attribute');
         // Modify collection logic here
     }
     

3. Migration Scripts:

   • Use Doctrine migrations to backfill TextCollection attributes:

     $em = $this->getEntityManager();
     $products = $em->getRepository('PimCatalogBundle:Product')->findAll();
     foreach ($products as $product) {
         $product->set('pim_catalog_textcollection_attribute', ['Old data', 'Migrated']);
         $em->flush();
     }
     

4. Testing:

   • Test TextCollection attributes in PHPUnit:

     public function testTextCollectionAttribute() {
         $product = $this->createProduct();
         $product->set('pim_catalog_textcollection_attribute', ['Test 1', 'Test 2']);
         $this->assertEquals(['Test 1', 'Test 2'], $product->get('pim_catalog_textcollection_attribute'));
     }
     

Gotchas and Tips

Pitfalls

1. Elasticsearch Index Reset:

   • Critical: Forgetting to reset Elasticsearch indexes after installation/upgrades will cause TextCollection attributes to fail silently.
   • Fix: Always run:

     php bin/console akeneo:elasticsearch:reset-indexes --env=prod
     

2. Data Serialization:

   • TextCollection values are stored as JSON arrays in the database. Ensure your custom code handles serialization/deserialization:

     // Correct:
     $collection = json_decode($product->get('pim_catalog_textcollection_attribute'), true);
     // Incorrect (may fail for non-JSON data):
     $collection = $product->get('pim_catalog_textcollection_attribute');
     

3. UI Glitches:

   • The Akeneo UI may not render TextCollection fields correctly if:
     • The attribute is assigned to a product model but not a product.
     • The Elasticsearch index is corrupted.
   • Fix: Clear caches and verify index mappings.

4. Performance:

   • Large TextCollection datasets (e.g., >100 items) may slow down:
     • Product indexing.
     • Elasticsearch queries.
   • Mitigation: Limit collection size via validation or use pagination in custom queries.

5. Version Compatibility:

   • The bundle is not actively maintained (last release: 2018). Test thoroughly with:
     • Akeneo PIM 2.2+ (for 2.1.* bundle version).
     • Avoid mixing with newer Akeneo versions (e.g., 5.x) without forks.

Debugging Tips

1. Check Elasticsearch Mappings:

   • Verify mappings are loaded:

     curl -XGET 'http://localhost:9200/pim_product/_mapping?pretty'
     

   • Look for pim_catalog_textcollection_attribute under properties.

2. Log Attribute Data:

   • Dump TextCollection data to debug:

     use Symfony\Component\Debug\Debug;
     Debug::dump($product->get('pim_catalog_textcollection_attribute'));
     

3. Common Errors:

   • "Attribute not found": Ensure the attribute is:
     • Saved in the Akeneo UI.
     • Assigned to the correct product family/model.
   • "Invalid data format": Validate JSON structure in custom code.

Extension Points

1. Custom Validators:

   • Add validation logic for TextCollection attributes:

     # config/validation.yml
     Pim\Bundle\CatalogBundle\Entity\Product:
         constraints:
             - Akeneo\Bundle\ExtendedAttributeTypeBundle\Validator\Constraints\TextCollection:
                 maxItems: 10
                 allowedPatterns: ["^https?://"]
     

2. Custom Templates:

   • Override Twig templates for TextCollection rendering: