Advanced Enrich Bundle Laravel Package

## Getting Started

### Minimal Setup
1. **Installation**:
   ```bash
   composer require clickandmortar/advanced-enrich-bundle

Ensure compatibility with your Akeneo version (check the versions table in the README).

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

   ClickAndMortar\AdvancedEnrichBundle\ClickAndMortarAdvancedEnrichBundle::class => ['all' => true],
   

3. First Use Case:

   • Navigate to Akeneo PIM > Settings > Attributes and create a new attribute.
   • Select "Advanced Enrich" as the Attribute Type (if available in your Akeneo version).
   • Test by assigning the attribute to a product and verifying its behavior in Product Grid or Product Edit.

4. Key Files to Explore:

   • config/akeneo/advanced_enrich.yaml (if provided by the bundle).
   • src/Resources/config/services.xml (for bundle services).
   • src/DependencyInjection/ (for configuration overrides).

Implementation Patterns

Common Workflows

1. Extending Attribute Types:

   • Use the bundle to add custom attribute types (e.g., pim_enrich.entity.attribute_type.advanced).
   • Override or extend existing attribute types via YAML configuration:

     # config/akeneo/advanced_enrich.yaml
     advanced_enrich:
         attribute_types:
             my_custom_type:
                 class: 'App\Entity\CustomAttributeType'
                 label: 'Custom Attribute'
     

2. Custom Field Rendering:

   • Extend the bundle’s field templates (e.g., Twig templates in templates/advanced_enrich/).
   • Example: Override the default form field for a custom type:

     {# templates/advanced_enrich/attribute_type/my_custom_type/_form.html.twig #}
     <input type="text" data-type="my_custom_type" />
     

3. Integration with Akeneo Events:

   • Listen to Akeneo’s pim_enrich_attribute_type.pre_save or pim_enrich_attribute.pre_save events to validate or modify attribute data:

     // src/EventListener/CustomAttributeListener.php
     public function onPreSaveAttribute(PreSaveAttributeEvent $event) {
         $attribute = $event->getAttribute();
         if ($attribute->getType() === 'my_custom_type') {
             // Custom logic here
         }
     }
     

     Register the listener in services.xml:

     <service id="app.custom_attribute_listener" class="App\EventListener\CustomAttributeListener">
         <tag name="kernel.event_listener" event="pim_enrich_attribute.pre_save" method="onPreSaveAttribute" />
     </service>
     

4. Mass Actions and Export/Import:

   • Use the bundle’s hooks to customize how attributes behave in Mass Actions, Export, or Import profiles.
   • Example: Extend the pim_enrich.attribute_type.export service to add custom logic:

     # config/services.yaml
     pim_enrich.attribute_type.export:
         class: 'App\Service\CustomExportAttributeType'
         arguments:
             - '@pim_enrich.attribute_type.export.default'
     

5. API and REST Integration:

   • Ensure custom attribute types are serializable for Akeneo’s REST API by implementing NormalizerInterface:

     use Symfony\Component\Serializer\Normalizer\NormalizerInterface;
     
     class CustomAttributeNormalizer implements NormalizerInterface {
         public function normalize($object, $format = null, array $context = []) {
             return ['data' => $object->getValue()];
         }
     }
     

Gotchas and Tips

Pitfalls

1. Akeneo Version Mismatch:

   • The bundle is tightly coupled to specific Akeneo versions. Using an incompatible version may break functionality or cause errors. Always verify the versions table before installation.

2. Missing Configuration:

   • The bundle may not include default configuration files (e.g., advanced_enrich.yaml). If you encounter issues, check if you need to create this file manually in config/akeneo/.

3. Template Overrides:

   • Overriding Twig templates requires following Akeneo’s template inheritance structure. Incorrect paths (e.g., advanced_enrich/attribute_type/my_type/_form.html.twig) will result in 404 errors.

4. Event Listener Conflicts:

   • If multiple bundles or custom code listen to the same Akeneo events (e.g., pim_enrich_attribute.pre_save), execution order matters. Use priority tags in services.xml to control order:

     <tag name="kernel.event_listener" event="pim_enrich_attribute.pre_save" method="onPreSaveAttribute" priority="200" />
     

5. Database Schema Changes:

   • Custom attribute types may require additional database columns. Always run migrations after installing or updating the bundle:

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

6. Caching Issues:

   • Akeneo caches attribute types and templates aggressively. Clear caches after making changes:

     php bin/console cache:clear
     

Debugging Tips

1. Enable Debug Mode:

   • Set APP_DEBUG=1 in .env to get detailed error logs for template or service issues.

2. Log Attribute Events:

   • Use Akeneo’s event system to log attribute changes for debugging:

     public function onPreSaveAttribute(PreSaveAttributeEvent $event) {
         \Pim\Tool\Log\Logger::info('Custom attribute saved', ['attribute' => $event->getAttribute()->getCode()]);
     }
     

3. Check Bundle Assets:

   • Verify that bundle assets (JavaScript/CSS) are loaded by inspecting the browser’s Network tab. Missing assets may indicate incorrect bundle activation or path issues.

4. Validate YAML Configuration:

   • Use Symfony’s config validator to check for syntax errors:

     php bin/console config:validate
     

Extension Points

1. Custom Attribute Types:

   • Extend the bundle by creating new attribute types. Example:

     // src/Entity/CustomAttributeType.php
     namespace App\Entity;
     
     use ClickAndMortar\AdvancedEnrichBundle\Entity\AbstractAdvancedAttributeType;
     
     class CustomAttributeType extends AbstractAdvancedAttributeType {
         // Custom logic here
     }
     

   • Register the type in services.xml:

     <service id="pim_enrich.attribute_type.custom" class="App\Entity\CustomAttributeType" />
     

2. Form Field Customization:

   • Override default form fields by extending the bundle’s Twig templates. Example for a custom input:

     {# templates/advanced_enrich/attribute_type/custom/_form.html.twig #}
     <div class="custom-input">
         <input type="text" {{ attribute_form_attributes }} />
         <span class="custom-label">{{ attribute.label }}</span>
     </div>
     

3. API Serialization:

   • Implement custom normalizers/denormalizers for API compatibility:

     class CustomAttributeDenormalizer implements DenormalizerInterface {
         public function denormalize($data, $class, $format = null, array $context = []) {
             $attribute = new CustomAttribute();
             $attribute->setValue($data['value']);
             return $attribute;
         }
     }
     

4. Mass Edit Actions:

   • Extend mass edit actions to support custom attribute types. Example:

     use Pim\Enrichment\Component\Attribute\AttributeRepositoryInterface;
     
     class CustomMassEditAction {
         public function __construct(private AttributeRepositoryInterface $attributeRepository) {}
     
         public function edit(CustomAttribute $attribute, $value) {
             $attribute->setValue($value);
             $this->attributeRepository->save($attribute);
         }
     }
     

5. Validation Rules:

   • Add custom validation rules for attribute types using Symfony’s validator:

     use Symfony\Component\Validator\Constraints as Assert;
     
     class CustomAttribute {
         /**
          * @Assert\NotBlank(message="Value cannot be blank")
          * @Assert\Length(max=255)
          */
         private $value;
     }
     

---