README

Azure Commercial Marketplace SaaS plumbing for Laravel applications. Bedrock replaces the Microsoft SaaS Accelerator with a first-class, testable package that integrates cleanly with Laravel's queues, events, HTTP client, and Cashier-compatible database layout.

Highlights

✅ End-to-end Azure SaaS fulfillment lifecycle (landing, resolve, activate, webhook operations, and ACK loop)
✅ Cashier-compatible schema while remaining framework-agnostic about billing provider
✅ Idempotent operation handling with replay protection
✅ Optional metering pipeline with batch emission support
✅ Hardened webhook verification (HMAC shared secret, IP allow list, mTLS toggle)
✅ Action & pipeline architecture with first-class test coverage using Pest and Orchestra Testbench

Installation

Install the package via Composer:

composer require ziptied/bedrock

Publish the configuration and database migrations:

php artisan vendor:publish --provider="Ziptied\\Bedrock\\AzureMarketplaceServiceProvider"
php artisan migrate

Register your own marketplace provisioner implementation (optional) by binding the Ziptied\Bedrock\Domain\Contracts\Provisioner interface in your AppServiceProvider or a dedicated service provider.

Configuration

All settings live in config/azure_marketplace.php:

billable_model — Fully-qualified class name of the model that represents the billable customer (defaults to App\Models\User).
route prefix/middleware — Customize landing and webhook route groups; webhook middleware defaults to ['api'] plus the signed request middleware.
OAuth credentials — Tenant ID, client ID, client secret, and scope for Azure Marketplace APIs.
Endpoints & versions — Override Azure API base URLs or api-version strings if Microsoft introduces breaking revisions.
Webhook security — Shared secret, IP allow list, and optional mutual TLS enforcement.
Cashier compatibility — Controls whether generated tables align with Laravel Cashier naming and columns.
Plans & metering — Describe plan-specific features and configure metering enablement, dimension defaults, and batch size.
Logging & redirects — Choose a log channel and the redirect path after landing flow activation.

Environment variables such as AZURE_MP_TENANT_ID, AZURE_MP_CLIENT_ID, AZURE_MP_CLIENT_SECRET, AZURE_MP_WEBHOOK_SECRET, and AZURE_MP_ROUTE_PREFIX can be set to tailor behavior per environment.

Usage Overview

Landing Flow: LandingController orchestrates resolve → provision → activate using the LandingResolveActivatePipeline.
Webhook Handling: WebhookController validates signatures, ensures idempotency, dispatches specific action handlers, and optionally triggers the ACK loop.
Actions: Each marketplace behavior (ActivateSubscriptionAction, ApplyChangePlanAction, EmitMeteringBatchAction, etc.) is encapsulated in a dedicated, easily testable action class.
Events: Lifecycle hooks such as SubscriptionResolved, PlanChanged, and QuantityChanged enable application-level integrations.
Metering: When enabled, EmitMeteringBatchAction (and the accompanying console command) submit batched usage events to Microsoft and persist responses for auditing.

Refer to the tests/ directory for example-driven documentation of each action.

Testing

The project ships with a comprehensive Pest suite.

composer test

Tests execute inside an in-memory SQLite database via Orchestra Testbench. Custom migrations for your application can be placed under tests/database/migrations and will be executed automatically.

Contributing

Fork the repository and create a feature branch.
Run composer install and composer test locally.
Adhere to PSR-12 coding standards and the existing action/pipeline architecture.
Include Pest tests for any new or modified actions.
Submit a pull request describing your changes.

License

Bedrock is open-sourced software licensed under the MIT license.

ziptied / bedrock

Maintainers

Details