Df System Laravel Package

Getting Started

dreamfactory/df-system is not a general-purpose package you bolt onto an ordinary Laravel app — it is one of the internal service components of the DreamFactory platform, pulled in transitively by dreamfactory/dreamfactory (alongside df-core, df-user, df-db, etc.). The practical first step is therefore not composer require, but standing up a DreamFactory instance and letting the platform compose it:

composer create-project dreamfactory/dreamfactory df
cd df
php artisan dreamfactory:setup   # or: php artisan migrate --seed
php artisan serve

Where to look first, in this order:

1. composer.json — check the pinned dreamfactory/df-core constraint; that is the real compatibility contract.
2. The package's service provider (src/Providers/*ServiceProvider.php) — it registers routes, migrations, model bindings, and the system service itself.
3. src/Resources/ (or wherever the shipped *.json Swagger/OpenAPI definitions live) — this is the authoritative list of system/* endpoints and their parameters, more reliable than the README.
4. database/migrations and src/Models — the system service owns records for apps, roles, users, services, API keys, and config-ish state.

First useful use case: scripted inspection of a running instance with the system API, using an admin API key from .env (DREAMFACTORY_API_KEY) or an admin session token:

curl -H "X-DreamFactory-Api-Key: $DF_KEY" http://localhost:8000/api/v2/system/environment
curl -H "X-DreamFactory-Api-Key: $DF_KEY" http://localhost:8000/api/v2/system/config
curl -H "X-DreamFactory-Api-Key: $DF_KEY" http://localhost:8000/api/v2/system/cache

Implementation Patterns

Treat it as an admin/bootstrap API, not a runtime dependency. The highest-value day-to-day pattern is infrastructure-as-code for a DreamFactory instance: create roles, apps, users, services, and API keys from a script or CI job against system/role, system/app, system/user, system/service, so a fresh environment is reproducible instead of click-configured.

Wrap it, don't call HTTP from inside the same app. If you need system data during a request, resolve the service/model classes directly from the container rather than making a loopback HTTP call — you skip auth round-trips and header plumbing. Build a thin internal adapter class in your own code that isolates you from endpoint or payload changes.

Use it for cache/ops actions in deploy pipelines. system/cache (flush/clear), system/environment for a config snapshot, and system/app/system/service for verifying that provisioning landed. These make good smoke tests after a deploy.

Drive provisioning from seeders or artisan commands. Migrations plus a custom seeder that inserts the system service record and your default apps/roles is more robust than ad-hoc curl in a Makefile, and it fails loudly if the schema changed.

Extension point is your own service, not a fork. DreamFactory's model is one service per API namespace. Anything custom belongs in a separate df-* style package/service registered in config/dreamfactory.php, leaving df-system untouched so upgrades stay mechanical.

Client-side auth pattern: admin API key for automation, JWT/session for humans. Keep two separate keys — a read-only key for dashboards that only touch system/environment and system/cache, and an admin key used solely by the provisioning job.

Gotchas and Tips

• Version lockstep is the number-one failure mode. df-system and df-core must move together. A mismatched minor produces migration errors or "service not found" at boot. Pin all dreamfactory/* packages to the same release line and use composer update --with-all-dependencies rather than targeted updates.
• system/environment and system/config can leak secrets. They expose DB credentials, JWT secrets, and third-party keys depending on version and config. Audit Role access to the system service specifically — an API key alone is not the boundary; the role attached to it is.
• Laravel cache vs. DreamFactory config cache are two different things. php artisan cache:clear does not invalidate the platform's cached service/config definitions. After editing a service or .env, use the system cache endpoint or restart the queue/worker processes, or you will debug a phantom stale config.
• Route caching hides vendor routes. php artisan route:cache in some setups freezes the route table before the package provider registers its API routes; if /api/v2/system/* 404s in production but works locally, clear the cached routes first.
• Migrations live in vendor/. A plain php artisan migrate on a fresh checkout may run them out of order relative to your own migrations, and the system service row must exist before the API is usable. Prefer the platform's setup command, and re-run it after upgrades.
• Debugging: php artisan route:list | grep system to confirm registration, storage/logs/laravel.log for service-level exceptions, and the Swagger UI served at the service root to confirm the endpoint actually exists in this version before blaming your client.
• Payload shapes drift between releases (notably around app/role/user nesting and ids/filter parameters). Generate clients from the shipped Swagger JSON per version rather than hand-writing them.
• Forking is a trap. With effectively no external dependents and a tiny star count, you are the only one who will hit your fork's bugs — there is no community to lean on. Extend via your own service or a decorator, and keep the vendor directory pristine.
• Support surface is the DreamFactory docs and forum, not this repo. The GitHub issues/README for a component package like this are thin; budget time for reading source when behavior is undocumented.