Apitk Common Bundle Laravel Package

Getting Started

Minimal Steps

1. Check Dependencies: Ensure your project uses other check24/apitk-* bundles (e.g., apitk-swagger-bundle or apitk-api-bundle). This package is designed as a shared dependency for them.
2. Installation: Run:

   composer require check24/apitk-common-bundle
   

   (Note: Manual installation is rare; it’s typically pulled in via other apitk-* bundles.)
3. First Use Case:
   • If using Symfony’s ParamConverter, extend EntityAwareParamConverterTrait or RequestParamAwareParamConverterTrait in your custom converter to leverage shared logic.
   • For Swagger/OpenAPI annotations, extend AbstractDescriber to dynamically modify API documentation.

Where to Look First

• Traits: Browse src/Annotation/, src/ParamConverter/, and src/Describer/ for reusable components.
• Interfaces: Check src/Contract/ for shared interfaces (e.g., EntityAwareInterface).
• Example Usage: Review the apitk-swagger-bundle or apitk-api-bundle source to see how this package is integrated.

Implementation Patterns

ParamConverter Workflows

1. Entity-Based Conversion:

   use Check24\ApitkCommonBundle\ParamConverter\EntityAwareParamConverterTrait;
   
   class MyParamConverter implements ParamConverterInterface {
       use EntityAwareParamConverterTrait;
   
       public function supports(ParamConverterInterface $configuration) {
           return $configuration->getClass() === MyEntity::class;
       }
   
       public function convert($value, ParamConverterInterface $configuration) {
           $entity = $this->getEntity(); // Uses EntityAwareTrait
           $repo = $this->getEntityManager()->getRepository(MyEntity::class);
           return $repo->find($entity->getId());
       }
   }
   

   • Key Methods: getEntity(), getEntityManager(), callRepositoryMethod().

2. Request Param Handling:

   use Check24\ApitkCommonBundle\ParamConverter\RequestParamAwareParamConverterTrait;
   
   class RequestParamConverter implements ParamConverterInterface {
       use RequestParamAwareParamConverterTrait;
   
       public function convert($value, ParamConverterInterface $configuration) {
           $paramValue = $this->getRequestParamValue('user_id', 1); // Default: 1
           return new User($paramValue);
       }
   }
   

   • Key Methods: getRequestParam(), getRequestParamValue().

3. Context-Aware Options:

   use Check24\ApitkCommonBundle\ParamConverter\ContextAwareParamConverterTrait;
   
   class ContextParamConverter implements ParamConverterInterface {
       use ContextAwareParamConverterTrait;
   
       public function convert($value, ParamConverterInterface $configuration) {
           $name = $this->getOption('name', 'default_name'); // Access annotation options
           return new Response(['name' => $name]);
       }
   }
   

Annotation Integration

1. Extending ParamConverter Annotations:

   use Check24\ApitkCommonBundle\Annotation\EntityAwareAnnotationTrait;
   
   #[Route('/users/{id}', name: 'user_show')]
   #[ParamConverter(
       class: 'App\Entity\User',
       options: ['entity' => true, 'methodName' => 'findById']
   )]
   public function show(User $user) { ... }
   

   • Traits to Use:
     • EntityAwareAnnotationTrait: Adds entity, entityManager, methodName.
     • RequestParamAwareAnnotationTrait: Adds requestParam.

2. Dynamic OpenAPI Descriptions:

   use Check24\ApitkCommonBundle\Describer\AbstractDescriber;
   
   class CustomDescriber extends AbstractDescriber {
       protected function describeOperation(Operation $operation) {
           $operation->setSummary('Custom summary via ' . static::class);
           return $operation;
       }
   }
   

   • Register as a service in services.yaml:

     services:
         App\Describer\CustomDescriber:
             tags: ['api_platform.describer']
     

Integration Tips

• Symfony Flex: If using other apitk-* bundles, this package is auto-installed. No manual config needed.
• Doctrine ORM: Ensure EntityAware traits are used with Doctrine entities (e.g., getEntityManager() requires Doctrine).
• Request Context: For RequestParamAware traits, ensure the request object is available in the converter’s context.

Gotchas and Tips

Pitfalls

1. Manual Installation:

   • This package is not standalone. Installing it without other apitk-* bundles will yield no practical benefit. It’s designed for internal use by the apitk ecosystem.
   • Fix: Only install via composer require check24/apitk-swagger-bundle (or similar), which pulls this as a dependency.

2. EntityManager Assumptions:

   • EntityAwareParamConverterTrait assumes Doctrine is configured. If using another ORM (e.g., Eloquent), override getEntityManager() or avoid the trait.
   • Tip: Inject the EntityManagerInterface manually if needed:

     public function __construct(private EntityManagerInterface $em) {}
     

3. Request Scope:

   • RequestParamAwareParamConverterTrait relies on Symfony’s RequestStack. Ensure your converter is request-scoped or the request is passed explicitly.
   • Debugging: Check for RequestStack service availability with:

     bin/console debug:container RequestStack
     

4. Annotation Overrides:

   • Custom annotations using EntityAwareAnnotationTrait must match the trait’s expected options (entity, methodName, etc.). Mismatched options will throw errors.
   • Tip: Validate options in your converter’s supports() method:

     public function supports(ParamConverterInterface $configuration) {
         return $configuration->getClass() === MyEntity::class
             && $configuration->getOptions()['entity'] ?? false;
     }
     

Debugging

1. ParamConverter Issues:

   • Use Symfony’s debug toolbar to inspect converter calls. Enable with:

     _PROFILE=1 _CONTEXT=dev symfony serve
     

   • Check the "ParamConverter" tab for conversion errors.

2. OpenAPI Describer:

   • If AbstractDescriber changes aren’t reflected, clear the cache:

     bin/console cache:clear
     

   • Verify the describer is tagged correctly in services.yaml:

     tags: ['api_platform.describer']  # For API Platform
     # OR
     tags: ['nelmio_api_doc.describer'] # For NelmioApiDoc
     

Extension Points

1. Custom Traits:

   • Extend existing traits (e.g., ContextAwareParamConverterTrait) to add domain-specific logic. Example:

     trait MyCustomParamConverterTrait {
         use ContextAwareParamConverterTrait;
     
         protected function getCustomOption(string $name, $default = null) {
             return $this->getOption('custom.' . $name, $default);
         }
     }
     

2. Describer Hooks:

   • Override methods in AbstractDescriber to modify OpenAPI schemas dynamically:

     protected function describeSchema(Schema $schema) {
         $schema->setExample(['id' => 1, 'name' => 'Example']);
         return $schema;
     }
     

3. Annotation Validation:

   • Create a validator for custom annotations using the entity, requestParam, etc., options:

     use Check24\ApitkCommonBundle\Annotation\EntityAwareInterface;
     
     class MyAnnotationValidator implements ConstraintValidator {
         public function validate($annotation, $object) {
             if (!$annotation instanceof EntityAwareInterface) {
                 return;
             }
             if (empty($annotation->getEntity())) {
                 $this->context->buildViolation('Entity is required.')
                     ->addViolation();
             }
         }
     }
     

Config Quirks

1. Service Autowiring:

   • Traits like EntityAwareParamConverterTrait assume autowiring for EntityManagerInterface. If not autowired, manually inject it:

     public function __construct(private EntityManagerInterface $em) {}
     

2. RequestStack Binding:

   • For RequestParamAware traits, bind the RequestStack service explicitly if using custom containers:

     # config/services.yaml
     services:
         App\ParamConverter\RequestParamConverter:
             arguments:
                 $requestStack: '@request_stack'