Getting Started

Minimal Setup

Installation Add the bundle to your composer.json:

composer require akeneo/storage-utils-bundle

Enable it in config/bundles.php:

return [
    // ...
    Akeneo\StorageUtilsBundle\AkeneoStorageUtilsBundle::class => ['all' => true],
];

First Use Case: Querying with Criteria The bundle provides a Criteria class for building complex queries across Doctrine ORM/DBAL/MongoDB. Example:

use Akeneo\Tool\Component\StorageUtils\Query\Criteria;

$criteria = new Criteria();
$criteria->addFilter(Criteria::FILTER_EQUAL, 'field_name', 'value');
$criteria->addSort('field_name', Criteria::SORT_ASC);

Where to Look First
- Core Classes: Focus on Akeneo\Tool\Component\StorageUtils\Query\Criteria and Akeneo\Tool\Component\StorageUtils\Repository\RepositoryInterface.
- Doctrine Integration: Check Akeneo\Tool\Component\StorageUtils\Doctrine\Query\QueryBuilderFactory.
- MongoDB Integration: Explore Akeneo\Tool\Component\StorageUtils\MongoDB\Query\QueryBuilderFactory.

Implementation Patterns

Common Workflows

1. Repository Abstraction

Use the RepositoryInterface to standardize repository operations across ORM/DBAL/MongoDB:

use Akeneo\Tool\Component\StorageUtils\Repository\RepositoryInterface;

$repository = $this->get('akeneo_storage_utils.repository.product');
$results = $repository->findBy($criteria);

2. Criteria-Based Queries

Build reusable criteria for filtering, sorting, and pagination:

$criteria = new Criteria();
$criteria
    ->addFilter(Criteria::FILTER_EQUAL, 'status', 'enabled')
    ->addSort('created_at', Criteria::SORT_DESC)
    ->setLimit(10)
    ->setOffset(0);

3. Query Builder Factories

Generate query builders dynamically for different storage backends:

use Akeneo\Tool\Component\StorageUtils\Doctrine\Query\QueryBuilderFactory;

$qbFactory = $this->get(QueryBuilderFactory::class);
$qb = $qbFactory->create($entityManager, $entityClass, $criteria);

4. Event-Driven Extensions

Extend functionality via Symfony events (e.g., akeneo_storage_utils.query_builder.create):

# config/services.yaml
services:
    App\EventSubscriber\CustomQuerySubscriber:
        tags:
            - { name: kernel.event_subscriber }

5. MongoDB-Specific Patterns

For MongoDB, leverage the MongoDBQueryBuilderFactory:

use Akeneo\Tool\Component\StorageUtils\MongoDB\Query\MongoDBQueryBuilderFactory;

$mongoQbFactory = $this->get(MongoDBQueryBuilderFactory::class);
$query = $mongoQbFactory->create($dm, $documentClass, $criteria);

Integration Tips

Doctrine ORM

Entity Metadata: Ensure your entities use standard Doctrine annotations or YAML/XML for metadata.
DQL: The bundle translates Criteria to DQL under the hood. Complex joins may require manual DQL adjustments.

MongoDB ODM

Document Mapping: Use @Document and @Field annotations for proper mapping.
Aggregation Pipelines: For advanced queries, combine Criteria with MongoDB’s native aggregation framework.

DBAL

Raw SQL: For DBAL, the bundle generates SQL queries. Test edge cases (e.g., LIMIT/OFFSET with complex joins).

Symfony Integration

Dependency Injection: Prefer constructor injection for repositories and factories.
Configuration: Override default settings via config/packages/akeneo_storage_utils.yaml:
```
akeneo_storage_utils:
    query_builder:
        default_limit: 50
```

Gotchas and Tips

Pitfalls

Criteria Translation Limits
- Not all Criteria filters/sorts translate perfectly to MongoDB or raw SQL. Test edge cases (e.g., nested filters, custom functions).
- Workaround: Fall back to native query builders for unsupported operations.
MongoDB vs. ORM Differences
- MongoDB’s Criteria implementation may behave differently (e.g., $lookup vs. joins).
- Tip: Use MongoDBQueryBuilderFactory directly for MongoDB-specific optimizations.
Performance with Large Datasets
- Avoid overly complex Criteria with deep nesting or unbounded sorts. Use setLimit() and setOffset() for pagination.
- Tip: Add indexes in MongoDB or database-level optimizations for filtered fields.
Event Subscriber Conflicts
- Multiple subscribers for akeneo_storage_utils.query_builder.create may override each other.
- Tip: Use priority tags (priority: 10) to control execution order.
Doctrine Event Listeners
- The bundle may conflict with existing Doctrine listeners (e.g., lifecycle callbacks).
- Tip: Disable conflicting listeners or use stopPropagation() in event subscribers.

Debugging

Query Logging Enable Doctrine/MongoDB query logging to inspect generated queries:

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

Criteria Validation Use Criteria::validate() to check for unsupported operations before execution:

if (!$criteria->validate()) {
    throw new \RuntimeException('Invalid criteria for this storage backend.');
}

MongoDB Debugging For MongoDB, enable debug mode in the MongoDBQueryBuilderFactory:

$query = $mongoQbFactory->create($dm, $documentClass, $criteria, true); // Debug mode

Extension Points

Custom Criteria Filters Extend Criteria by implementing Akeneo\Tool\Component\StorageUtils\Query\Filter\FilterInterface:

class CustomFilter implements FilterInterface {
    public function apply(QueryBuilder $qb, $field, $value) {
        // Custom logic
    }
}

services:
    App\Query\CustomFilter:
        tags:
            - { name: akeneo_storage_utils.criteria.filter, alias: 'custom' }

Query Builder Decorators Decorate the default QueryBuilderFactory to add pre/post-processing:

use Akeneo\Tool\Component\StorageUtils\Doctrine\Query\QueryBuilderFactoryInterface;

class CustomQueryBuilderFactory implements QueryBuilderFactoryInterface {
    private $decorated;

    public function __construct(QueryBuilderFactoryInterface $decorated) {
        $this->decorated = $decorated;
    }

    public function create(EntityManagerInterface $em, string $entityClass, Criteria $criteria) {
        $qb = $this->decorated->create($em, $entityClass, $criteria);
        // Add custom logic (e.g., global filters)
        return $qb;
    }
}

Repository Decorators Decorate RepositoryInterface to add cross-cutting concerns (e.g., logging, caching):

use Akeneo\Tool\Component\StorageUtils\Repository\RepositoryInterface;

class CachedRepository implements RepositoryInterface {
    private $decorated;

    public function __construct(RepositoryInterface $decorated) {
        $this->decorated = $decorated;
    }

    public function findBy(Criteria $criteria) {
        $cacheKey = md5($criteria->serialize());
        if ($cached = $this->cache->get($cacheKey)) {
            return $cached;
        }
        $result = $this->decorated->findBy($criteria);
        $this->cache->set($cacheKey, $result, 3600);
        return $result;
    }
}

Configuration Quirks

Default Limit The bundle sets a default limit (e.g., 50). Override it globally:
```
akeneo_storage_utils:
    query_builder:
        default_limit: 100
```
MongoDB Document Classes Ensure your MongoDB documents are properly mapped with @Document and @Field annotations. The bundle uses these for query generation.
Doctrine Event Dispatcher The bundle dispatches events for query building. Disable if conflicts arise:
```
akeneo_storage_utils:
    query_builder:
        dispatch_events: false
```

Storage Utils Bundle Laravel Package