[nicdavidson]

Refs #130

What

• Document platform.api signatures per scripting engine #130: The scripting page said every platform.api verb takes the same arguments (method(path[, payload[, options]])). That is wrong for all three engines. The page now has a per-engine signature table for get, post, put, patch, delete and call (Node.js, Python/Python3, PHP). It adds one working example per engine and notes on callbacks, return types and PHP closures.
• Document platform.api signatures per scripting engine #130: Two PHP examples in event-scripts.md called the platform.api closures as methods, which fails with Call to undefined method stdClass::get(). Both now assign the closure to a variable first.
• Document platform.api signatures per scripting engine #130: New "Script output and logging" section. Script stdout is written to storage/logs/dreamfactory.log at INFO, once per run.

Behavior change

Documentation only. Nothing in the product changes.

• The scripting reference now lists the real platform.api arguments for Node.js, Python and PHP.
• Node.js: calls are async, and the callback must be the last argument. A delete with a payload is sent as POST with X-HTTP-Method: DELETE. To send a real DELETE, pass null for the payload. Set results inside a callback with event.setResponse(...).
• Python: calls are synchronous and return an HTTP response object. The payload must be a string, so use json.dumps(...).
• PHP: $platform['api'] members are closures. Assign one to a variable before calling it.
• Script output only appears in the log if APP_LOG_LEVEL is info or more verbose.
• The PHP examples in event-scripts.md now use the closure form.

Tests

df-docs has no test suite. The gate is the Docusaurus build.

• OK docs build: the site builds with the new #platform-api and #script-output-and-logging anchors resolving. 0 failures on base, 0 on this branch.
• Checked by grep: the "They all accept the same arguments" text is gone, and no $platform->api->… or $platform['api']->get(...) method-style calls remain in docs.
• Reviewed over 3 rounds against the df-script source (NodeJs.php, Python.php, Python3.php, BaseEngineAdapter.php, ScriptHandler.php). Round 1 found a Python POST example that would crash on a dict payload. Round 2 found a Node example whose result was silently dropped inside the async callback. Both are fixed. Round 3 approved.
• Not run: the examples were checked against the source, not executed on a live instance.

Scope

• In (df-docs only, 3 pages, no sidebar or dependency changes):
  • scripting-resources.md: signature table, per-engine examples and notes, logging section.
  • event-scripts.md: PHP example fixes and two cross-links.
  • scripted-services-and-endpoints.md: one link to the signature table.
  • Also removed a stray empty #### Event request heading that sat under #### Platform API, so the new anchor lands on the reference.
• Out: df-script behavior changes, platform.log, a runtime log-level page, and reshuffling the rest of scripting-resources.md.

Related issues

Not fixed here:

• Node platform.api: fix hangs, silent wrong-order calls, and 500 on no callback df-script#75 (draft): fixes Node platform.api hangs, makes payload and callback optional, and throws on wrong argument order. The wording here (callback last, null payload for delete) stays true after it merges. A follow-up doc update is needed once it ships.
• Node platform.api: wrong argument order fails silently (callback never fires) df-script#70, add page for installing oracle and trino drivers #72, create new tab in security for authentication methods setup, and add … #73, Add llms txt #74: Node wrong-order and missing-callback failures. Fixed by Created guide for configuring SQL Server connection #75.
• Node platform.api: non-string payload (number, boolean) throws and hangs the script df-script#76: a non-string payload (number, boolean) hangs Node scripts. The docs say the payload is an object or a string.
• Add platform.log(level, message) for scripts df-script#69: proposed platform.log(level, message). It would change the logging note.
• Add runtime log level override: system/server_setting, admin UI, docs #138 (draft): runtime log-level override page. Link to it from the logging section once it merges.

Open question: the issue says the default APP_LOG_LEVEL is warning, while windows-installation.md says the dev default is debug. This was not verified, so the docs name no default.

Existing issues found, not fixed

• Python also accepts a bare headers object as options (Python3.php:136-137). The page says only Node.js does. Suggested wording: "Both also accept a bare headers object."
• A Node delete with null still sends the 4-byte body "null" as a real DELETE. Harmless, but '' sends a truly empty body.
• The PHP example's [CURLOPT_TIMEOUT => 10] has no effect on an internal path. ['parameters' => ['limit' => 5]] would match the other examples.
• PHP curlOptions also accepts parameters and headers keys. The page does not say so.
• Scripted services skip the output log line when called with ?log_output=false. The page does not mention it.
• The new Node post example can hang on IIS without a Content-Length header (see windows-installation.md).

---

Factory gate

• Result on the branch: OK docs build
• New failures vs base: none (0 tests already fail on base and are excluded)
• New tests that fail on base and pass here: none

Open review notes (not blocking, from the factory's final review)

1. scripting-resources.md:123: "Node.js also accepts a bare headers object." Python accepts one too (Python3.php:136-137, elif(options): header = options). Change it to "Both also accept a bare headers object."
2. scripting-resources.md Node delete note: null does not send a body-less DELETE. typeof null === 'object', so JSON.stringify(null) writes the 4-byte body "null" (NodeJs.php:208-209,226). This is harmless, and it is the workaround the issue asked for. '' would send a truly empty body. You could add "(or '')".
3. PHP example [CURLOPT_TIMEOUT => 10]: carried from review 2, still open. It is a no-op for an internal path. ['parameters' => ['limit' => 5]] would mirror the Node and Python examples.
4. Logging paragraph: output is also skipped when the request carries log_output=false (Services/Script.php:311, ScriptServiceJob.php:57). You could add one clause. Open PR Add runtime log level override: system/server_setting, admin UI, docs #138 (runtime log-level override via system/server_setting) is also a natural cross-link once it merges.

[netlify]

✅ Deploy Preview for dreamfactory-docs ready!

Name	Link
🔨 Latest commit	b6af4e5
🔍 Latest deploy log	https://app.netlify.com/projects/dreamfactory-docs/deploys/6ae2c5ff6c4f87c494da274f
😎 Deploy Preview	https://deploy-preview-139--dreamfactory-docs.netlify.app
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.

---

To edit notification comments on pull requests, go to your Netlify project configuration.