- How do I integrate am-driver with a Laravel application?
- Install via Composer (`composer require application-manager-tools/am-driver`), register the Symfony bundle in `config/bundles.php`, and configure it in `config/packages/am_driver.yaml` with your Application Manager base URL, tokens, and route prefix. Laravel’s service container will auto-wire dependencies for orchestration commands and webhook handling.
- What Laravel versions does am-driver support?
- The package is framework-agnostic but requires PHP 7.4+ and Symfony components (HTTP Client, Console) compatible with Laravel 8+ (Symfony 5.4+) or Laravel 9+ (Symfony 6.4+). Test thoroughly with your Laravel version, as some Symfony features may require adjustments.
- How do I handle orchestration commands in Laravel?
- Use the `AmDriverBundle` to expose routes like `/am/orchestration/commands`. Laravel’s controller can inject the `CommandHandler` service to process commands. For CLI orchestration, use the `am-driver serve` command with Docker or PHP directly, parsing responses via the `CallbackDto` class.
- Does am-driver support multi-tenant or SaaS architectures?
- Yes. The `integrationInstanceId` field in callbacks (added in PR #11) enables tenant isolation. Map this ID to your Laravel tenant model (e.g., via middleware or service providers) and use it to scope commands, webhooks, and operational state pushes to specific tenants.
- How do I test webhook consumption in Laravel?
- Use Laravel’s HTTP testing tools to simulate webhook payloads. Mock the `ConsumptionWebhookHandler` service and assert responses. For local testing, run `am-driver serve` with Docker and configure Laravel’s `AM_DRIVER_CONSUMPTION_WEBHOOK_TOKEN` to match the test environment.
- Can I use am-driver without Symfony (e.g., pure Laravel)?
- Yes. The core library is framework-agnostic. Install the package, use the `AmDriver` class for orchestration commands, and manually handle webhooks via Laravel’s route middleware. Skip the Symfony bundle and configure routes in `routes/web.php` or `routes/api.php` instead.
- What’s the difference between `am-driver serve` and Laravel’s HTTP server?
- `am-driver serve` is a standalone CLI tool for testing orchestration commands and webhooks locally. It bypasses Laravel’s routing and middleware, ideal for debugging. For production, use Laravel’s built-in server or a web server like Nginx, ensuring routes like `/am/instance-operational-state` are properly configured.
- How do I validate OpenAPI specs in Laravel?
- Use the `openapi` CLI tool included with am-driver: `vendor/bin/openapi --validate spec/openapi.yaml`. In Laravel, integrate the OpenAPI spec with tools like `zircote/swagger-php` for API documentation. The Swagger UI (accessible via `docker compose up swagger-ui`) helps visualize and test endpoints.
- Are there alternatives to am-driver for Laravel?
- For Application Manager integrations, am-driver is the official PHP driver. Alternatives like custom HTTP clients (e.g., Guzzle) exist but lack orchestration features, OpenAPI support, and webhook handling. For multi-cloud orchestration, compare with tools like Terraform or Pulumi, though they require additional setup.
- How do I handle errors or malformed callbacks in production?
- Implement Laravel’s exception handling middleware to catch and log errors from `CallbackDto` parsing. Use structured logging (e.g., Monolog) to include `integrationInstanceId` for debugging. For critical failures, trigger alerts via Laravel’s `notify()` method or integrate with monitoring tools like Sentry.