Framework Laravel Package

Technical Evaluation

Pollora is a Laravel-native WordPress framework (Blade, Vite, service container and artisan tooling over WordPress). The delta under review is v13.36.1 → v13.38.1. v13.38.1 is a bugfix-plus-hardening release, not an architectural one: no new packages, no namespace moves, no contract changes. It fixes local-environment breakage (scheme-less APP_URL, Valet/Herd self-redirect loop, /cms/wp-admin/ 404) and adds two diagnostics (Site Health check for .env exposure, pollora:doctor warning for APP_URL without a scheme). The v13.36.1 decomposition and the pollora/query 2.0 semantics risk remain the dominant items and are unchanged.

• Architecture fit — unchanged, with a new touchpoint. No ports-and-adapters movement; the split described for 13.36.1 stands. What is new is that Pollora now interposes in two places it previously did not: URL derivation (a scheme-less APP_URL is read as http://… for WP_HOME, WP_SITEURL, cookie path and console host) and request dispatch (a PHP file that has included the front controller counts as Laravel serving the request; a request for a public/ directory holding an index.php is routed to that file). Both are pragmatic fixes for Valet/Herd, but they move environment-detection heuristics into the framework's request lifecycle — the layer where surprises are most expensive.
• Integration feasibility — high. Consumers on the public surface need no code change; this is a minor bump from 13.36.1. The only integration surface that shifts is operational: document root, APP_URL format, and subdirectory installs (/cms/). Teams already on 13.36.1 should treat 13.38.1 as a should-take patch.
• Technical risk — the query bump is still the headline; this release adds a quieter one.
  • pollora/query ^1.0 || ^2.0 and the silent result-set changes (where()/orWhere() grouping, inclusive DateQuery, 24-hour clock) plus the new QueryException throws are unchanged and still the highest-severity item. Nothing in v13.38.1 mitigates or narrows it.
  • New: HTTP downgrade by coercion. A scheme-less APP_URL is now repaired as http://, not rejected. On a developer laptop that is exactly right; on a misconfigured staging or production .env it silently converts an https:// site into an http:// one — cookie path, canonical URLs and asset origins follow — and the only signal is a pollora:doctor warning that says what to write. This trades a loud 500 for a quiet downgrade, which is the wrong direction for prod.
  • New: widened front-controller surface. "A request for a public/ directory that holds an index.php is now sent to that file" is a routing rule, not a bugfix scoped to Valet. Verify it does not expose or shadow anything in our public/ tree, and that the included-front-controller detection cannot misfire on Bedrock or other web/-rooted layouts where the entry point is included by a bootstrap.
  • New: the Site Health .env check performs an HTTP request to /.env. Behind a catch-all front controller, a WAF, basic auth or an edge cache, the response is not a reliable proxy for "the file is served" — expect false positives (page HTML returned) and false negatives (403 from the WAF masking a genuinely served file).
  • Multi-package version matrix, Infrastructure\Laravel namespace moves, and the AssetFile::resolveUsing() resolver bootstrap requirement all carry over unchanged.
• Key questions
  • What shipped in 13.37.0 and 13.38.0? These notes cover only 13.38.1; we are two minors past the last assessment and cannot assume the gap is empty.
  • Is the scheme-less APP_URL coercion environment-aware (dev-only), or does it apply in production? If the latter, can it be made a hard failure outside local?
  • Minimum Laravel/PHP/WordPress floors per package, and is the four new packages + framework + pollora/query matrix published and lockstep-released? (carried over, still unanswered)
  • Do the moved Infrastructure\Laravel classes ship aliases or a deprecation shim? (carried over)
  • When does the framework drop pollora/query ^1.0? (carried over)
  • Does the Site Health .env probe distinguish "served the file" from "served the app's 200 page", and does it run on every Site Health load (self-request cost) or only on demand?
  • Does pollora:doctor now detect package/framework version skew, or still only configuration problems? (carried over — the new APP_URL check suggests the check suite is growing, but not that it covers skew)
  • Do the new packages publish config/assets that must be added to vendor:publish? (carried over)

Integration Approach

• Stack fit. Unchanged stack (Laravel + WordPress + Blade + Vite). This release is specifically about how that stack is hosted: Valet, Herd, MAMP/Apache/nginx, subdirectory installs, and hand-written .env files. Nothing about how a Pollora site is built changes.
• Migration path.
  1. Read the pollora/query 2.0 upgrading guide; inventory queries using where()/orWhere() chains, DateQuery, fields(), orderBy() direction and userPermission(). (unchanged — still step one)
  2. Upgrade Pollora with pollora/query pinned to ^1.0 in a branch to isolate the decomposition from the query semantics change. Take 13.38.1 in the same pass — there is no reason to stage two upgrades.
  3. Grep for direct imports of moved classes (MetaServiceProvider, LaravelMetaValidator, TypedMetaCheck, MetaListCommand, MetaAuditCommand, RoleServiceProvider, EnsureUserHasRole, RoleDirective, RolesCheck) and fix namespaces.
  4. Audit manual construction of AssetFile/AssetManager/MissingBuilds and any MetaUiDrivers or extend() callback for the new resolver and PSR-11 signature.
  5. New: APP_URL audit across every environment. Assert an explicit scheme everywhere; treat any scheme-less value found in staging or production as a defect, not a value the release will fix for you. Confirm pollora:doctor is green on each environment after the bump.
  6. New: document-root and routing smoke test. Confirm the vhost points at public/, then exercise /, /wp-admin/, /cms/wp-admin/, a public/ subdirectory containing an index.php, and /.env — on Valet/Herd and on the production-like nginx/Apache target, since the new rules are dispatch-level.
  7. Confirm asset publishing and the block-bindings preview route are registered.
• Compatibility. pollora/query 1.x/2.0 dual support is a bridge, not a resting state — plan for 2.0-only. The AssetFile::resolveUsing() resolver must be set by the provider, so any bootstrap that bypasses AssetServiceProvider will fail silently. New: the front-controller detection assumes the entry point is included by the server wrapper; validate on any deployment where index.php is reached differently.
• Sequencing. (1) Query audit and result-set diffing on staging → (2) framework upgrade to 13.38.1 with query pinned → (3) unpin and re-run query assertions → (4) namespace/contract fixes → (5) APP_URL + docroot + routing verification per environment → (6) asset + preview route verification in build and hot mode → (7) Site Health / doctor green check on every environment → (8) CI lockfile and vendor:publish updates → (9) rollout with the pinned branch retained as rollback.

Operational Impact

• Maintenance. Unchanged package count (five) and unchanged tracking burden; pollora:doctor and Site Health now cover two additional misconfigurations, so the pre-deploy checklist grows slightly and gets cheaper. Version drift across the framework/package matrix remains the standing maintenance tax.
• Support. Two runbook items change: the admin URL printed by pollora:install now resolves under Valet/Herd (update any doc that tells people to hand-edit it), and "site 404s but files are fine" now has a first-line answer — check the document root, then Site Health's .env finding. The new failure text ("point the document root to public/") is good; capture it verbatim in the runbook. Scheme-less APP_URL should be added to the onboarding checklist rather than left to the doctor warning.
• Scaling. No runtime scaling change. The Site Health .env probe is an extra HTTP request on a rarely-loaded admin page — negligible, but confirm it is not on a hot path.
• Failure modes.
  • Silent: query result-set changes from where()/orWhere() grouping, inclusive dates, 24-hour clock — wrong content served, no error. Highest severity. (unchanged)
  • Silent, new: a scheme-less APP_URL in staging or production is coerced to http:// — HTTPS assets, cookies and canonical URLs degrade with no error, only a doctor warning.
  • Loud: QueryException from fields(), userPermission() or orderBy() direction that was previously ignored — a working page starts 500-ing. (unchanged)
  • Boot-time: class-not-found from the Infrastructure\Laravel namespace moves in app or third-party code. (unchanged)
  • Asset-time: unregistered AssetFile resolver or unpublished block-bindings.js → missing build notice or missing editor behaviour. (unchanged)
  • Skew: contract mismatch across the framework/package boundary after a partial composer update. (unchanged)
  • Routing, new: the widened "public/ directory with an index.php is served directly" rule and the included-front-controller heuristic change dispatch — smoke-test subdirectory installs and non-standard docroots rather than assuming the Valet/Herd fix is inert elsewhere.
  • Diagnostic, new: Site Health .env probe false-positives/negatives behind catch-all routing, WAFs or basic auth — a red finding is not proof of exposure, and a green one is not proof of safety.
  • Removed by this release: endless self-redirect on Valet/Herd home pages, /wp-admin/ 404s, /cms/wp-admin/ 404s, and total Artisan failure from a scheme-less APP_URL. Good hygiene wins — credit them.
  • Test-only: deferred enqueue after application destruction (fixed in 13.36.1).
• Ramp-up. Low for teams on the public surface — the release is output-preserving and this patch set is configuration-facing. Medium for teams that extended internals (custom binding sources, custom meta UI drivers, custom asset containers): they must still learn MethodInvokerInterface, BindingEventsInterface, PostFinderInterface, the three asset contracts and PSR-11 in place of app() — roughly half a day per subsystem touched, plus a dedicated query-semantics audit before unpinning pollora/query. No additional ramp-up for v13.38.1 beyond the APP_URL/docroot checklist.