PHP Fallback

PHP provides a baseline and backup in AI Worker 1.0.0. It lets requests run before an external worker is configured, when Enable PHP Worker is Yes, secrets and provider credentials are saved, and the host can support the flow below. PHP is a worker in its own right: Enable External Worker can be No and the configured AI features remain available.

Choose How PHP Is Used

Save the worker secrets under Hyvä AI → AI Worker and your provider credentials under Hyvä AI → Settings. The two worker switches are independent:

For PHP-only operation, set Enable External Worker → No and Enable PHP Worker → Yes. You do not need to erase a saved external URL. Text, section, page and image generation remain subject to each feature's own enablement, provider/model configuration and installed adapters.

Run Test Connection after saving. It checks PHP separately from any external worker. PHP reads Magento's saved secrets directly; you do not copy them into another configuration.

Choose AI Worker in the feature's execution setting to use these rules. Direct PHP is a separate mode for short requests through the base AI module.

PHP supports text streaming, tools and incremental page previews through the installed provider packages. Gemini and OpenAI packages also supply image adapters. The PHP worker reports only the adapters installed on your store. A failed external connection can hand the same request to PHP. Only one worker can claim that request, so backup never starts a second copy of work already accepted.

Hosting Checks

These checks are for your developer or hosting provider.

• Use Magento's normal PHP extensions, including cURL and OpenSSL, and allow outbound HTTPS to providers.
• PHP must reach the store's own secure URL for short request-retrieval and result-callback calls. A callback URL override can provide another reachable Magento URL. These calls are restricted to its configured origin and refuse redirects.
• In a Docker development environment, check that the PHP container resolves the store host to the web proxy and not to itself: curl -sS -o /dev/null -w '%{http_code}' https://<store host>/ from inside the container. A hosts entry written when the container was created goes stale once the proxy restarts on another address, and Test Connection then reports No worker is ready with a refused connection on the PHP line. Recreate the container to refresh it.
• Keep spare PHP-FPM children available while AI is generating. Each generation occupies a child; retrieval and callbacks need additional capacity. A synchronous call through the worker can occupy two waiting children before retrieval. A single-process PHP development server cannot serve this flow.
• Use PHP-FPM for background dispatch. fastcgi_finish_request() answers the caller early but keeps the FPM child busy. Magento cron is still required. Without detachment, use Connected holder transport and the consumer described in Operations.
• Check PHP-FPM termination settings and proxy/load-balancer deadlines. They can end work before the worker's configured limit, which is capped at 600 seconds. The module changes no server settings.
• Allow /hyva-ai-worker-php/ streams through without buffering or caching. The endpoint is derived from the default store view's secure link URL, including any subdirectory or store-code path.

Allow PHP backup only when the store has enough spare capacity during an outage. Set Enable PHP Worker → No if protecting storefront capacity takes priority over continuing AI work during that outage.

Certificates and Staging Access

The browser and PHP must trust the worker endpoint's certificate. CORS permits the configured Magento admin origin. If admin and storefront use different hosts, allow the storefront worker origin in the admin's Content Security Policy.

For local development, prefer trusting the development CA in PHP. Skip TLS Verification On Loopback is off by default and applies only when the callback host is localhost, 127.0.0.1 or [::1]. Any other callback host is always verified. It does not change provider TLS verification.

For HTTP Basic-auth staging, expose MAGENTO_HTTP_AUTH_ORIGIN, MAGENTO_HTTP_AUTH_USERNAME and MAGENTO_HTTP_AUTH_PASSWORD to PHP-FPM. Use the exact callback origin. These authenticate nested Magento calls; initial browser/Magento access to the worker route must also satisfy any protection on that route. See Basic-auth setup.