Custom Entity Bundle Laravel Package

## Getting Started

### Minimal Steps to First Use
1. **Install the Bundle**
   ```bash
   composer require akeneo-labs/custom-entity-bundle:4.0.*

Enable in config/bundles.php:

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

2. Add Routing Append to config/routes/routes.yml:

   pim_customentity:
       prefix: /reference-data
       resource: "@PimCustomEntityBundle/Resources/config/routing.yml"
   

3. Create a Basic Custom Entity Extend AbstractCustomEntity and define Doctrine mapping:

   // src/Acme/SupplierBundle/Entity/Supplier.php
   namespace Acme\Bundle\SupplierBundle\Entity;
   use Pim\Bundle\CustomEntityBundle\Entity\AbstractCustomEntity;
   
   class Supplier extends AbstractCustomEntity {
       protected $name;
       // Getters/Setters...
   }
   

   # 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:
           name: { type: string, length: 255, nullable: false }
   

4. Register the Entity Declare in config/custom_entities.yml:

   custom_entities:
       supplier:
           entity_class: Acme\Bundle\SupplierBundle\Entity\Supplier
   

5. Update Database

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

6. Clear Cache & Rebuild Assets

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

First Use Case: Adding a Supplier

• Navigate to /reference-data/supplier (if menu is configured).
• Create a new supplier via the UI form (if CRUD forms are set up).

Implementation Patterns

1. Entity Design Patterns

• Extend AbstractCustomEntity for all custom entities (handles id and code fields automatically).
• Use CustomEntityRepository for all repositories to leverage built-in CRUD methods.
• Implement NormalizerInterface for API responses (e.g., for REST exports).

2. CRUD Configuration Workflow

Step-by-Step CRUD Setup

1. Menu Integration Add a menu item in 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 }
   

2. Datagrid Configuration Define columns, filters, and sorting in datagrid/supplier.yml:

   datagrid:
       supplier:
           options: { entityHint: supplier }
           source:
               type: pim_datasource_default
               entity: Acme\Bundle\SupplierBundle\Entity\Supplier
               repository_method: createDatagridQueryBuilder
           columns:
               code: { label: acme.supplier.code }
               name: { label: acme.supplier.name }
           filters:
               columns:
                   name: { type: search, data_name: rd.name }
   

3. Form Extensions

   • Index Page: Extend to show the grid (e.g., index.yml).
   • Create/Edit Forms: Define fields in create.yml/edit.yml:

     # create.yml
     acme-supplier-create-form:
         module: pim/form/standard
         parent: pim-entity-create-form
         targetZone: content
         position: 100
         config:
             fields:
                 name: { type: text, options: { label: acme.supplier.name } }
     

4. Validation Use Symfony’s validation YAML (e.g., validation.yml):

   Acme\Bundle\SupplierBundle\Entity\Supplier:
       properties:
           name:
               - NotBlank: ~
               - Length: { max: 255 }
   

3. Integration with Akeneo Features

• Reference Data as Attributes: Create a "reference data simple select" attribute in Akeneo’s attribute configuration, targeting your custom entity (e.g., supplier).

  # config/pim/catalog/attributes.yml
  attributes:
      supplier:
          type: pim_catalog_reference_data_simple_select
          reference_data_name: supplier
  

• Mass Edits: Use the csv_reference_data_quick_export job (created via CLI) to export/import custom entities in bulk:

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

4. API and Normalization

• Implement NormalizerInterface for custom serialization:

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

• Register the normalizer in services.yml:

  services:
      acme.supplier.normalizer:
          class: Acme\Bundle\SupplierBundle\Normalizer\SupplierNormalizer
          tags: [pim_custom_entity.normalizer]
  

5. Custom Fields in Forms

• Dropdowns for Custom Entities: Use the custom_entity/field/custom-entity-select module to link entities:

  # form_extensions/product_association.yml
  acme-product-supplier-select:
      module: custom_entity/field/custom-entity-select
      parent: pim-entity-edit-form-properties-common
      config:
          fieldName: supplier
          entityName: supplier
          choiceNameField: name
          choiceValueField: code
          isCustomEntity: true
  

Gotchas and Tips

Pitfalls

1. Cache Invalidation:

   • Symfony Cache: Clear cache after every config change (cache:clear --env=prod).
   • Frontend Assets: Rebuild assets (yarn run webpack-dev) after routing/translation changes.
   • Browser Cache: Hard-refresh (Ctrl+F5) to see UI changes.

2. Doctrine Schema Updates:

   • Always check SQL with --dump-sql before running --force.
   • Custom tables must follow the naming convention refdata_{entity_name} (e.g., refdata_supplier).

3. Menu Visibility:

   • Menu items won’t appear until:
     • The customEntityName in routeParams matches the YAML key in custom_entities.yml.
     • The title is translated (check translations/messages.en.xlf).

4. Form Extensions:

   • Parent Targets: Use pim-entity-create-form for create forms, pim-entity-edit-form for edit forms.
   • Positioning: Higher position values appear later in the form. Start with 100 for new fields.
   • Missing Edit Form: If redirected to a broken edit form, ensure the edit.yml form extension exists.

5. Validation Errors:

   • Validation messages won’t show if the constraint is misconfigured in validation.yml.
   • Use NotBlank for required fields, but ensure the field exists in the entity.

6. API Normalization:

   • If API responses are empty, verify:
     • The normalizer is tagged with pim_custom_entity.normalizer.
     • The normalizer’s normalize() method returns the expected structure.

7. Mass Edit Jobs:

   • The csv_reference_data_quick_export job must be created manually via CLI.
   • File paths in the job config (e.g., /tmp/suppliers.csv) must be writable by the web server.

Debugging Tips

1. Check Logs:

   php bin/console debug:config pim_custom_entity
   

   Lists all registered custom entities and their configurations.

2. Datagrid Issues:

   • Verify the repository_method in datagrid.yml matches the repository’s method (e.g., createDatagridQueryBuilder).
   • Use pim_datasource_default for standard queries.

3. Form Rendering:

   • Inspect the browser’s Network tab for failed JS/CSS requests (asset rebuild issues).
   • Check Symfony’s debug:router for routing