Df Rws Laravel Package

Getting Started

dreamfactory/df-rws is the Remote Web Service (RWS) connector module for DreamFactory — the piece that lets the platform expose an external REST or SOAP endpoint as a governed API (auth, roles, rate limits, logging, OpenAPI docs) without writing a controller. Treat it as a platform plugin, not a normal Laravel library: you don't use it in your app's controllers, you install it into a DreamFactory instance (which is itself a Laravel app) and configure it.

Minimal steps

1. Confirm you have a running DreamFactory instance and note its major version — the module's major version must line up with the platform/df-core version, or the service type won't register.
2. Install into that instance:

   composer require dreamfactory/df-rws
   

3. Run the platform's discovery/migration pass (names vary by platform version — check php artisan list for the dreamfactory:/df: namespace, then run the refresh and migrate commands).
4. Clear config/caches, then open Admin UI → Services → Create and look for Remote Web Service. If it isn't in the list, the provider didn't register — check composer.json's extra.dreamfactory block and the module's ServiceProvider.
5. Create a service, point it at a known-good endpoint, and call it: GET /api/v2/{api_name}/... with an API key.

Where to look first

• composer.json → extra.dreamfactory (how the platform discovers it)
• src/ → the service provider, the service-type handler, and the request/response plumbing
• config/ and database/migrations/ → the defaults and the service table shape your config lands in
• The DreamFactory docs for the "Remote Web Service" connector — the module's behavior is documented there more than in the repo.

First use case. Wrap a legacy internal SOAP endpoint (or a third-party REST API your mobile app shouldn't hold keys for) so clients and LLM tool-callers hit one authenticated, role-scoped, rate-limited DreamFactory URL. That is the whole value proposition: credentials and policy stay server-side, clients get a uniform API.

Implementation Patterns

Config-as-code, not click-ops. Service definitions live in the database, so the UI is the easy path and the wrong long-term one. Keep the service payload as JSON in your repo and apply it on deploy:

{
  "name": "shipping_quotes",
  "label": "Shipping Quotes",
  "type": "rws",
  "is_active": true,
  "config": {
    "base_url": "https://legacy.internal/shipping",
    "headers": { "Accept": "application/json" },
    "parameters": {},
    "username": "",
    "password": ""
  }
}

Then POST /api/v2/system/service from a seed/deploy script (or the platform's package-import artisan command). This gives you diffs, review, and rollback.

Passthrough is the default contract. The service maps GET /api/v2/shipping_quotes/rates?zip=... onto the upstream path. Don't expect field renaming, pagination normalization, or error translation for free — those go in server-side scripts (pre/post process) attached to the service, where you can reshape payloads, strip internal fields, and map upstream 4xx into sane client errors.

Auth delegation. The platform handles API keys, JWT, and session auth for your callers. Upstream credentials belong in the service config or, better, pulled from env/user_config so they never sit in a git-tracked JSON. Per-user upstream credentials (each caller supplies their own legacy login) are a legitimate pattern here — store them in the user's config and reference them in the script layer.

Consuming it from Laravel. Your Laravel app is just another client:

$quotes = Http::withToken(config('services.dreamfactory.token'))
    ->baseUrl(config('services.dreamfactory.url').'/api/v2')
    ->get('shipping_quotes/rates', ['zip' => $zip])
    ->throw()
    ->json();

LLM / tool-calling. This is the package's modern niche: expose the wrapped service through DreamFactory's OpenAPI generation and hand that spec to a local model as function definitions. You get tool access to a data source with the platform's role scoping acting as the guardrail — far safer than giving the model raw HTTP egress.

Policy layer. Create one role per consumer (mobile app, internal dashboard, LLM agent), attach only the services each needs, and set per-role rate limits. Use lookup keys rather than sharing a single admin key.

Testing. Seed a service pointing at a stub (WireMock/httpbin) in your test environment and write Pest tests against the DreamFactory API with a scoped key. You are testing configuration and scripts, not PHP units — that's the correct shape here.

Gotchas and Tips

• Version coupling is the #1 failure mode. A mismatched df-core/platform major version makes the service type vanish silently. Pin both, and bump them together.
• Cache blindness. New or edited services frequently "don't exist" until you clear platform and Laravel config caches. Make cache-clearing part of the deploy step, not a debugging afterthought.
• DB-resident config is unversioned. Anything changed in the Admin UI is invisible to git and to code review. Export, commit, and treat the UI as read-only outside local experiments.
• No magic in passthrough. Pagination, retries, timeouts, multipart uploads, and error mapping are all explicit config or scripts. Default HTTP timeouts will bite on slow legacy backends — set them per service.
• SOAP specifics. WSDL fetch/caching failures look like generic 500s; XML→JSON conversion mangles empty elements and attributes. Log the raw upstream response during bring-up.
• SSRF surface. base_url is admin-controlled, but path/verb forwarding plus scripted parameters can be abused if you hand broad roles to untrusted consumers. Restrict verbs and paths per role.
• Debugging order: platform logs → service-specific debug toggle → the exact outbound request your script produced. Almost every bug is "the request I thought I was sending" vs. the real one.
• Secrets. Env placeholders in your committed JSON; never the real upstream password.
• Adoption risk. One star, zero dependents, a low composite score: pin the exact version, avoid relying on undocumented internals, and be ready to fork. Extension points that survive a fork well are the service-type handler and platform event listeners (good for audit logging).
• Check the license fit. Apache-2.0 is friendly, but the surrounding DreamFactory platform has its own commercial tiers — confirm the features you need (roles, limits, OpenAPI) are in the edition you're running before building on them.