Custom Entity Bundle Laravel Package

Technical Evaluation

Architecture Fit

• PIM-Centric Design: The bundle is tightly coupled with Akeneo PIM’s architecture (e.g., AbstractCustomEntity, CustomEntityRepository, and Akeneo’s form extensions). It extends Akeneo’s core functionality for managing reference data (e.g., brands, categories, or custom taxonomies) as first-class entities.
• Modularity: Leverages Symfony’s bundle system and Doctrine ORM, making it compatible with Akeneo’s layered architecture (e.g., PimCustomEntityBundle integrates with Akeneo’s Pim\Bundle\* stack).
• UI/UX Integration: Provides a CRUD interface via Akeneo’s UI framework (e.g., form_extensions, datagrid), aligning with the PIM’s admin panel. The bundle assumes Akeneo’s frontend (Symfony UX + Webpack) is already in place.
• REST/API Support: Includes normalizers for API consistency, but relies on Akeneo’s existing API layer (e.g., CustomEntityNormalizer).

Key Fit: ✅ Strong for Akeneo PIM extensions requiring custom reference data (e.g., supplier hierarchies, custom attributes, or domain-specific taxonomies). ⚠️ Limited for standalone Laravel apps or non-PIM projects (requires Akeneo’s ecosystem).

Integration Feasibility

• Akeneo Dependency: Mandates Akeneo PIM (v2.0–v4.0) as a host system. Cannot be used in vanilla Laravel without significant refactoring (e.g., replacing Akeneo’s Pim\Bundle\* dependencies).
• Composer Integration: Simple composer require + bundle enablement, but requires:
  • Akeneo’s bundles.php configuration.
  • Doctrine schema updates (doctrine:schema:update).
  • Frontend asset rebuild (yarn webpack-dev).
• Configuration Overhead:
  • YAML-heavy: Requires menu.yml, datagrid/*.yml, form_extensions/*.yml, and validation.yml for each custom entity.
  • Doctrine ORM: Custom entities must extend AbstractCustomEntity and define ORM mappings.
  • UI Customization: Heavy reliance on Akeneo’s form/grid system (e.g., pim/menu/item, pim_datasource_default).

Feasibility Score: ✅ High for Akeneo PIM extensions. ❌ Low for non-Akeneo Laravel projects (would need a rewrite of core dependencies).

Technical Risk

Critical Risks:

• Akeneo Version Drift: Risk of breaking changes if Akeneo PIM is upgraded without testing.
• Frontend Lock-in: Custom UI components are tightly coupled to Akeneo’s asset pipeline.

Key Questions for TPM

1. Is Akeneo PIM the Host System?

   • If no, this bundle is not viable without a major rewrite. Consider alternatives like Laravel’s Spatie Media Library or custom Eloquent models.
   • If yes, proceed with version alignment (e.g., Akeneo 4.0.* + bundle 4.0.*).

2. What Are the Custom Entity Use Cases?

   • Example: Supplier hierarchies, product categories, or custom attributes?
   • Complex relationships (e.g., hierarchical data) may require additional logic (e.g., tree repositories).

3. Frontend Customization Needs

   • Will the UI be extended with custom JavaScript (e.g., React)? If so, Akeneo’s asset pipeline may need modification.
   • Are there plans to replace Akeneo’s frontend entirely?

4. CI/CD Pipeline Readiness

   • Can the team handle Akeneo-specific commands (doctrine:schema:update, pim:installer:assets) in CI?
   • Are database migrations automated and tested?

5. Long-Term Maintenance

   • Who will maintain compatibility if Akeneo PIM is upgraded?
   • Are there plans to fork or contribute back to the bundle?

6. Performance Requirements

   • How many custom entities will be created? (Each adds a new table.)
   • Will custom entities be queried in bulk (e.g., for imports/exports)?

Integration Approach

Stack Fit

Recommendation:

• For Akeneo PIM: Proceed with integration. The bundle is a drop-in solution for custom reference data.
• For Laravel: Evaluate alternatives (e.g., Laravel Custom Entities or custom Eloquent models).

Migration Path

Step 1: Prerequisites

1. Akeneo PIM Installation:
   • Ensure Akeneo PIM is installed (matching bundle version, e.g., 4.0.*).
   • Verify PHP/Doctrine/Symfony versions meet Akeneo’s requirements.
2. Composer Setup:

   composer require akeneo-labs/custom-entity-bundle:4.0.*
   

3. Bundle Enablement:
   • Add to config/bundles.php:

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

Step 2: Database Schema

1. Define Custom Entity:
   • Create a class extending AbstractCustomEntity (e.g., Supplier).
   • Define Doctrine ORM mappings (e.g., Supplier.orm.yml).
2. Generate Schema:

   php bin/console doctrine:schema:update --dump-sql  # Review SQL
   php bin/console doctrine:schema:update --force     # Apply changes
   

Step 3: UI Configuration

1. Menu Integration:
   • Add menu.yml to register the entity