Wncms Core Laravel Package

Getting Started

Treat v6.7.0 as a fresh-install baseline, not an in-place upgrade target. The release is explicitly scoped to new installations on PHP 8.4+ / Laravel 13, and is built from the v6.3.8 codebase rather than the most recent v6 line — so version numbers do not imply a linear feature progression.

First steps:

1. Confirm your platform can take it. Check composer.json (php, laravel/framework) before composer require. On Laravel 11/12 or PHP < 8.4 you cannot adopt v6.7.0; stay pinned to your existing 6.3.x constraint and treat this release as unavailable to you.
2. Pin explicitly. Use an exact or tilde constraint ("^6.7.0" only if you have verified the tag) rather than a floating *, because the v6 line contains divergent branches (6.3.8-derived vs. later) and a loose constraint can silently move you between them.
3. Verify the artifact before installing. The release notes call out a package archive fix and reference a reviewed candidate checked in an isolated Docker build. Mirror that: install into a throwaway container or fresh laravel new project first, inspect the extracted vendor/ tree, and only then roll it into anything real.
4. Run the installer once, then close it. Start with a single fresh project, complete the install flow end to end, and observe what it writes (.env, config, storage, database) before repeating anywhere else.

First use case: a brand-new Laravel 13 project on PHP 8.4 where you use the package's installer to bootstrap credentials and environment configuration, then immediately disable the installer surface.

Implementation Patterns

Installer-as-one-shot, not installer-as-feature. The credential handling changes in this release reinforce that the installer is a bootstrapping tool. A workable workflow:

• Gate the installer routes behind an env flag (e.g. INSTALLER_ENABLED=true) and a non-production check in a service provider or route file.
• Run the flow, capture the generated admin credential out-of-band (password manager / secrets store), then flip the flag off and redeploy.
• Keep the installer's route registration in a conditional middleware/route group so that "installer disabled" means the routes 404 rather than merely validate.

Credential handling. Since this release touches installer credential handling, avoid any pattern where the installer mints a credential you don't control. Prefer a flow where you supply the initial admin email/password via environment at install time, or where the installer emits a one-time token you immediately exchange and rotate. Never let a generated credential land in version control — check .env.example vs .env and confirm .env is gitignored before you start.

Environment encoding discipline. The env-encoding fixes are a hint about real-world breakage. Standardise:

• UTF-8 without BOM for .env and .env.example; add an editor/CI check if your team edits these on Windows.
• LF line endings in committed env templates.
• Quote values containing #, spaces, or $, and prefer base64 or single-quoted strings for secrets with special characters.
• If you template env files per environment (CI, Docker entrypoints), generate them from a validated source rather than string-concatenating.

Fronting the installer behind a proxy, CDN, or tunnel. The CSRF fixes are relevant here. If the installer POSTs fail with a 419 behind a load balancer or ngrok-style tunnel, the cause is usually a session/domain or cookie mismatch rather than a package bug. Configure trusted proxies, SESSION_DOMAIN, SESSION_SECURE_COOKIE, and a stable APP_URL that matches the URL you actually browse.

Integration into a provisioning pipeline. The most leverage comes from wrapping the installer in your own artisan command or CI job that: writes env from secrets, invokes the install steps non-interactively, asserts expected rows/credentials exist, and then disables the installer. That gives you idempotency the raw installer won't provide.

Archive integrity in CI. Add composer validate --strict, composer audit, and a lockfile diff check to the pipeline. Because the release notes distinguish "reviewed candidate" from "published archive", treat dist archives as something to verify, not assume.

Gotchas and Tips

• v6.7.0 does not remediate an already-compromised installation. The notes are explicit: existing compromised installs require separate cleanup, and this release does not remove files outside the package. If you have any reason to suspect a prior install, upgrading is not the fix — you need an audit: diff public/, bootstrap/, config/, and vendor/ against a clean skeleton, grep for unexpected eval/base64_decode/assert and obfuscated payloads, inspect web-server access logs for odd POSTs, review composer.lock and any repositories overrides, and rotate APP_KEY, database credentials, mail credentials, and all admin passwords. Assume persistence outside the package directory.
• Version numbering is misleading. "v6.7.0" is derived from v6.3.8, so changelogs and commit history above 6.3.8 may not apply. Read the tag's actual diff, not the release prose, when deciding whether a given fix affects you.
• Do not upgrade in place on an existing install. New-installation releases frequently assume an empty database and absent env file. Upgrading over a populated install risks credential overwrite. Provision a new environment, install, then migrate data deliberately.
• 419 on installer POSTs — check CSRF token presence in the form, session driver (file/database both fine, but array is not), cookie domain, and whether a reverse proxy is stripping cookies. Also confirm you aren't caching the installer page.
• Env parse failures look like config failures. A stray BOM or CRLF in .env can produce null config values that surface as confusing auth or database errors far from the cause. Run php artisan config:clear and dump the parsed value when debugging.
• Clear config cache after any installer run. config:cache during an install writes stale values; php artisan optimize:clear afterwards prevents a whole class of "it works in tinker, not in the browser" issues.
• Extension points to prefer: publishable config (vendor:publish --tag=...) and package events/commands over editing vendor files. Anything you patch in vendor/ is lost on the next composer update and won't survive the archive-integrity checks you should be running.
• Lock the installer down post-install in code, not just by memory. A short feature test asserting the installer route returns 404 when disabled is cheap insurance against a future deploy re-enabling it via env drift.