Extended Measure Bundle Laravel Package

Getting Started

Minimal Setup

1. Installation:

   composer require akeneo/extended-measure-bundle
   

   Ensure compatibility with Akeneo PIM CE/EE (v1.6.x, v1.7.x, or v2.x).

2. Configuration: Copy the default measure configurations from vendor/akeneo/extended-measure-bundle/Resources/config/measures/ to your project’s app/config/pim/measure/ directory. Override or extend the YAML files (e.g., acceleration.yml, length.yml) as needed.

3. First Use Case: Convert a value from one unit to another (e.g., meters to feet) using the MeasureConverter service:

   $converter = $this->get('akeneo_measures.converter');
   $value = $converter->convert(10, 'METER', 'FOOT');
   

Implementation Patterns

Core Workflows

1. Unit Conversion:

   • Use the MeasureConverter service to handle conversions between units within the same family (e.g., KILOGRAM ↔ POUND).
   • Example:

     $converter->convert(5, 'KILOGRAM', 'POUND'); // Returns ~11.023
     

2. Family Management:

   • Extend existing measure families (e.g., add CENTIMETER to the LENGTH family) by modifying the YAML config.
   • Define new families (e.g., TEMPERATURE) with their own units and conversion rules.

3. Symbol Handling:

   • Leverage alternative_symbols to support locale-specific or legacy symbols (e.g., µ vs. micro).
   • Access symbols via the MeasureRepository:

     $symbols = $this->get('akeneo_measures.repository')->getSymbols('METER');
     

4. UNECE Codes:

   • Use unece_code for standardized identifiers (e.g., MTQ for meter) in integrations with external systems.

Integration Tips

• Akeneo PIM Integration: Attach measures to product attributes via the pim_catalog bundle. Use the measureable attribute type for numeric fields requiring units. Example attribute definition:

  # config/pim/catalog/attributes.yml
  my_weight_attribute:
      type: measureable
      measure_family: WEIGHT
      default_unit: KILOGRAM
  

• Custom Services: Extend the bundle’s services (e.g., MeasureConverter) to add domain-specific logic:

  // src/Akeneo/Bundle/MyBundle/Service/CustomMeasureService.php
  class CustomMeasureService {
      public function __construct(private MeasureConverter $converter) {}
  
      public function convertWithTolerance(float $value, string $from, string $to, float $tolerance = 0.01) {
          $converted = $this->converter->convert($value, $from, $to);
          return abs($converted - $value) <= $tolerance ? $converted : null;
      }
  }
  

• Event Listeners: Listen to akeneo_measures.measure_family.loaded to dynamically modify measure families at runtime:

  // src/Akeneo/Bundle/MyBundle/EventListener/MeasureListener.php
  class MeasureListener {
      public function onMeasureFamilyLoaded(MeasureFamilyEvent $event) {
          $family = $event->getFamily();
          if ($family->getCode() === 'LENGTH') {
              $family->addUnit('NAUTICAL_MILE', ['convert' => ['mul' => 1852]]);
          }
      }
  }
  

Gotchas and Tips

Pitfalls

1. Configuration Overrides:

   • Issue: Custom YAML files in app/config/pim/measure/ may be ignored if not properly loaded by Akeneo’s config system.
   • Fix: Ensure the files are included in config/packages/_pim.yml:

     imports:
         - { resource: pim/measure/acceleration.yml }
         - { resource: pim/measure/length.yml }
     

2. Unit Uniqueness:

   • Issue: Duplicate unit codes across families will cause errors during pim:measures:check.
   • Fix: Run the check command regularly:

     php bin/console pim:measures:check
     

3. Deprecated Methods:

   • Issue: The bundle is archived; some methods may not be documented or may conflict with newer Akeneo versions.
   • Fix: Use MeasureConverter and MeasureRepository directly, and refer to the AkeneoMeasureBundle for updates.

4. Performance:

   • Issue: Loading all measure configurations at once can be slow for large catalogs.
   • Fix: Lazy-load families using Akeneo’s measure_family.loader service or cache configurations:

     $this->get('akeneo_measures.cache.warmer')->warmup();
     

Debugging Tips

• Find a Unit: Use the pim:measures:find command to locate units by name, symbol, or UNECE code:

  php bin/console pim:measures:find "foot"  # Searches by name/symbol
  php bin/console pim:measures:find --unece-code "FT"  # Searches by UNECE code
  

• Conversion Debugging: Log conversion steps to verify calculations:

  $converter->convert(1, 'METER', 'FOOT', true); // Enable debug mode (if supported)
  

• Configuration Validation: Validate YAML syntax using a linter (e.g., YAML Lint) before applying changes.

Extension Points

1. Custom Conversion Rules: Extend the MeasureConverter to support non-linear conversions (e.g., Fahrenheit ↔ Celsius):

   // src/Akeneo/Bundle/MyBundle/Converter/CustomConverter.php
   class CustomConverter implements MeasureConverterInterface {
       public function convert($value, $fromUnit, $toUnit, $debug = false) {
           if ($fromUnit === 'FAHRENHEIT' && $toUnit === 'CELSIUS') {
               return ($value - 32) * 5/9;
           }
           // Delegate to default converter for other cases
           return $this->delegate->convert($value, $fromUnit, $toUnit, $debug);
       }
   }
   

2. Dynamic Families: Create measure families dynamically via the MeasureFamilyManager:

   $family = new MeasureFamily('CUSTOM_FAMILY', 'KILOGRAM');
   $family->addUnit('GRAM', ['convert' => ['mul' => 0.001]]);
   $this->get('akeneo_measures.manager')->saveFamily($family);
   

3. Attribute Events: Trigger actions when measure attributes are updated (e.g., recalculate product weights):

   // src/Akeneo/Bundle/MyBundle/EventListener/ProductListener.php
   class ProductListener {
       public function onProductUpdate(ProductUpdateEvent $event) {
           $product = $event->getProduct();
           if ($product->hasAttribute('weight')) {
               $weight = $product->getValue('weight');
               $converted = $this->get('akeneo_measures.converter')->convert(
                   $weight->getData(),
                   $weight->getUnit(),
                   'POUND'
               );
               // Store converted value for reporting
           }
       }
   }
   

4. API Extensions: Expose measure conversions via Akeneo’s API by extending the api.read or api.write events:

   // src/Akeneo/Bundle/MyBundle/EventListener/ApiListener.php
   class ApiListener {
       public function onApiRead(ApiReadEvent $event) {
           $data = $event->getResult();
           if (isset($data['attributes']['weight'])) {
               $data['attributes']['weight_pounds'] = $this->get('akeneo_measures.converter')
                   ->convert($data['attributes']['weight'], 'KILOGRAM', 'POUND');
           }
           $event->setResult($data);
       }
   }