Oro Extended Magento Bundle Laravel Package

Getting Started

Minimal Setup

1. Installation:

   composer require allies/oro-extended-magento-bundle
   

   Ensure your project uses oro/crm: ~2.0 (not 2.3+ due to incompatibility).

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

   return [
       // ...
       Allies\ExtendedMagentoBundle\AlliesExtendedMagentoBundle::class => ['all' => true],
   ];
   

3. Prerequisites:

   • Install the Allies_OroApi Magento extension on your Magento instance.
   • Configure oro/crm-magento-bundle (e.g., API credentials, sync settings).

4. First Use Case: Sync Magento customer data to OroCRM with extended fields (e.g., gender, custom attributes) via:

   php bin/console oro:cron:run --emulate
   

   Verify extended fields in OroCRM’s magento_customer entity.

Implementation Patterns

Workflows

1. Field Extension:

   • Override Magento entity mappings (e.g., Customer, Order) in config/oro/magento.yml:

     oro_magento:
         entities:
             customer:
                 fields:
                     gender: ~ # Maps Magento's gender to OroCRM's extended field
     

   • Use AlliesExtendedMagentoBundle's event listeners (e.g., CustomerGenderConverter) to transform data.

2. Sync Automation:

   • Schedule syncs via OroCRM’s cron jobs:

     php bin/console oro:cron:run --emulate --env=prod
     

   • Log sync status in var/log/oro/magento_sync.log.

3. Custom Attributes:

   • Extend Magento’s eav_attribute data via OroCRM’s magento_attribute entity.
   • Example: Add a custom field loyalty_points to sync from Magento:

     // src/EventListener/MagentoAttributeSubscriber.php
     use Allies\ExtendedMagentoBundle\Event\MagentoAttributeEvent;
     
     class MagentoAttributeSubscriber {
         public function onLoadAttributes(MagentoAttributeEvent $event) {
             $event->addAttribute('loyalty_points', 'text');
         }
     }
     

4. Data Validation:

   • Validate extended fields before sync using OroCRM’s validators:

     # config/validation.yml
     Oro\MagentoBundle\Entity\Customer:
         properties:
             gender:
                 - NotBlank: ~
                 - Choice: { choices: ["male", "female", "other"] }
     

Integration Tips

• Magento API Limits: Batch syncs to avoid hitting Magento’s API rate limits (configure in oro_magento.yml).
• Field Mappings: Use oro:magento:entity:dump to inspect current mappings:

  php bin/console oro:magento:entity:dump
  

• Testing: Mock Magento API responses in PHPUnit:

  $this->get('oro_magento.api.client')->method('getCustomer')->willReturn($mockCustomer);
  

Gotchas and Tips

Pitfalls

1. Version Lock:

   • Error: ClassNotFoundException for Allies\ExtendedMagentoBundle\....
   • Fix: Ensure oro/crm: ~2.0 (not 2.3+) and allies/oro-extended-magento-bundle: ~2.0 in composer.json.

2. Gender Conversion Bug:

   • Issue: Gender fields may sync as null or incorrect values (fixed in 2.0.1).
   • Workaround: Manually patch CustomerGenderConverter if using an older version:

     // src/Allies/ExtendedMagentoBundle/Converter/CustomerGenderConverter.php
     public function convert($gender) {
         return in_array($gender, [1, 2, 3]) ? ['male', 'female', 'other'][$gender - 1] : null;
     }
     

3. Missing Extended Fields:

   • Cause: Fields not defined in oro_magento.yml or Magento API.
   • Debug: Check var/log/oro/magento_sync.log for skipped fields.

4. Cron Conflicts:

   • Error: Sync jobs fail due to locked tables.
   • Fix: Increase OroCRM’s cron job timeout in .env:

     ORO_CRON_TIMEOUT=3600
     

Debugging

• Enable Verbose Logging:

  php bin/console oro:magento:sync --env=prod --verbose
  

• SQL Queries: Use Doctrine’s query logger:

  $this->get('doctrine')->getConnection()->getConfiguration()->setSQLLogger(new \Doctrine\DBAL\Logging\EchoSQLLogger());
  

Extension Points

1. Custom Sync Logic: Subscribe to oro_magento.sync.post event:

   // src/EventListener/CustomSyncListener.php
   use Oro\Bundle\MagentoBundle\Event\SyncEvent;
   
   class CustomSyncListener {
       public function onPostSync(SyncEvent $event) {
           $entity = $event->getEntity();
           // Add custom logic (e.g., update related records)
       }
   }
   

2. New Entity Support: Extend for non-customer entities (e.g., Product, Quote) by:

   • Creating a custom bundle.
   • Implementing MagentoEntityInterface for new entities.

3. API Client Overrides: Replace the default Magento API client:

   # config/services.yaml
   services:
       oro_magento.api.client:
           class: App\Service\CustomMagentoClient
           arguments:
               - '@oro_magento.api.client.default'
   

Configuration Quirks

• Field Naming: OroCRM expects snake_case (e.g., first_name), but Magento uses camelCase (firstName). Use oro_magento.yml to normalize:

  oro_magento:
      entities:
          customer:
              fields:
                  first_name: firstName
  

• Timezone Sync: Magento timestamps may differ from OroCRM’s. Configure in oro_magento.yml:

  oro_magento:
      timezone: America/New_York