Nebula Tools Laravel Package

Getting Started

This is a minor (2.1.0) release with no breaking changes signalled, so upgrading is low-risk: bump the constraint, run composer update, and re-run your existing setup flow to confirm nothing shifted. The substance of the release is in the new-website setup path, so that's where to spend your first ten minutes.

1. Upgrade and inspect the surface area first. Run php artisan list before and after the update and diff the output — the setup refinements may be exposed as new flags, a new command, or changed prompts rather than a new class. Then read the command class behind the setup entry point; the release notes are deliberately thin, so the diff is your actual documentation.
2. Look at the config and stubs. Setup processes almost always read from a published config file and a set of stub templates. Check config/ for anything new and run php artisan vendor:publish to see whether additional publishable groups appeared in this version.
3. Check the WP-CLI counterpart. The release explicitly tracks a matching WP-CLI package release. Confirm which version of that package this one expects — that pairing is the fastest way to reproduce the "similar improvements" locally and the most likely source of confusing behaviour if mismatched.
4. First use case: scaffold one site locally. In a throwaway Laravel app, run the setup flow end-to-end against a fresh directory, then immediately run it a second time. The second run is the real test: setup refinements usually mean better idempotency and clearer prompts, and you want to see that behaviour before you trust it in a pipeline.

Implementation Patterns

Treat setup as a repeatable command, not a one-time ritual. The value of these refinements is that new-site bootstrap becomes something you can script. Wire it into a project template or an internal artisan command so a new site is one invocation plus a config file, rather than a wiki page of manual steps.

Pin the pair. Because this package's setup logic is coupled to a specific WP-CLI package version, add both to composer.json with compatible constraints and let Composer resolve them together. If you maintain multiple sites, a shared base project (or a skeleton repo) is the cleanest way to keep the pair aligned.

Drive it non-interactively. For CI or container provisioning, check whether the setup command accepts flags to skip prompts — and prefer passing values explicitly over relying on defaults. If interactive prompts are unavoidable, wrap the command so the input is deterministic and failures are loud.

Separate "create" from "configure". If the flow lets you scaffold a site and then apply settings separately, keep them as distinct steps in your automation. That way a config change to an existing site doesn't risk re-running creation logic, and a failed configuration step doesn't leave you wondering whether the scaffold was touched.

Verify after setup rather than assuming. Add a post-setup smoke check — the expected directory structure, the config values actually written, and a successful boot of the site. Setup commands that "succeed" while leaving partial state are the classic failure mode here, and an explicit assertion turns a silent problem into a failing build.

Keep local and CI paths identical. If your local workflow uses the interactive defaults and CI passes flags, you're testing two different code paths. Pick one invocation shape and use it everywhere.

Gotchas and Tips

• The release notes are not the changelog. "Some refinements" tells you nothing about renamed flags, changed defaults, or reordered prompts. Diff the setup command and any changed stubs between tags before rolling this out to existing projects.
• Re-run before you trust. Setup improvements are often about idempotency and better error messages. Confirm by running setup twice on the same target and checking that the second run is a clean no-op, not a partial overwrite.
• Version skew with the WP-CLI package is the top suspect for any oddity after upgrading. If setup behaves differently than the notes imply, check the WP-CLI package version actually installed before debugging your own code.
• Watch for changed defaults. A "refinement" that alters a default value will silently change what new sites get while leaving existing sites untouched — a divergence that only shows up months later. Snapshot the generated config for one site pre- and post-upgrade and compare.
• Permissions and filesystem assumptions. Setup flows that write directories or copy stubs are sensitive to umask, container users, and read-only mounts. If setup works locally but fails in Docker or CI, look there first.
• Partial failure leaves debris. If setup dies halfway, you may have a half-created site that the next run won't clean up. Script your automation to start from a known-clean directory rather than retrying in place.
• Extension points to check: publishable stubs and config are usually the intended customisation surface — prefer overriding those over editing vendor files. If the setup command is bound in the container, that binding is also a legitimate override point for project-specific behaviour.
• Existing sites are not automatically migrated. This release targets new website setup. Don't assume improvements apply retroactively; if you want the new structure in an existing project, you'll likely need to re-scaffold or manually port the changes.