Extension Starter Laravel Package

Getting Started

Minimal Setup

1. Initialize Akeneo PIM Standard Edition

   composer create-project --prefer-dist akeneo/pim-community-standard /tmp/pim-standard-edition "1.6.*@stable"
   

2. Generate Extension Skeleton Navigate to src/ of your Akeneo installation and run:

   composer create-project akeneo-labs/extension-starter YourCompanyName
   

3. Customize the Starter Replace placeholders in composer.json (e.g., Acme → YourCompanyName, DemoConnectorBundle → YourExtensionBundle):

   sed -i "s#Acme#YourCompanyName#g" composer.json
   sed -i "s#DemoConnectorBundle#YourExtensionBundle#g" composer.json
   

4. Register the Bundle Add the bundle to app/AppKernel.php and update composer.json autoload:

   "autoload": {
       "psr-4": {
           "YourCompanyName\\Bundle\\YourExtensionBundle\\": "src/YourCompanyName"
       }
   }
   

   Run:

   composer dump-autoload
   

5. Test Clear cache and verify the extension loads:

   php app/console cache:clear
   

First Use Case: Adding a Custom Attribute Type

1. Create a New Attribute Type Class Extend Akeneo\Tool\Component\Attribute\Common\Type\AbstractType in YourExtensionBundle/AttributeType/YourType.php.

2. Register the Type Override buildAttributeTypes() in YourExtensionBundle/DependencyInjection/YourExtensionExtension.php:

   public function load(array $configs, ContainerBuilder $container)
   {
       $loader = new Loader\YamlFileLoader($container, new FileLocator(__DIR__.'/../Resources/config'));
       $loader->load('services.yml');
   }
   

3. Define Services In Resources/config/services.yml:

   services:
       your_extension.attribute_type.your_type:
           class: YourCompanyName\Bundle\YourExtensionBundle\AttributeType\YourType
           tags:
               - { name: akeneo_attribute.type, type: your_type }
   

4. Verify in PIM Check if the new attribute type appears in the UI under Settings > Attributes.

Implementation Patterns

Workflow: Developing a Connector

1. Symlink or Vendor Integration

   • Symlink: Link your extension to src/ for live development:

     ln -s /path/to/extension src/YourCompanyName
     

   • Vendor: Install via Composer (recommended for production):

     composer require yourcompany/your-extension
     

2. Processor-Based Logic Use Akeneo’s ProcessorInterface for imports/exports. Example:

   namespace YourCompanyName\Bundle\YourExtensionBundle\Processor;
   
   use Akeneo\Tool\Component\Connector\Processor\Item\ItemProcessorInterface;
   
   class YourProcessor implements ItemProcessorInterface
   {
       public function process($item)
       {
           // Transform $item (e.g., map PIM fields to external API)
           return $transformedItem;
       }
   }
   

3. Event Subscribers Hook into Akeneo’s events (e.g., pim_enrich.product.save):

   namespace YourCompanyName\Bundle\YourExtensionBundle\EventSubscriber;
   
   use Symfony\Component\EventDispatcher\EventSubscriberInterface;
   
   class YourSubscriber implements EventSubscriberInterface
   {
       public static function getSubscribedEvents()
       {
           return [
               'pim_enrich.product.save' => 'onProductSave',
           ];
       }
   
       public function onProductSave($event)
       {
           // Custom logic on product save
       }
   }
   

4. Configuration Management Use Extension class to inject configuration:

   namespace YourCompanyName\Bundle\YourExtensionBundle\DependencyInjection;
   
   class YourExtensionExtension extends Extension
   {
       public function load(array $configs, ContainerBuilder $container)
       {
           $configuration = new Configuration();
           $config = $this->processConfiguration($configuration, $configs);
           $container->setParameter('your_extension.config', $config);
       }
   }
   

Integration Tips

1. Database Migrations Use Doctrine Migrations for schema changes:

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

2. Asset Management Place static assets (JS/CSS) in Resources/public/ and enable Twig:

   {% block stylesheets %}
       {{ parent() }}
       {{ asset('bundles/yourextension/css/your.css') }}
   {% endblock %}
   

3. Testing Extend Akeneo’s WebTestCase for functional tests:

   use Akeneo\Test\Integration\WebTestCase;
   
   class YourExtensionTest extends WebTestCase
   {
       public function testYourFeature()
       {
           $client = static::createClient();
           $crawler = $client->request('GET', '/your-route');
           // Assertions...
       }
   }
   

4. Localization Use translation domains in templates:

   {{ 'your_extension.your_message'|trans }}
   

   Define translations in Resources/translations/messages.en.yml.

Gotchas and Tips

Pitfalls

1. Namespace Collisions

   • Ensure your bundle namespace (e.g., YourCompanyName\Bundle\YourExtensionBundle) is unique.
   • Avoid using reserved Akeneo namespaces (e.g., Akeneo\).

2. Autoloading Issues

   • Symlink Pitfall: If using symlinks, ensure the target path is correct and permissions are set.
   • Composer Dump: Always run composer dump-autoload after manual composer.json changes.

3. Event Dispatcher Conflicts

   • Avoid overriding Akeneo’s core events (e.g., pim_enrich.product.index). Use custom events instead.
   • Example custom event:

     $dispatcher->dispatch('your_extension.product.post_save', new YourEvent($product));
     

4. Database Compatibility

   • MongoDB vs. MySQL: Test your extension on both databases. MongoDB may require BSON serialization for complex data.
   • Large Datasets: Avoid findAll() in processors. Use pagination or cursors:

     $repository->createQueryBuilder('p')
         ->setMaxResults(100)
         ->getQuery()
         ->getResult();
     

5. Cache Invalidation

   • Clear Akeneo’s cache after schema changes:

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

Debugging Tips

1. Log Output Use Monolog in your bundle:

   $this->container->get('logger')->info('Your debug message');
   

   Check logs at var/log/dev.log.

2. Symfony Profiler Enable the profiler in app/config/config_dev.yml:

   framework:
       profiler: { only_exceptions: false }
   

   Access at /_profiler.

3. XDebug Configure php.ini for remote debugging:

   xdebug.remote_enable=1
   xdebug.remote_port=9000
   

4. Akeneo-Specific Tools

   • Debug Toolbar: Add to app/config/config_dev.yml:

     akeneo_debug_toolbar:
         enabled: true
     

   • CLI Commands: Use pim:import and pim:export for testing connectors.

Extension Points

1. Custom Attribute Types Extend AbstractType and register via akeneo_attribute.type tag. Example:

   services:
       your_extension.attribute_type.color:
           class: YourCompanyName\Bundle\YourExtensionBundle\AttributeType\ColorType
           tags:
               - { name: akeneo_attribute.type, type: pim_catalog_color }
   

2. Custom Forms Override Akeneo’s form types in Resources/config/akeneo_form_types.yml:

   akeneo_form.type.product:
       parent: Akeneo\Platform\Bundle\Form\Type\ProductType
       class: YourCompanyName\Bundle\YourExtensionBundle\Form\Type\ProductType
   

3. Custom Actions Add mass actions via akeneo_action tag:

   services:
       your_extension.action.your_action:
           class: YourCompanyName\Bundle\YourExtensionBundle\Action\YourAction
           tags:
               - { name: akeneo_action.action, type: your_action, label: 'Your Action' }
   

4. Custom Widgets Create