Getting Started

Minimal Steps

Installation:
```
composer require clickandmortar/akeneo-utils-bundle "^<version-wanted>.*"
```
Replace <version-wanted> with your Akeneo version (e.g., 7.0 for Akeneo 7.x).

Bundle Registration: Add the bundle to config/bundles.php:

return [
    // ...
    ClickAndMortar\AkeneoUtilsBundle\ClickAndMortarAkeneoUtilsBundle::class => ['all' => true],
];

First Use Case: Run the list-unused-options command to identify unused attribute options for a specific family/attribute:
```
php bin/console candm:akeneo-utils:list-unused-options --family="electronics" --attribute="color"
```
- Where to look first: Check the commands section for available commands and their flags.

Implementation Patterns

Usage Patterns

Archive Cleanup: Schedule clear-archives to run periodically (e.g., monthly) to free up disk space:
```
php bin/console candm:akeneo-utils:clear-archives --days=90
```
- Use --dry-run to preview what will be deleted:
```
php bin/console candm:akeneo-utils:clear-archives --days=90 --dry-run
```
Unused Option Detection: Integrate list-unused-options into a data cleanup workflow:
```
php bin/console candm:akeneo-utils:list-unused-options --family="clothing" --attribute="size" > unused_options.csv
```
- Tip: Automate this in a CI/CD pipeline to regularly audit unused options.
Model Pruning: Use clear-models-without-children to clean up empty models:
```
php bin/console candm:akeneo-utils:clear-models-without-children --dry-run
```
- Best Practice: Always run with --dry-run first to verify the impact.
Attribute Deletion: Delete an attribute without updating product modification dates:
```
php bin/console candm:akeneo-utils:delete-attribute --code="old_attribute_code"
```
- Caution: This is irreversible; ensure backups are in place.

Workflows

Data Hygiene Pipeline: Combine commands into a script for regular maintenance:

#!/bin/bash
php bin/console candm:akeneo-utils:clear-archives --days=90
php bin/console candm:akeneo-utils:list-unused-options --family="electronics" --attribute="color" > unused_options.log
php bin/console candm:akeneo-utils:clear-models-without-children --dry-run

CI/CD Integration: Add commands to your deployment pipeline to ensure data integrity:

# Example GitHub Actions step
- name: Run Akeneo Utils Commands
  run: |
    php bin/console candm:akeneo-utils:clear-archives --days=30 --dry-run
    php bin/console candm:akeneo-utils:list-unused-options --family="clothing" --attribute="size" > unused_options.csv

Integration Tips

Akeneo Events: While this bundle doesn’t extend Akeneo’s event system, you can trigger these commands via custom events or cron jobs.

Logging: Redirect command output to logs for auditing:

php bin/console candm:akeneo-utils:clear-archives --days=90 >> /var/log/akeneo/cleanup.log 2>&1

Permissions: Ensure the Akeneo user (e.g., www-data) has write permissions to the directories being cleaned.

Gotchas and Tips

Pitfalls

Akeneo Version Mismatch:
- Issue: Using an incompatible Akeneo version (e.g., v7.0.* bundle with Akeneo 6.x) will cause errors.
- Fix: Strictly adhere to the version compatibility table in the README.
Destructive Commands:
- Issue: Commands like clear-models-without-children and delete-attribute permanently delete data.
- Fix: Always use --dry-run first and back up your database before executing.
Disk Space Warnings:
- Issue: clear-archives may fail if the Akeneo user lacks permissions to delete files.
- Fix: Run commands with elevated privileges or adjust file permissions:
```
sudo -u www-data php bin/console candm:akeneo-utils:clear-archives --days=90
```
False Positives in Unused Options:
- Issue: list-unused-options may flag options as unused even if they’re referenced in other systems (e.g., ERP).
- Fix: Manually verify outputs before taking action.
Product Modification Dates:
- Issue: The delete-attribute command skips updating product modification dates, which might affect downstream processes.
- Fix: Document this behavior for stakeholders and test impacts on integrations.

Debugging

Command Errors:
- Check Symfony logs (var/log/dev.log) for detailed error messages.
- Use --verbose flag for more output:
```
php bin/console candm:akeneo-utils:clear-archives --verbose
```

Database Queries:

Enable Doctrine debugging to inspect SQL queries:

// config/packages/dev/doctrine.yaml
doctrine:
    dbal:
        logging: true
        profiling: true

Configuration Quirks

Bundle Enablement:
- Ensure the bundle is enabled in bundles.php for all environments (['all' => true]).
Command Autocompletion:
- Use Symfony’s built-in command autocompletion for easier usage:
```
php bin/console
```

Extension Points

Custom Commands: Extend the bundle by creating a new command class and injecting the AkeneoUtilsService:

namespace App\Command;

use ClickAndMortar\AkeneoUtilsBundle\Service\AkeneoUtilsService;
use Symfony\Component\Console\Command\Command;
use Symfony\Component\Console\Input\InputInterface;
use Symfony\Component\Console\Output\OutputInterface;

class CustomAkeneoCommand extends Command
{
    protected static $defaultName = 'app:custom-akeneo-task';

    private $akeneoUtils;

    public function __construct(AkeneoUtilsService $akeneoUtils)
    {
        $this->akeneoUtils = $akeneoUtils;
        parent::__construct();
    }

    protected function execute(InputInterface $input, OutputInterface $output): int
    {
        // Use $this->akeneoUtils to interact with Akeneo data
        $output->writeln('Running custom Akeneo task...');
        return Command::SUCCESS;
    }
}

Service Overrides: Override the AkeneoUtilsService to customize behavior:

# config/services.yaml
services:
    ClickAndMortar\AkeneoUtilsBundle\Service\AkeneoUtilsService:
        class: App\Service\CustomAkeneoUtilsService
        arguments:
            $akeneoManager: '@pim_catalog.manager.product'

Event Listeners: While the bundle doesn’t provide events, you can listen to Akeneo’s native events to trigger these commands:

// src/EventListener/AkeneoUtilsListener.php
namespace App\EventListener;

use Symfony\Component\EventDispatcher\EventSubscriberInterface;
use Pim\Tool\Bundle\BatchBundle\Event\BatchEvent;

class AkeneoUtilsListener implements EventSubscriberInterface
{
    public static function getSubscribedEvents()
    {
        return [
            'pim_enrich.product_variant.save.post' => 'onProductVariantSave',
        ];
    }

    public function onProductVariantSave(BatchEvent $event)
    {
        // Trigger cleanup after product variant save
        shell_exec('php bin/console candm:akeneo-utils:clear-models-without-children --dry-run');
    }
}

Tips

Backup Before Running Destructive Commands: Always back up your Akeneo database and critical directories before running commands like clear-models-without-children or delete-attribute.
Monitor Disk Usage: Set up monitoring for Akeneo’s var/export and var/import directories to proactively trigger clear-archives.
Document Command Usage: Maintain a runbook for each command, including:
- Purpose
- Flags and their effects

Akeneo Utils Bundle Laravel Package