Templates#
Reference for the template directories under templates/: which directory bakes which shape, what each one carries, the Squire-owned deploy copy, and the rules the generator applies before it writes anything. Pick a shape first in Pick a shape, then come back here for the exact values.
Five jars on the shelf, all five full.
The template directories#
| Directory | Shape | Status |
|---|---|---|
raw/ |
Raw PHP with WayneUI's standalone path | generates |
raw-vue/ |
Raw PHP + Vue SPA over JSON, layered over raw/ |
generates |
laravel-blade/ |
Laravel + Blade | generates |
laravel-blade-vue/ |
Laravel + Blade + Vue islands | generates |
laravel-inertia/ |
Laravel + Inertia/Vue | generates |
squire/ |
Squire's exported deploy files, not a shape | installed as-is into every app |
The flags that select a shape:
| Flags | Permutation |
|---|---|
(none) or --raw |
Raw PHP with WayneUI's standalone path |
--raw --vue |
Raw PHP + Vue SPA over JSON |
--laravel |
Laravel + Blade |
--laravel --vue |
Laravel + Blade + Vue islands |
--laravel --inertia (or --inertia) |
Laravel + Inertia/Vue |
All five permutations bake: raw PHP since 0.1.0, the three Laravel shapes since 0.1.5 and raw PHP + Vue since 0.1.6. --raw --vue is the raw PHP bake with a Vue 3 front end over it: PHP answers JSON under /api/, Vite builds the Vue app, and src/Vite.php loads it from the build or the dev server.
Bake commands for the five shapes:
raw
sourdough new my-app --raw
raw + vue
sourdough new my-app --raw --vue
laravel
sourdough new my-app --laravel
laravel + vue
sourdough new my-app --laravel --vue
inertia
sourdough new my-app --inertia
What each template carries#
raw/#
- Pins WayneUI 2.0.8 (
https://wayneui.apps.wayne.edu/v2/releases/2.0.8/wayne-ui.php) instead of fetching the floatingmainbranch copy. - Ships Pinstripe's coding standard:
pint.json(the per preset, with the fetchedpublic/wayne-ui.phpkept out andvendorexcluded) andphpstan.neon(Pinstripe's raw preset, level 8 oversrc/andpublic/), withwaynestate/pinstripein require-dev and the extension-installer plugin allowed. - Ships
scripts(test,lint,fix,analyse,proctor,ci) andscripts-descriptions, so a generated raw app can run its own gate locally withcomposer ci, which runs test, lint, analyse, proctor and audit in that order. - Its
.gitlab-ci.ymlruns an explicitcomposer-cijob (composer install, thencomposer ci), mirroring the Laravel overlay, so PROCTOR sees acomposer ciin the pipeline instead of warning that no job runs it. phpunit.xml.distfails the run on any PHP or PHPUnit deprecation and names the test that raised it (failOnDeprecation,failOnPhpunitDeprecation), counting the app's own code (src/,public/, not the fetchedpublic/wayne-ui.php) and skipping indirect deprecations, the ones one package raises because of another.- Ships
stubs/wayne-ui.php, a static-analysis stub for the run-time WayneUI functions (wsu_shell_start,wsu_shell_end) thatphpstan.neonscans throughscanFiles, socomposer ciin a freshly baked raw app no longer fails with function-not-found errors for functions that arrive only with the fetchedpublic/wayne-ui.php. - The front controller answers
404for any path but/(a short not-found page that keeps WayneUI's layout and links home) instead of rendering the home page for every URL;/upstays HELMET's and answers first. - Installs Squire's deploy files from
templates/squire/:build.sh,deployments/001-first-release.sh,scripts/release.sh,scripts/parity.sh,scripts/parity.ps1,health.php,public/up.php,docker-compose.squire.yml,.env.squire.example, and the.squire/build context. - Oracle: raw PHP apps run queries through the
App\Oraclehelper, which takes values only as binds and answers mistakes with plain sentences.
raw-vue/#
sourdough new --raw --vue copies raw/ first, then raw-vue/ over it, so the two raw shapes share the same Squire files, Pinstripe checks, Oracle helper, Playbook and ADVISOR wiring. The manifest records the template as raw-vue.
public/index.phpboots HELMET, the session and SESAME exactly asraw/does. Paths under/api/answer JSON:/api/mereturns the signed-in user (usernameandname), an unknown endpoint is a JSON404, and a request without a session is a JSON401instead of a redirect to CAS./sends the page that loads the Vue app; any other path sends the same page with a404, and Vue says the page does not exist.src/Vite.phpprints the stylesheet,modulepreloadand script tags forresources/js/app.jsfrompublic/build/manifest.json(imported chunks and their CSS included), each with HELMET's CSP nonce. Whilenpm run devruns,public/hotholds the dev server's origin and the helper points at it instead, and adds it to the CSP; withAPP_ENV=productionthe hot file is ignored.tests/ViteTest.phpcovers both paths.package.jsonpins@waynestate/wayne-ui-cssand@waynestate/wayne-ui-vue2.0.8 exactly, as the Inertia shape does, with Vue 3 and Vite 6.resources/css/app.cssimports WayneUI's layereddist/wayne-ui.css, andresources/js/App.vuedraws the page with WayneUI's app bar, environment ribbon, cards and footer, served from the app's own origin (no CDN).vite.config.jsbuilds intopublic/buildwith the manifest at its top, keepspublic/(PHP's document root) out of the copy, and writes and removespublic/hotaround the dev server..gitignoreadds/node_modules/,/public/build/and/public/hot. The template shipspackage-lock.json(seeded: yours after the bake), so CI and Squire's release script runnpm cifrom it on the first push.- Drops
stubs/wayne-ui.phpandphpstan.neon'sscanFiles: Vue draws the chrome, so there is no fetchedpublic/wayne-ui.php. - Its
.gitlab-ci.ymladds afrontendjob (npm ci --ignore-scriptsfrom the shippedpackage-lock.json,npm audit --audit-level=high --omit=dev(runtime dependencies; a second run lists dev-only findings without failing),npm run build, andsbom-npm.cdx.jsonfrom CycloneDX's npm tool) to the raw pipeline, and itsa11y-pagesjob waits for that build and also saves/api/me, so the accessibility gate sees the Vue app signed in.
laravel-blade/#
- A fresh Laravel skeleton from Composer, the laravel-blade overlay, the stack packages, Squire's laravel deploy files and the manifest.
- Ships
app/Providers/AppServiceProvider.phpwithSchema::defaultStringLength(191), so string columns stay inside Citadel's MySQL 5.6 index limit (PROCTORmysql56-string-default). - The views read the signed-in user as an array (
$user['name']), because SESAME'sSesame::user()returns an array, not an object. - Deprecations fail the suite: the bake adds
failOnDeprecation,failOnPhpunitDeprecationand the twodisplayDetailsOn...flags to the skeleton'sphpunit.xmlandignoreIndirectDeprecationsto its<source>, leaving the rest of the file as Laravel wrote it.tests/TestCase.phpusestests/Support/ReportsDeprecationsToPhpUnit.php, which hands deprecations back to PHPUnit's handler during each test, because Laravel's handler drops them while testing. The other Laravel shapes ship the same. config/helmet.phpholds only the app's own override,policy_path(the CREED policy the environment ribbon reads). Every other HELMET setting comes from the package's config, which HELMET's provider merges in, socomposer updatebrings new settings and fixes instead of a stale copy hiding them. The other Laravel shapes ship the same file.- Pinstripe is installed, not copied:
phpstan.neonincludes Pinstripe's Laravel preset (level 8, the ignore hygiene and the banned calls come from the package) andpint.jsonis Pinstripe'slaravel.jsonplus three recorded skips for Squire's files (deploy,health.php,oracle-check.php). The app's owntests/Unit/PinstripeWiringTest.phpholds both files to that, so a new skip needs its reason written down.composer lint:gitlabwrites Pint's findings as a GitLab Code Quality report (pint-codequality.json, ignored by git), and thecomposer-cijob runs it inafter_script, so the merge request widget shows Pint's findings even whencomposer cifails. The other Laravel shapes ship the same, as WELD does. - Next steps:
composer install,cp .env.example .env,php artisan key:generate,php artisan migrate,php artisan serve.
laravel-blade-vue/#
- The Laravel + Blade bake under a front-end layer: Vite with the Vue plugin, a
resources/js/app.jsregistry that mounts a Vue 3 app on every[data-vue-island]element, and a Counter island live on the dashboard view. - Ships
tests/Feature/ExampleTest.phpwith$this->withoutVite(), socomposer ciin a freshly baked islands app does not fail on the missing Vite manifest beforenpm run buildhas run. - Its own
.gitlab-ci.yml: the Laravel + Blade pipeline plus afrontendjob (npm ci --ignore-scripts,npm audit --audit-level=high --omit=dev,npm run build, the npm SBOM), whosepublic/build/thea11y-pagesjob serves, because Blade's@vitereads the build's manifest. - Next steps: the Laravel + Blade steps plus
npm installandnpm run build.
laravel-inertia/#
- The same Laravel skeleton, the laravel-inertia overlay (Inertia pages rendered by Vue, Ziggy routes, the stack packages), Squire's laravel deploy files and the manifest.
- Inertia 3 on both sides:
inertiajs/inertia-laravel^3.0and@inertiajs/vue3^3.0. The root view marks its<title>withdata-inertia, Inertia hands the first page to Vue in a<script type="application/json">element (data, not code, so HELMET's CSP has nothing to admit), and no Axios: the pages talk through Inertia's own client. Addaxiostopackage.jsononly when your own code imports it.resources/js/app.tshands HELMET's per-request nonce (read from the pre-paint script) to Inertia'snonceoption, so the progress bar's injected styles pass the CSP. - Ships
AppServiceProvider(string length 191 for Citadel's MySQL 5.6) and atests/TestCase.phpthat writes a stub Vite manifest, so view tests boot without a build. - The
.gitlab-ci.ymlcarries theziggyjob: it regeneratesresources/js/ziggy.*and fails on any diff, so the route list that ships inside the Vite bundle always matches the routes. - The overlay allows
phpstan/extension-installer; the appended SESAME and HELMET env keys ship commented out (exceptSESAME_DRIVER=fake) so package defaults hold instead of being overridden by empty values.config/sesame.phpdefaultsSESAME_FAKE_USERNAMEtojane.doe, so the fake driver has a non-empty username. - Next steps: the Laravel + Blade steps plus
npm installandnpm run build.
Shared wiring in every app#
| Part | What lands in the app |
|---|---|
| Stack packages | HELMET ^1.3, SESAME ^0.7, PROCTOR ^0.15, and in the Laravel shapes CREED ^0.1.8 (PROCTOR's composer proctor script is plain proctor check: PROCTOR refuses --policy in CI since 0.6 and finds CREED's released policy in vendor/waynestate/creed by itself; 0.7 adds proctor gate, which the Squire kit's release script runs; 0.8 fails a deploy script with Windows line endings; 0.9 fails two paths that differ only by case; 0.10 warns on a secret-looking VITE_ variable; 0.11 adds --record; 0.12 warns when composer.json sets no release cooldown and when git does not track composer.lock; 0.13 compares the release cooldown with the CREED policy; 0.14 warns when a script in scripts/ has no .ps1 or .sh twin). The raw shapes also require Guzzle and nyholm/psr7, the HTTP client and factory the cas driver checks tickets with |
| Playbook | waynestate/playbook in require, the VCS repository, config.gitlab-domains so Composer sends your token to git.wayne.edu, the seven setting names in .env.example, a composer playbook script that shows whether Playbook is installed, and a "WSU values (PLAYBOOK)" README section that explains how to get read access |
| ADVISOR | waynestate/advisor in require-dev, .mcp.json git-ignored (a client config starts a program for whoever opens the project), a README "ADVISOR" section; install with php vendor/bin/advisor install --client=claude --write |
| Preflight | .gitlab-ci.yml pins the Preflight CI components to the 0.9.0 release SHA (fb73b538f3980292119b5b306ff64383d760a214, with the tag in a trailing comment), which PROCTOR's preflight-pinned check accepts on every PROCTOR the shapes allow (0.4 to 0.7 want a 40-hex SHA; 0.8 also takes a release tag). The includes pass no image inputs, so each component runs its own default image, pinned by digest inside that release, and the ones that pull from Docker Hub pass image_prefix: "${IMAGE_PREFIX}", so the components and the app's own jobs pull through the same Dependency Proxy rule (a11y pulls Playwright's image from Microsoft's registry and takes none) |
| CI gates | every shape's .gitlab-ci.yml includes Preflight's sbom (Composer SBOM), secret-detection (Gitleaks) and a11y (axe-core at WCAG 2.2 AA over a11y-site/, which the a11y-pages job fills by booting the app with SESAME's fake driver and saving each page in A11Y_PATHS), and carries a hidden .deploy template that runs only on protected refs and never for a merge request; the three Laravel shapes also include mysql56-migrate, which runs php artisan migrate against a real MySQL 5.6.51 service on an amd64-tagged runner, because the tests' SQLite accepts DDL that 5.6 rejects. tests/TemplateCiGatesTest.php holds all five shapes to it; see CI |
| Oracle | wired but dormant: ORACLE_USERNAME, ORACLE_PASSWORD, and either ORACLE_TNS or ORACLE_HOST, ORACLE_PORT, ORACLE_SERVICE_NAME ship commented out in .env.example; while they are empty, nothing connects and nothing errors. Laravel apps check the wiring with php artisan oracle:check |
| PHP floor | require.php, config.platform.php, the .gitlab-ci.yml test matrix and the README's test-suite line, read from CREED's policy.json at bake time (today ^8.3, 8.3.0, tested on 8.3, 8.4 and 8.5). The templates carry those values as the pinned fallback for a policy that cannot be read. The Docker base and the Sail runtime stay pinned, and a test holds them to a line the matrix tests. See The PHP floor |
| Manifest | .sourdough/manifest.json: the Sourdough version, the template, the answers you chose, and a sha256 hash of every file, each marked managed or seeded |
| Plan | .sourdough/plan.yaml: the plan the app was baked from, written after the bake. Not in the manifest, so neither managed nor seeded; feed never touches it. See The saved plan |
Seeded files are .env.example and README.md: Sourdough wrote them once and you own them now. Managed files belong to Sourdough; the manifest is the record sourdough feed refreshes, merging in any edits you made. See The manifest.
The Squire-owned copy (templates/squire/)#
The deploy files in your app come from Squire's exported copy, checked into this repository at templates/squire/: raw/, laravel/, static/, vue/, catalog.json, manifest.json. The copy is Squire 0.11.1's kit: it ships a .gitattributes that pins line endings (LF for shell scripts, .conf files and Dockerfiles, CRLF for PowerShell), so the deploy layer clears PROCTOR's line-ending warnings; a Laravel release first refuses to run with no APP_KEY or with APP_DEBUG on in production (and warns when APP_ENV is not production); then its scripts/release.sh runs PROCTOR's deploy gate (proctor gate) right after composer audit, before the frontend build and the migrations, writes the verdict to storage/squire/proctor-gate.json (SQUIRE_PROCTOR_RECORD_DIR), the baseline the next release is ratcheted against, and after the optimize step restarts Laravel's long-lived processes (php artisan reload, or queue:restart and schedule:interrupt on an older Laravel; report only, SQUIRE_ARTISAN_RESTART=0 turns it off). The image hardens too: the web's PHP loses its shell functions (SQUIRE_PHP_DISABLE_FUNCTIONS sets the list), opcache runs with production settings (SQUIRE_OPCACHE_VALIDATE), Apache answers ServerTokens Prod, and secrets can be read from /run/secrets. Session cookies are SameSite=Lax (.squire/php.ini), every image the kit builds from is named in full (docker.io/library/...) so Buildah and Podman take it, and the portable image ships the built assets without node_modules/. Squire owns those files; Sourdough never hand-edits them, installs them as-is and records them in the manifest, so you never edit them by hand.
| Command | What it does |
|---|---|
composer squire-copy:sync |
rewrites the copy from the installed waynestate/squire package (dev dependency ^0.11) |
composer squire-copy:check |
exits 1 when the committed copy has drifted; part of composer ci |
When Squire's templates change, regenerate the copy from a Squire checkout, then verify it:
php ../squire/bin/export-templates.php --to=../sourdough/templates/squire
php ../squire/bin/export-templates.php --to=../sourdough/templates/squire --check
Commit the refreshed copy with the Squire commit in the message, and add a CHANGELOG line.
Rules the generator applies#
From the best-practices notes, section 1 (Generating a project):
| Rule | What it requires | Stack today |
|---|---|---|
| Make the permutation an explicit, validated input | take the permutation from flags (--raw, --vue, --laravel, --inertia) and refuse combinations that make no sense, such as --inertia without --laravel |
Enforced: Permutation::fromFlags() refuses the combinations that make no sense; tests/PermutationTest.php covers every valid row and every refused one (--inertia alone means --laravel --inertia) |
Offer --dry-run, and make it write nothing |
print the plan (files, packages, commands) and change nothing on disk | Enforced: sourdough new --dry-run prints the plan and writes nothing (testDryRunWritesNothingAndExitsZero in tests/NewCommandTest.php) |
| Refuse a non-empty target | refuse to generate into a directory that already has files; if overwriting is ever allowed, require a --force flag and prompt only when the session is interactive |
Enforced: every generator refuses a file or a non-empty directory before writing (testRefusesNonEmptyTarget); there is no --force |
| Use exit codes that scripts can rely on | 0 on success and distinct non-zero codes for the main failure modes, documented; PROCTOR uses 0 pass, 1 fail, 2 tool error | Checked: 0 done, 1 refused or failed, 2 tool error, the same scheme as PROCTOR (see the commands reference) |
| Keep output friendly to people and to machines | results to stdout and logs, warnings and errors to stderr, --json for the plan, color off when output is not a terminal, when NO_COLOR is set, or with --no-color, prompt only when stdin is a terminal, and --no-input so CI and agents never hang |
Checked: errors go to stderr, --json is tested, NO_COLOR wins, --no-input is accepted (the CLI never prompts); there is no --no-color flag yet |
| Test the generator on every permutation, in temp directories | generate each permutation into a temp directory and compare the result with a stored snapshot; test commands through a tester class rather than a real terminal | Documented; Laravel paths need the network, so their tests run in a pipeline job instead of the unit suite |
| Treat names, paths and templates as untrusted input | check <dir> and any app or vendor name against an allow-list before the value reaches a file name, a composer.json or a command line; refuse any write whose resolved path falls outside the target directory; keep templates as data: placeholder substitution only, with no code in a template running during generation |
Enforced for names: RawGenerator::assertValidName() checks every name (letter or number first; then letters, numbers, spaces, dots, dashes and underscores; at most 63 characters) before generation touches the disk, and the test suite generates with hostile names (quotes, backslash, newline, NUL byte, {{app_slug}}, path traversal, 64 characters, empty, dashes only, leading dash or dot, a Unicode look-alike), asserting the exception and an absent or empty target dir. Paths stay inside the target by construction: the slug is [a-z0-9-] only and every write path is built under the target dir |
| Make the "new app" page and the CLI one engine | the page calls the same plan code as sourdough new --dry-run --json, shows the equivalent command, validates on the server with the rules above, and returns the same archive the CLI would write; a snapshot test compares the two |
Documented for the page itself; Not yet for the shared-engine rule |