Custom Entity Bundle Laravel Package

Getting Started

Minimal Setup for Akeneo PIM

1. Installation

   composer require adeoweb/custom-entity-bundle:"5.0.*"
   

   Ensure your Akeneo PIM version matches the requirements table.

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

   return [
       // ...
       Adeoweb\CustomEntityBundle\AdeowebCustomEntityBundle::class => ['all' => true],
   ];
   

3. First Use Case: Create a Custom Entity Define a YAML config file (e.g., config/akeneo/custom_entity/my_custom_entity.yml):

   akeneo_custom_entity:
       entities:
           my_custom_entity:
               label: "My Custom Entity"
               class: "App\Entity\CustomEntity"
               form:
                   fields:
                       - { property: "name", type: "text", label: "Name" }
                       - { property: "description", type: "textarea", label: "Description" }
   

4. Clear Cache

   php bin/console cache:clear
   

5. Verify in Akeneo UI Navigate to Settings > Custom Entities to see your new entity.

Implementation Patterns

Workflow: Extending Akeneo PIM with Custom Data

1. Define Entity Structure Use YAML/XML config to define:

   • Entity label, class, and fields (e.g., text, select, date).
   • Example for a ProductCategory entity:

     akeneo_custom_entity:
         entities:
             product_category:
                 label: "Product Category"
                 class: "App\Entity\ProductCategory"
                 form:
                     fields:
                         - { property: "code", type: "text", label: "Category Code" }
                         - { property: "parent", type: "entity", label: "Parent Category", entity: "product_category" }
     

2. Integrate with Business Logic

   • Event Listeners: Attach to Akeneo events (e.g., product.save) to sync custom entities:

     // src/EventListener/ProductListener.php
     use Adeoweb\CustomEntityBundle\Event\CustomEntityEvent;
     
     class ProductListener {
         public function onProductSave(CustomEntityEvent $event) {
             $product = $event->getProduct();
             $category = $product->getCategory();
             // Save/Update custom entity logic here
         }
     }
     

   • Register in services.yml:

     services:
         App\EventListener\ProductListener:
             tags:
                 - { name: kernel.event_listener, event: product.save, method: onProductSave }
     

3. API/Grid Integration Extend Akeneo’s API/Grid to include custom entity data:

   • Override src/Akeneo/Pim/Enrichment/Controller/Api/ReadController.php to add custom fields to API responses.
   • Extend src/Akeneo/Pim/Enrichment/Controller/Admin/Grid/FieldProvider for grid columns.

4. Validation Rules Add validation via config:

   akeneo_custom_entity:
       entities:
           product_category:
               validation:
                   - { property: "code", constraints: { NotBlank: {}, Length: { max: 50 } } }
   

Gotchas and Tips

Pitfalls

1. Version Mismatch

   • Issue: Bundle fails to load due to incompatible Akeneo PIM version.
   • Fix: Strictly adhere to the requirements table. Use composer why-not to debug.

2. Cache Dependencies

   • Issue: Changes to YAML config aren’t reflected in the UI.
   • Fix: Run:

     php bin/console akeneo:custom-entity:dump && php bin/console cache:clear
     

3. Entity Class Autoloading

   • Issue: Custom entity class not found.
   • Fix: Ensure the class is autoloaded (e.g., App\Entity\CustomEntity exists in src/Entity/).

4. Field Type Limitations

   • Issue: Custom field types (e.g., akeneo_pim_enrichment_form_field_select) may not render.
   • Fix: Use supported types (text, textarea, select, date, entity). Extend via custom form types if needed.

5. Database Schema

   • Issue: Custom entity tables aren’t created.
   • Fix: Run migrations manually:

     php bin/console doctrine:migrations:diff && php bin/console doctrine:migrations:migrate
     

Debugging Tips

• Log Custom Entity Events: Enable debug mode (APP_DEBUG=true) and check var/log/dev.log for Adeoweb\CustomEntityBundle entries.
• Dump Entity Config: Use the akeneo:custom-entity:dump command to verify loaded configurations:

  php bin/console akeneo:custom-entity:dump
  

Extension Points

1. Custom Form Types Extend Adeoweb\CustomEntityBundle\Form\Type\CustomEntityType to add new field types:

   // src/Form/Type/CustomColorType.php
   use Symfony\Component\Form\AbstractType;
   use Symfony\Component\Form\FormBuilderInterface;
   
   class CustomColorType extends AbstractType {
       public function buildForm(FormBuilderInterface $builder, array $options) {
           $builder->add('color', ColorType::class);
       }
   }
   

   Register in services.yml and reference in your YAML config:

   form:
       fields:
           - { property: "color", type: "custom_color", label: "Color" }
   

2. Custom Actions Add buttons/actions to the custom entity grid via JavaScript:

   // web/js/custom-entity-actions.js
   require(['underscore', 'jquery', 'akeneo-grid-selector'], function(_, $, gridSelector) {
       gridSelector.addAction('my_custom_entity', {
           name: 'export',
           label: 'Export',
           action: function() { /* Logic */ }
       });
   });
   

3. API Filters Extend Akeneo’s API filters to support custom entity queries:

   // src/Akeneo/Pim/Enrichment/API/Filter/CustomEntityFilter.php
   use Akeneo\Tool\API\Rest\AbstractFilter;
   
   class CustomEntityFilter extends AbstractFilter {
       public function apply(QueryBuilder $qb, array $parameters) {
           // Add custom WHERE clauses
       }
   }