Skip to content

docs: app developer guide for making a PHP app work as a preview - #5

Open
luthermonson wants to merge 1 commit into
mainfrom
docs/preview-app-guide
Open

docs: app developer guide for making a PHP app work as a preview#5
luthermonson wants to merge 1 commit into
mainfrom
docs/preview-app-guide

Conversation

@luthermonson

Copy link
Copy Markdown
Contributor

Adds docs/preview-app-guide.md — the "make your PHP app work here" guide for
app developers deploying to a switchboard-driven preview host.

Switchboard owns the ephpm.yaml contract (src/manifest.rs), so the manifest
reference belongs here rather than in ePHPm's site. Server behaviour is
cross-linked to https://ephpm.dev rather than duplicated.

What it covers

  • ephpm.yaml v1, every field with its default and semantics, plus the
    framework-synthesized defaults for a repo that ships no manifest, and
    ${secret.NAME} resolution.
  • The $_SERVER-not-getenv() rule — the highest-value item. Includes the
    measured $_SERVER/$_ENV/getenv matrix, why variables_order = EGPCS
    makes getenv() return a wrong value rather than a missing one, and the
    verified phpdotenv/Laravel adapter order that makes env() work.
  • Database — the native ephpm_db_* bridge vs stock pdo_mysql, with the
    per-site injected key list (both DB_NAME/DB_USER and Laravel's
    DB_DATABASE/DB_USERNAME), and the credential rotation caveat.
  • KV/Redis — native packages vs RESP, with the EPHPM_REDIS_* vs
    REDIS_* naming asymmetry called out and a worked mapping.
  • Restrictions — the exact open_basedir and disable_functions values
    read back from a live preview, and a dedicated callout for disabled
    persistent connections.
  • Recipes for WordPress, Laravel, Symfony and bespoke apps.
  • Sessions and WebSockets, and a section on why build:/seed: cannot
    reach the preview's database.

Verification

Everything marked Verified was executed against a running ePHPm build
(PHP 8.5.7, sites_dir multi-tenant mode with per-site Turso + KV) or read in
source at ephpm/ephpm@2ca6535 / this repo at ca203ff. Unverifiable items are
labelled Not tested; unmerged behaviour is labelled Planned.

Three findings from that verification are documented as current gaps rather
than written around:

  1. docroot: does not change what the server treats as the web root. A repo
    with only public/index.php returns 404 at /, and composer.json,
    vendor/ and storage/logs/*.log are served with 200. Filed as
    docroot: is not honoured — the repo root is served, so front-controller apps 404 and vendor/ + storage/logs are public #3.
  2. The env: block does not reach PHP for docroot: "." apps — the generated
    prepend is never auto-loaded (ini_get('auto_prepend_file') is empty), and
    no .env is written in that case. Filed as env: never reaches PHP for docroot: "." — the generated prepend is not auto-loaded #4. A verified
    one-line app-side workaround is documented in the meantime.
  3. seed: steps cannot reach the preview database at all — verified, including
    that ephpm php returns ephpm: no embedded database is active. The guide
    documents the over-HTTP pattern ephpm/wordpress-sample already uses.

Documents the ephpm.yaml v1 contract field by field, and the multi-tenant
constraints an app author cannot predict: credentials arrive in $_SERVER
only, the served web root is the repo root regardless of docroot:,
persistent connections are disabled, and build/seed run outside ePHPm so
they cannot reach the preview's database.

Every claim was executed against a running ePHPm build or read in source;
unverifiable and unmerged behaviour is labelled rather than implied.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant