docs: app developer guide for making a PHP app work as a preview - #5
Open
luthermonson wants to merge 1 commit into
Open
docs: app developer guide for making a PHP app work as a preview#5luthermonson wants to merge 1 commit into
luthermonson wants to merge 1 commit into
Conversation
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.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Adds
docs/preview-app-guide.md— the "make your PHP app work here" guide forapp developers deploying to a switchboard-driven preview host.
Switchboard owns the
ephpm.yamlcontract (src/manifest.rs), so the manifestreference belongs here rather than in ePHPm's site. Server behaviour is
cross-linked to https://ephpm.dev rather than duplicated.
What it covers
ephpm.yamlv1, every field with its default and semantics, plus theframework-synthesized defaults for a repo that ships no manifest, and
${secret.NAME}resolution.$_SERVER-not-getenv()rule — the highest-value item. Includes themeasured
$_SERVER/$_ENV/getenvmatrix, whyvariables_order = EGPCSmakes
getenv()return a wrong value rather than a missing one, and theverified phpdotenv/Laravel adapter order that makes
env()work.ephpm_db_*bridge vs stockpdo_mysql, with theper-site injected key list (both
DB_NAME/DB_USERand Laravel'sDB_DATABASE/DB_USERNAME), and the credential rotation caveat.EPHPM_REDIS_*vsREDIS_*naming asymmetry called out and a worked mapping.open_basediranddisable_functionsvaluesread back from a live preview, and a dedicated callout for disabled
persistent connections.
build:/seed:cannotreach the preview's database.
Verification
Everything marked Verified was executed against a running ePHPm build
(PHP 8.5.7,
sites_dirmulti-tenant mode with per-site Turso + KV) or read insource at
ephpm/ephpm@2ca6535/ this repo atca203ff. Unverifiable items arelabelled Not tested; unmerged behaviour is labelled Planned.
Three findings from that verification are documented as current gaps rather
than written around:
docroot:does not change what the server treats as the web root. A repowith only
public/index.phpreturns 404 at/, andcomposer.json,vendor/andstorage/logs/*.logare served with 200. Filed asdocroot: is not honoured — the repo root is served, so front-controller apps 404 and vendor/ + storage/logs are public #3.
env:block does not reach PHP fordocroot: "."apps — the generatedprepend is never auto-loaded (
ini_get('auto_prepend_file')is empty), andno
.envis written in that case. Filed as env: never reaches PHP for docroot: "." — the generated prepend is not auto-loaded #4. A verifiedone-line app-side workaround is documented in the meantime.
seed:steps cannot reach the preview database at all — verified, includingthat
ephpm phpreturnsephpm: no embedded database is active. The guidedocuments the over-HTTP pattern
ephpm/wordpress-samplealready uses.