Apie Bundle Laravel Package

Getting Started

Minimal Setup

1. Installation

   composer require apie/apie-bundle
   

   This auto-registers ApieBundle and generates config/packages/apie.yaml.

2. Basic Configuration Edit config/packages/apie.yaml to define your API resources and routes:

   apie:
       resources:
           - { path: '/api/users', methods: ['GET'], controller: 'App\\Controller\\UserController' }
   

3. First Use Case Create a simple controller to return JSON data:

   // src/Controller/UserController.php
   namespace App\Controller;
   
   use Symfony\Bundle\FrameworkBundle\Controller\AbstractController;
   use Symfony\Component\HttpFoundation\JsonResponse;
   
   class UserController extends AbstractController
   {
       public function __invoke(): JsonResponse
       {
           return new JsonResponse(['users' => ['id' => 1, 'name' => 'John Doe']]);
       }
   }
   

   Access /api/users to see the response.

Implementation Patterns

Core Workflows

1. Resource-Based Routing Define API endpoints in apie.yaml under resources:

   apie:
       resources:
           - { path: '/api/posts/{id}', methods: ['GET', 'POST'], controller: 'App\\Controller\\PostController' }
   

   Use route parameters ({id}) for dynamic routing.

2. Dependency Injection Inject Apie services into controllers:

   use Apie\Core\Apie;
   
   class PostController
   {
       public function __construct(private Apie $apie) {}
   
       public function __invoke(int $id): JsonResponse
       {
           $this->apie->getLogger()->info('Fetching post ID: ' . $id);
           return new JsonResponse(['post' => []]);
       }
   }
   

3. Middleware Integration Use Symfony middleware (e.g., ApiPlatform\Metadata\Property\ApiResource) alongside Apie’s routing:

   apie:
       resources:
           - { path: '/api/admin', methods: ['GET'], controller: 'App\\Controller\\AdminController', middleware: ['auth'] }
   

4. Doctrine Integration If using apie/doctrine-entity-datalayer, configure the entity manager in apie.yaml:

   apie:
       datalayer:
           doctrine:
               entity_manager: apie_manager
   

Common Patterns

• Validation: Use Symfony’s Validator with Apie controllers:

  use Symfony\Component\Validator\Validator\ValidatorInterface;
  
  class UserController
  {
      public function __construct(private ValidatorInterface $validator) {}
  
      public function __invoke(array $data): JsonResponse
      {
          $errors = $this->validator->validate($data);
          if (count($errors)) {
              return new JsonResponse(['errors' => (string) $errors], 400);
          }
          return new JsonResponse(['success' => true]);
      }
  }
  

• OpenAPI/Swagger: Leverage apie/rest-api for auto-generated docs (if installed in dev dependencies).

Gotchas and Tips

Pitfalls

1. Doctrine Linking

   • If enable_doctrine_bundle_connection: false, you must manually configure migrations:

     php bin/console apie:migrate
     

   • Avoid running migrations in production unless explicitly needed.

2. CSRF Requirements

   • Apie/CMS uses CSRF for forms. Ensure Symfony\SecurityBundle is installed:

     composer require symfony/security-bundle
     

3. Route Overrides

   • Apie routes override Symfony’s default routes. Use priority: -10 in apie.yaml to avoid conflicts:

     apie:
         resources:
             - { path: '/api/health', methods: ['GET'], priority: -10 }
     

Debugging Tips

• Query Logging: Enable Doctrine profiling in config/packages/dev/doctrine.yaml:

  doctrine:
      dbal:
          profiling: true
  

  View queries in Symfony Profiler under "Apie Queries."

• Error Handling: Wrap Apie logic in try-catch:

  try {
      $this->apie->getResourceManager()->load('users');
  } catch (\Apie\Core\Exception\ResourceNotFoundException $e) {
      return new JsonResponse(['error' => 'Resource not found'], 404);
  }
  

Extension Points

1. Custom Datalayers Extend Apie\Core\Datalayer\DatalayerInterface for non-Doctrine storage (e.g., MongoDB):

   class MongoDatalayer implements DatalayerInterface
   {
       public function find($resource, $id) { /* ... */ }
   }
   

   Register in apie.yaml:

   apie:
       datalayer:
           mongo: App\\Datalayer\\MongoDatalayer
   

2. Template Overrides Override Apie/CMS templates by copying files from vendor/apie/cms/src/Resources/views/ to templates/apie/.

3. Event Listeners Subscribe to Apie events (e.g., apie.resource.loaded):

   namespace App\EventListener;
   
   use Apie\Core\Event\ResourceEvent;
   use Symfony\Component\EventDispatcher\EventSubscriberInterface;
   
   class ResourceSubscriber implements EventSubscriberInterface
   {
       public static function getSubscribedEvents(): array
       {
           return [ResourceEvent::LOADED => 'onResourceLoaded'];
       }
   
       public function onResourceLoaded(ResourceEvent $event) { /* ... */ }
   }