Excel Connector Bundle Laravel Package

Getting Started

Minimal Steps to Begin

1. Installation:

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

   Enable the bundle in AppKernel.php:

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

   Clear cache and install assets:

   php app/console cache:clear --env=prod
   php app/console pim:installer:assets --env=prod
   

2. First Use Case:

   • Download the minimal init.xlsx template.
   • Open it in Excel (not LibreOffice/OpenOffice) to define your catalog structure (families, categories, attributes, etc.).
   • Upload via Akeneo PIM UI under Import > Import jobs (for initial setup).

Implementation Patterns

Workflows

1. Catalog Initialization:

   • Use init.xlsx to define:
     • Families, categories, and attributes.
     • Channel-specific configurations (e.g., enabled/disabled attributes per channel).
   • Example structure:

     Families Tab: Family name, code, label
     Categories Tab: Category name, code, parent code
     Attributes Tab: Attribute code, type, label, default value
     

2. Product Import/Export:

   • Create an Excel file with columns matching your product attributes (e.g., sku, name, price, image).
   • Upload via Import > Import jobs in Akeneo UI.
   • Map Excel columns to PIM attributes using the UI.

3. Programmatic Usage (Advanced):

   • Use the Akeneo\Bundle\SpreadsheetParserBundle\Reader service to parse Excel files in custom commands/jobs:

     $reader = $this->get('akeneo_spreadsheet_parser.reader');
     $data = $reader->read('path/to/file.xlsx');
     

   • Process data and integrate with PIM services (e.g., pim_catalog.repository.product).

Integration Tips

• Validation: Ensure Excel files are opened in Excel (not LibreOffice) to avoid validation errors.
• Channels: Verify channel names match exactly between init.xlsx and PIM configurations.
• Attribute Types: Support for numeric values in text/textarea attributes (since v1.5.4).
• Dependencies: Requires phpoffice/phpexcel (v1.8) and akeneo-labs/spreadsheet-parser-bundle.

Gotchas and Tips

Pitfalls

1. Excel Compatibility:

   • Files must be opened in Microsoft Excel (not OpenOffice/LibreOffice) to pass validations.
   • Workaround: Save files as .xlsx in Excel before uploading.

2. Channel Mismatches:

   • Typos in channel names (e.g., web vs. Web) will cause import failures.
   • Debug: Check the channels tab in init.xlsx and PIM channel configurations.

3. Attribute Mapping:

   • Excel columns must match PIM attribute codes exactly (case-sensitive).
   • Use the Import job UI to map columns interactively if unsure.

4. Deprecation:

   • This bundle is deprecated for Akeneo PIM ≥1.6. Use akeneo/ExcelInitBundle instead.

Debugging

• Logs: Check var/log/prod.log for parsing errors (e.g., invalid headers, data types).
• Validation Errors: The UI provides feedback on failed imports (e.g., missing required fields).
• PhpExcel Warnings: Update phpoffice/phpexcel to v1.8 if encountering deprecated function warnings.

Extension Points

1. Custom Parsers:

   • Extend Akeneo\Bundle\SpreadsheetParserBundle\Reader to handle custom Excel formats:

     class CustomReader extends AbstractReader {
         public function read($filePath) { ... }
     }
     

   • Register as a service:

     services:
         custom.reader:
             class: AppBundle\Reader\CustomReader
             tags: ['akeneo_spreadsheet_parser.reader']
     

2. Post-Import Logic:

   • Use Akeneo’s event system to trigger actions after import:

     $eventDispatcher->dispatch('pim_catalog.product_import.post', new ProductImportEvent($product));
     

3. Batch Processing:

   • For large files, chunk imports using Akeneo’s job queue:

     $jobInstance = $this->get('pim_job_executor.job_instance');
     $jobInstance->run('import_product', ['file' => $filePath]);