Custom Entity Bundle Laravel Package

## Getting Started

### Minimal Setup for a Custom Entity
1. **Install the Bundle**
   ```bash
   composer require akeneo-labs/custom-entity-bundle

Enable in config/bundles.php:

Pim\Bundle\CustomEntityBundle\PimCustomEntityBundle::class => ['all' => true]

2. Define Your Entity Class Extend AbstractCustomEntity and add your fields:

   // src/Acme/SupplierBundle/Entity/Supplier.php
   namespace Acme\Bundle\SupplierBundle\Entity;
   
   use Pim\Bundle\CustomEntityBundle\Entity\AbstractCustomEntity;
   
   class Supplier extends AbstractCustomEntity
   {
       protected $name;
   
       public function getName(): string { return $this->name; }
       public function setName(string $name): void { $this->name = $name; }
   }
   

3. Configure Doctrine Mapping

   # src/Acme/SupplierBundle/Resources/config/doctrine/Supplier.orm.yml
   Acme\Bundle\SupplierBundle\Entity\Supplier:
       type: entity
       table: refdata_supplier
       repositoryClass: Pim\Bundle\CustomEntityBundle\Entity\Repository\CustomEntityRepository
       fields:
           id: ~
           code: ~
           name:
               type: string
               length: 255
   

4. Register the Entity

   # src/Acme/SupplierBundle/Resources/config/custom_entities.yml
   custom_entities:
       supplier:
           entity_class: Acme\Bundle\SupplierBundle\Entity\Supplier
   

5. Create Database Table

   php bin/console doctrine:schema:update --force
   

6. Add Menu Entry

   # src/Acme/SupplierBundle/Resources/config/form_extensions/menu.yml
   extensions:
       acme-menu-supplier:
           module: pim/menu/item
           parent: pim-menu-reference_data-navigation-block
           config:
               title: acme.menu.supplier
               to: pim_customentity_index
               routeParams:
                   customEntityName: supplier
   

7. Configure Datagrid

   # src/Acme/SupplierBundle/Resources/config/datagrid/supplier.yml
   datagrid:
       supplier:
           options:
               entityHint: supplier
           source:
               type: pim_datasource_default
               entity: Acme\Bundle\SupplierBundle\Entity\Supplier
               repository_method: createDatagridQueryBuilder
           columns:
               code: ~
               name: ~
   

8. Clear Cache & Rebuild Assets

   php bin/console cache:clear
   yarn run webpack-dev
   

First Use Case: Creating a Supplier

1. Navigate to Reference Data > Supplier in the Akeneo UI.
2. Click Create to add a new supplier with a name field.
3. Save and verify the supplier appears in the list.

Implementation Patterns

Workflow: Building a Custom Entity

1. Entity Definition

   • Extend AbstractCustomEntity for all custom entities.
   • Use code (unique identifier) and id (auto-incremented primary key) as mandatory fields.
   • Example:

     class Brand extends AbstractCustomEntity {
         protected $logoUrl;
         protected $isActive;
     
         // Getters/setters...
     }
     

2. Doctrine Configuration

   • Map fields to a dedicated table (e.g., refdata_brand).
   • Use repositoryClass: Pim\Bundle\CustomEntityBundle\Entity\Repository\CustomEntityRepository.

3. UI Integration

   • Menu: Extend pim-menu-reference_data-navigation-block to add a menu item.
   • Datagrid: Configure columns, filters, and sorting in datagrid/{entity}.yml.

     columns:
         code: ~
         name:
             type: pim_datagrid_field_string
             label: acme.brand.name
         is_active:
             type: pim_datagrid_field_boolean
             label: acme.brand.is_active
     

   • Forms: Define create.yml and edit.yml for CRUD operations.

     # src/Acme/BrandBundle/Resources/config/form_extensions/brand/create.yml
     acme-brand-create-form:
         module: pim/form/standard
         parent: pim-entity-create-form
         targetZone: content
         position: 100
         config:
             fields:
                 code:
                     type: pim_form_field_text
                     options:
                         label: acme.brand.code
                         required: true
                 name:
                     type: pim_form_field_text
                     options:
                         label: acme.brand.name
                         required: true
     

4. Validation

   • Use Symfony’s validation YAML:

     # src/Acme/BrandBundle/Resources/config/validation.yml
     Acme\Bundle\BrandBundle\Entity\Brand:
         constraints:
             - Symfony\Bridge\Doctrine\Validator\Constraints\UniqueEntity:
                 fields: code
                 message: acme.brand.code.unique
         properties:
             name:
                 - NotBlank: ~
                 - Length:
                     max: 255
     

5. Relationships

   • Link custom entities to products or other entities using form components:

     # Link a product to a supplier (single select)
     acme-product-edit-form-properties-supplier:
         module: custom_entity/field/custom-entity-select
         parent: pim-entity-edit-form-properties-common
         targetZone: content
         position: 200
         config:
             fieldName: supplier
             choiceNameField: name
             choiceValueField: code
             isCustomEntity: true
             entityName: supplier
             required: false
     

6. Normalization

   • Implement a normalizer for API responses:

     use Pim\Bundle\CustomEntityBundle\Normalizer\CustomEntityNormalizerInterface;
     
     class BrandNormalizer implements CustomEntityNormalizerInterface {
         public function normalize($entity, $format = null, array $context = []) {
             return [
                 'code' => $entity->getCode(),
                 'name' => $entity->getName(),
                 'is_active' => $entity->isActive(),
             ];
         }
     }
     

   • Register the normalizer in services.yml:

     services:
         acme.brand.normalizer:
             class: Acme\Bundle\BrandBundle\Normalizer\BrandNormalizer
             tags:
                 - { name: pim_custom_entity.normalizer, entity: brand }
     

7. Batch Operations

   • Create a job for bulk exports/imports:

     php bin/console akeneo:batch:create-job "Supplier Export" "csv_supplier_export" "export" "csv_supplier_export" '{"filePath": "/tmp/suppliers.csv"}'
     

Gotchas and Tips

Pitfalls

1. Cache Invalidation

   • Forgetting to clear Symfony cache (php bin/console cache:clear) after updating YAML configs (e.g., datagrid, form_extensions, menu).
   • Fix: Always clear cache after config changes:

     php bin/console cache:clear --env=prod
     yarn run webpack-dev
     

2. Doctrine Schema Updates

   • Running --force without checking --dump-sql first can break existing data.
   • Fix: Always preview SQL first:

     php bin/console doctrine:schema:update --dump-sql
     

3. Entity Naming Conflicts

   • Using reserved words (e.g., product, family) as custom entity names can cause routing issues.
   • Fix: Use unique, descriptive names (e.g., acme_brand, vendor_supplier).

4. Form Extension Target Zones

   • Incorrect targetZone in form extensions (e.g., content vs. header) can hide fields.
   • Fix: Verify zones in Akeneo’s form templates (e.g., pim-entity-edit-form).

5. Missing Normalizers

   • API endpoints (e.g., /api/rest/v1/supplier) will return null if no normalizer is registered.
   • Fix: Implement CustomEntityNormalizerInterface for each entity.

6. Multi-Select Fields

   • Multi-select custom entity fields require isMultiple: true in the form component config.
   • Fix:

     config:
         isMultiple: true
         fieldName: fabrics
         entityName: fabric
     

7. Translation Keys

   • Missing translations for labels/buttons will show raw keys (e.g., acme.brand.name).
   • Fix: Add translations to translations/messages.{locale}.yml:

     acme:
         brand:
             name: "Brand Name"
             code: "Brand Code"