Excel Connector Bundle Laravel Package

Getting Started

Minimal Setup

1. Installation:

   composer require akeneo-labs/excel-connector-bundle:1.6.*
   

   Enable in AppKernel.php:

   new Akeneo\Bundle\SpreadsheetParserBundle\AkeneoSpreadsheetParserBundle(),
   new Pim\Bundle\ExcelConnectorBundle\PimExcelConnectorBundle(),
   

   Clear cache:

   php app/console cache:clear --env=prod
   

2. First Use Case:

   • Download the init.xlsx template.
   • Open it in Excel (not LibreOffice/OpenOffice) to populate:
     • Families (e.g., Electronics, Clothing)
     • Categories (e.g., Laptops, T-Shirts)
     • Attributes (e.g., sku, name, price)
   • Upload via Akeneo UI under Import > Import Jobs (select Excel as the job type).

Key Files to Review

• init.xlsx: Mandatory template for catalog structure.
• Getting Started Guide: Step-by-step setup.
• Home.rst: Advanced configurations.

Implementation Patterns

Workflows

1. Catalog Initialization:

   • Use init.xlsx to define families, categories, and attributes in one go.
   • Example:

     Family Tab:
     | Family | Channels |
     |--------|----------|
     | Laptops| ecommerce|
     
     Attribute Tab:
     | Code  | Type    | Localizable | Scopable |
     |-------|---------|-------------|----------|
     | price | pprice  | No          | Yes      |
     

   • Upload via UI or CLI:

     php app/console pim:excel-connector:init --file=init.xlsx
     

2. Product Import/Export:

   • Create a product spreadsheet with headers matching Akeneo attribute codes (e.g., sku, name, price).
   • Example:

     | sku   | name    | price | family |
     |-------|---------|-------|--------|
     | LAP001| MacBook | 999.99| Laptops|
     

   • Upload via Import > Import Jobs (select Excel job type).

3. CLI Automation:

   • Trigger imports programmatically:

     $job = $this->get('pim_connector.excel.job');
     $job->run('path/to/products.xlsx');
     

Integration Tips

• Validation: The bundle validates Excel files against Akeneo’s schema. Errors appear in the UI under Import Jobs.
• Numeric Textarea: Since v1.5.4, numeric values can be imported into text/textarea attributes (e.g., model_number).
• Channel Mapping: Ensure channel names in Excel match those in Akeneo (case-sensitive). Use the Channels tab in init.xlsx to define mappings.

Gotchas and Tips

Pitfalls

1. Excel Compatibility:

   • LibreOffice/OpenOffice: Files saved here may fail validation. Always use Microsoft Excel.
   • Formulas/Hidden Rows: Excel formulas or hidden rows can break imports. Use "Paste Values" to remove formulas.

2. Channel Mismatches:

   • If a family is linked to a non-existent channel, the import fails silently. Verify channel names in both the Family and Channel tabs of init.xlsx.
   • Fix: Delete the misconfigured channel in Akeneo or correct the Excel file.

3. Attribute Code Conflicts:

   • Attribute codes in Excel must match Akeneo’s exactly (e.g., price vs. PRICE). Use the Attributes tab in init.xlsx to define codes.

4. Deprecation Warning:

   • This bundle is deprecated for Akeneo PIM ≥1.6. Use ExcelInitBundle instead for newer versions.

Debugging

• Logs: Check var/log/prod.log for validation errors during imports.
• Dry Runs: Use the UI’s "Preview" option to validate files before full import.
• CLI Debugging:

  php app/console debug:config pim_excel_connector
  

Extension Points

1. Custom Templates:

   • Extend the init.xlsx template by copying it to app/Resources/PimExcelConnectorBundle/templates/ and overriding sheets.

2. Event Listeners:

   • Hook into pim_excel_connector.pre_import or pim_excel_connector.post_import events to preprocess/postprocess data:

     // src/Acme/ExcelConnector/EventListener/ExcelImportListener.php
     public function onPreImport(PreImportEvent $event) {
         $data = $event->getData();
         // Modify $data before import
     }
     

     Register in services.yml:

     services:
         acme.excel_listener:
             tag: { name: kernel.event_listener, event: pim_excel_connector.pre_import, method: onPreImport }
     

3. Attribute Mappings:

   • Override default mappings in config.yml:

     pim_excel_connector:
         attribute_mappings:
             pprice: price  # Map Excel 'price' to Akeneo 'pprice'