Cowegis Api Bundle Laravel Package

Getting Started

Minimal Setup

1. Installation:

   composer require cowegis/cowegis-api-bundle
   

   Ensure your project meets the PHP 8.2 requirement.

2. Enable the Bundle: Add to config/bundles.php:

   return [
       // ...
       Cowegis\ApiBundle\CowegisApiBundle::class => ['all' => true],
   ];
   

3. First Use Case: The bundle provides API endpoints for GIS (Geographic Information Systems) operations. Start by inspecting the default routes:

   php bin/console debug:route | grep cowegis
   

   Test a basic endpoint (e.g., /api/geojson) via:

   curl -X GET http://your-app.test/api/geojson
   

4. Configuration: Check config/packages/cowegis_api.yaml (auto-generated). Override defaults if needed:

   cowegis_api:
       api_prefix: '/custom-prefix'  # Example override
   

Implementation Patterns

Core Workflows

1. API Endpoints: The bundle exposes RESTful endpoints for GIS data (e.g., GeoJSON, WFS). Extend or override controllers in src/Controller/:

   namespace App\Controller;
   
   use Cowegis\ApiBundle\Controller\AbstractGeojsonController;
   use Symfony\Component\HttpFoundation\Response;
   
   class CustomGeojsonController extends AbstractGeojsonController
   {
       public function customAction(): Response
       {
           return $this->json(['custom' => 'data']);
       }
   }
   

   Register the route in config/routes.yaml:

   app_custom_geojson:
       path: /api/custom-geojson
       controller: App\Controller\CustomGeojsonController::customAction
   

2. Data Providers: Use the bundle’s DataProvider interfaces to fetch GIS data. Example:

   use Cowegis\ApiBundle\Provider\DataProviderInterface;
   
   class AppDataProvider implements DataProviderInterface
   {
       public function getFeatures(): array
       {
           return [
               // GeoJSON features here
           ];
       }
   }
   

   Bind the provider in services.yaml:

   services:
       Cowegis\ApiBundle\Provider\DataProviderInterface: '@AppDataProvider'
   

3. Request/Response Handling: Leverage Symfony’s Request/Response with GIS-specific extensions:

   use Symfony\Component\HttpFoundation\Request;
   use Cowegis\ApiBundle\Util\GeoJsonUtil;
   
   public function handleRequest(Request $request): Response
   {
       $data = GeoJsonUtil::validateGeoJson($request->getContent());
       return $this->json($data);
   }
   

4. Authentication: Secure endpoints with Symfony’s security component. Example for API tokens:

   # config/packages/security.yaml
   firewalls:
       api:
           pattern: ^/api
           stateless: true
           jwt: ~
   

Gotchas and Tips

Pitfalls

1. Route Conflicts: The bundle auto-registers routes under /api. Avoid naming conflicts by:

   • Overriding routes in config/routes.yaml.
   • Using api_prefix in config to isolate endpoints.

2. GeoJSON Validation: The bundle expects valid GeoJSON. Use GeoJsonUtil::validateGeoJson() to catch malformed input early:

   try {
       $validated = GeoJsonUtil::validateGeoJson($input);
   } catch (\InvalidArgumentException $e) {
       return new Response('Invalid GeoJSON', 400);
   }
   

3. Dependency Injection: The bundle relies on DataProviderInterface. If unbound, endpoints will fail. Always define a provider in services.yaml.

4. CORS Issues: Enable CORS for API endpoints if needed:

   # config/packages/nelmio_cors.yaml
   nelmio_cors:
       defaults:
           allow_origin: ["*"]
           allow_methods: ["GET", "POST", "PUT", "DELETE"]
           allow_headers: ["Content-Type", "Authorization"]
           expose_headers: []
           max_age: 3600
   

Debugging Tips

1. Log GeoJSON Data: Use Symfony’s logger to inspect payloads:

   $this->logger->info('GeoJSON Data', ['data' => $request->getContent()]);
   

2. Check Bundle Events: Listen for cowegis.api.event to intercept requests/responses:

   use Symfony\Component\EventDispatcher\Attribute\AsEventListener;
   
   #[AsEventListener(event: 'cowegis.api.pre_request')]
   public function onPreRequest(RequestEvent $event) {
       $event->setRequest($event->getRequest()->withHeader('X-Custom', 'Header'));
   }
   

3. Test Endpoints: Use PHPUnit with HttpClient to test API responses:

   $response = $client->request('GET', '/api/geojson');
   $this->assertResponseIsSuccessful();
   $this->assertJson($response->getContent());
   

Extension Points

1. Custom Serializers: Extend Cowegis\ApiBundle\Serializer\GeoJsonSerializer to support custom GeoJSON formats.

2. Database Integration: Implement DataProviderInterface to fetch data from Doctrine or other ORMs:

   class DoctrineDataProvider implements DataProviderInterface
   {
       public function __construct(private EntityManagerInterface $em) {}
   
       public function getFeatures(): array
       {
           return $this->em->getRepository(Feature::class)->findAll();
       }
   }
   

3. Webhook Support: Add webhook endpoints for external GIS services by extending the bundle’s WebhookController.