Df Azure Laravel Package

Getting Started

This is not a normal Laravel package — it is a DreamFactory 2.x platform plugin. You don't composer require it into an app and call facades; you install a DreamFactory instance (itself a Laravel 5.x application), add this package, and get Azure-backed REST APIs as a result. Day-to-day, you'll mostly be consuming the APIs it generates from your Laravel app, not calling its classes.

Minimal steps:

1. Install DreamFactory 2.x (or use the official Docker image).
2. From the DreamFactory root, composer require dreamfactory/df-azure.
3. Register the service provider in config/app.php (look in src/Providers/ — typically AzureServiceProvider), or run php artisan df:setup if your DF version supports package auto-registration.
4. Run php artisan migrate and clear caches (php artisan config:clear, php artisan cache:clear).
5. Log into the DreamFactory admin UI → Services → Create and pick an Azure service type (Blob, Table, SQL, Cosmos/DocumentDB, etc.).

Where to look first:

• src/Services/ — one class per Azure service; each exposes a getConfigSchema() that defines exactly which fields (account name, key, container, host) you must supply.
• src/Providers/ — registration and service-type binding.
• config/ — any package-level defaults.
• The DreamFactory docs for the generic "service definition" and "API key/role" model — those apply unchanged here.

First use case: register an Azure Blob service, create an API key + role that allows GET /files on that service, and call GET /api/v2/{service}/ from your Laravel app to list containers/blobs. That's a working end-to-end path in under an hour if your credentials are correct.

Implementation Patterns

Define services as infrastructure, not code. Azure endpoints are configured through the DreamFactory admin UI or the system API (POST /api/v2/system/service), not through Laravel config files. Treat the JSON service definition as your source of truth and version it alongside your app, applying it in seed/migration scripts per environment (dev/staging/prod) with different account keys.

Consume from Laravel via a thin HTTP client. Wrap the generated APIs in a small service class:

class AzureBlobClient
{
    public function __construct(private Client $http, private string $base) {}

    public function put(string $path, string $contents)
    {
        return $this->http->post("{$this->base}/{$path}", [
            'headers' => [
                'X-DreamFactory-Api-Key' => config('services.df.key'),
                'Content-Type'          => 'application/octet-stream',
            ],
            'body' => $contents,
        ]);
    }
}

Bind it in a service provider and inject it where you'd otherwise inject an Azure SDK client. This keeps your app portable if you later swap DreamFactory for the native SDK.

Use DreamFactory scripting for logic that belongs at the edge. Server-side scripts (V8/PHP) attached to the service can transform payloads, enforce naming conventions, or fan out to multiple containers before the response reaches Laravel. Good for multi-tenant path prefixing ({tenant}/...) without changing app code.

Blob storage is the most common daily pattern — file uploads, generated reports, user avatars. Table storage is the second — a cheap schemaless store for audit logs or feature flags; access it as GET /api/v2/{service}/{table} and map rows to arrays in your repository layer.

Use roles and API keys defensively. Create one API key per consuming app, scoped by role to only the containers/tables it needs. Rotate keys without touching application code. This is the main security win over embedding Azure keys in Laravel's .env.

Queue and cache on the Laravel side. Azure calls through DreamFactory are network hops; wrap expensive list operations in Cache::remember() and push writes to a queue when the UI doesn't need synchronous confirmation.

Gotchas and Tips

• It is not auto-discovered. DF 2.x predates Laravel package discovery; if the provider isn't registered you'll see "unknown service type" errors in the admin UI with no hint about the cause. Add it to config/app.php manually and restart the queue/worker processes.
• Service definitions are cached. After editing a service in the UI, if requests still hit the old config, clear DreamFactory's cache (php artisan cache:clear, and the platform's df:cache command if present). This burns everyone once.
• Credentials live in the database, not .env. The account key you enter in the UI is stored (encrypted, depending on version) in the service table. Back up and secure that table; don't assume your secrets management covers it.
• Old Azure SDK dependency. The package pulls in microsoft/azure-storage-php (or similar), which is legacy compared to azure-storage-blob/azure-sdk-for-php. Check compatibility with your PHP version — DF 2.x historically targets PHP 7.x/8.0, and this package is unlikely to be tested against the newest PHP.
• Connection strings vs. shared key. Config schemas differ per service: some want account_name + account_key, some want a full connection string, some want a SAS token. Read getConfigSchema() for the specific service — don't copy a config from another Azure service.
• Debugging is via the platform log. Errors surface in storage/logs/laravel.log and the DreamFactory event log, not in your app's log. When a request returns a generic 500, tail the DF log on the DreamFactory host first.
• Use Azurite locally. Point the service at the Azurite emulator endpoint instead of real Azure for local development; the account name/key are the well-known dev defaults.
• Extension points: subclass a service class in src/Services/ to override behavior, then register your subclass as a new service type in your own ServiceProvider. This is the cleanest way to add custom validation or response shaping without forking the package.
• Very low adoption (1 star). Expect thin documentation and no community answers. Budget time to read the source. If your needs are simple (blob + table CRUD), you may be better served by the current Azure SDK directly in Laravel and skipping the platform layer entirely — the DreamFactory route pays off when you need many services, roles, and generated docs for multiple consumers.
• CORS and rate limits are DreamFactory's job. Configure them on the API key/role, not in config/cors.php of your consuming Laravel app — the browser talks to DreamFactory, not to your app.