Eav Api Platform Bundle Laravel Package

Getting Started

Minimal Setup

1. Install Dependencies

   composer require api-platform/api-platform:^2.1 cleverage/eav-api-platform-bundle:^1.0
   

2. Register Bundles Add to config/bundles.php:

   return [
       // ...
       ApiPlatform\Core\Bridge\Symfony\Bundle\ApiPlatformBundle::class => ['all' => true],
       CleverAge\EAVApiPlatformBundle\CleverAgeEAVApiPlatformBundle::class => ['all' => true],
   ];
   

3. Define a Custom EAV Family Class Create a class extending Sidus\EAVModelBundle\Entity\AbstractFamily and annotate it with @Family:

   use Sidus\EAVModelBundle\Annotation\Family;
   
   /**
    * @Family("my_family")
    */
   class MyFamily extends AbstractFamily {}
   

4. Expose as API Resource Configure in config/api_platform/resources.yaml:

   resources:
       MyFamily:
           type: 'entity'
           shortName: 'my_family'
           collectionOperations:
               get:
                   method: 'GET'
                   path: '/families'
   

First Use Case

Expose a simple EAV family with basic CRUD operations:

# config/api_platform/resources.yaml
resources:
    MyFamily:
        type: 'entity'
        shortName: 'my_family'
        itemOperations:
            get: ~
            put: ~
            delete: ~
        collectionOperations:
            get: ~
            post: ~

Implementation Patterns

Custom Class Workflow

1. Define Family Class Extend AbstractFamily and annotate with @Family:

   /**
    * @Family("product")
    */
   class ProductFamily extends AbstractFamily {}
   

2. Create Attribute Classes Extend AbstractAttribute and define in eav_attributes.yaml:

   sidus_eav:
       attributes:
           product:
               - { name: "name", type: "string" }
               - { name: "price", type: "float" }
   

3. Expose via API Platform Use the custom class in resources.yaml:

   resources:
       ProductFamily:
           type: 'entity'
           shortName: 'product'
           filters: ['numeric', 'date']  # Use bundle filters
   

Filter Integration

Replace default Doctrine filters with bundle-specific ones:

# config/api_platform/resources.yaml
resources:
    MyFamily:
        filters:
            - CleverAge\EAVApiPlatformBundle\Filter\BooleanFilter
            - CleverAge\EAVApiPlatformBundle\Filter\DateFilter
            - Cleverage\EAVApiPlatformBundle\Filter\NumericFilter

Hydra Documentation

Ensure @Family annotation is present for proper schema generation:

/**
 * @Family("user_profile")
 * @ApiResource()
 */
class UserProfileFamily extends AbstractFamily {}

Serialization Groups

Use groups in attributes.yaml for granular control:

sidus_eav:
    attributes:
        product:
            - { name: "name", type: "string", groups: ["read"] }
            - { name: "price", type: "float", groups: ["write"] }

Gotchas and Tips

Common Pitfalls

1. Missing @Family Annotation Hydra documentation fails without it. Always annotate custom family classes:

   /**
    * @Family("my_family")  // <-- Required for Hydra
    */
   class MyFamily extends AbstractFamily {}
   

2. Filter Mismatch Bundle filters (BooleanFilter, NumericFilter) do not work with standard Doctrine fields. Use only with EAV attributes.

3. Circular References Avoid exposing nested EAV families without proper DTOs to prevent serialization loops.

4. Version Skew Bundle is tied to api-platform:2.1.*. Upgrading API Platform may break compatibility.

Debugging Tips

1. Check Serialization Use bin/console debug:serializer to verify EAV attributes are included in serialization groups.

2. Filter Validation Test filters individually:

   curl -X GET "/api/products?price[gt]=10"  # NumericFilter
   curl -X GET "/api/products?active=true"   # BooleanFilter
   

3. Hydra Schema Issues Clear cache after adding @Family:

   php bin/console cache:clear
   

Extension Points

1. Custom Filters Extend AbstractFilter to create domain-specific filters:

   class RangeFilter extends AbstractFilter {
       public function apply(QueryBuilder $qb, QueryNameGeneratorInterface $qng, string $resourceClass, string $operationName = null, array $context = []): void {
           // Custom logic
       }
   }
   

2. Attribute Validation Override Sidus\EAVModelBundle\Validator\Constraints\EAV for custom validation rules.

3. Event Subscribers Listen to eav.attribute.pre_save for pre-processing attribute values:

   $eventDispatcher->addSubscriber(new class {
       public function onPreSave(PreSaveEvent $event) {
           $event->getAttribute()->setValue(strtoupper($event->getAttribute()->getValue()));
       }
   });
   

Performance Quirks

1. Eager-Loading EAV Data Use fetch="EAGER" in attributes.yaml for frequently accessed attributes:

   sidus_eav:
       attributes:
           product:
               - { name: "name", type: "string", fetch: "EAGER" }
   

2. Pagination with Filters Combine with ApiPlatform\Metadata\Operation for optimized pagination:

   #[ApiResource(
       operations: [
           new Get(
               paginationItemsPerPage: 20,
               paginationClientItemsPerPage: true
           )
       ]
   )]
   class MyFamily {}