Flare Bundle Laravel Package

Getting Started

v3.1.1 is a small additive release: it enables contrib recipes — community-published recipe definitions, not just the bundled/official ones. Nothing is renamed or removed, so upgrading from 3.1.0 is a composer update away.

Start here:

1. Install/upgrade

   composer require <vendor>/<package>:^3.1
   php artisan vendor:publish --tag=<package>-config   # if you haven't already
   

   The service provider is auto-discovered; no manual registration needed on Laravel 10/11.

2. Find the config first. Look for the recipes / sources key in config/<package>.php. That is where official vs. contrib sources are declared, and it's the file you'll touch most often.

3. Discover what's available.

   php artisan recipe:list
   php artisan recipe:list --source=contrib
   

4. First real use case: replace a hand-rolled scaffold with a recipe. Instead of copy-pasting a starter (auth flow, admin panel, API skeleton) into a new app, install a contrib recipe and let the package write the files, merge config, and register providers:

   php artisan recipe:install vendor/recipe-name
   

Implementation Patterns

Pin contrib sources explicitly. Don't rely on an implicit "latest contrib" lookup in production tooling. Declare the source (Git URL, registry, or local path) in config and pin a tag/commit so recipe:install is reproducible across machines and CI.

Base recipe + contrib overlay. A common day-to-day pattern is a private "house" recipe that establishes your conventions (strict types, Pint config, Pest setup), then a contrib recipe layered on top for the specific feature. Apply in order; the package's file-conflict handling determines who wins — verify with --dry-run before trusting it.

Fresh-app CI job. In CI, spin up a throwaway Laravel app, install your pinned recipes, then run the test suite and php artisan about. This catches the real failure mode of recipes: they drift out of sync with newer Laravel skeleton versions.

Recipe application as a reviewable diff. Apply recipes on a clean branch and commit the result as a single commit. That makes contrib recipe contents reviewable in PRs — essential, since contrib recipes are third-party code.

Local contrib source for in-house recipes. Point the source config at a path repository during development and iterate without publishing. This is the fastest loop for authoring your own contrib recipes.

Gotchas and Tips

• Contrib recipes are untrusted third-party input. They can write files, merge config, and register providers. Treat recipe:install from a contrib source with the same scrutiny as composer require from an unknown vendor — read the recipe definition, pin the commit, and review the generated diff before merging.
• Name collisions. A contrib recipe can share a name with an official one. Always qualify by source (--source=contrib) and confirm which one resolved via -v. Post-3.1.1 ambiguity here is the most likely source of "it installed the wrong thing."
• Version skew. Contrib recipes target specific Laravel/package versions. A recipe that assumes Laravel 11 structure will silently produce broken code on 10. Check the recipe's declared constraints before applying.
• Overwrites are quiet. Back up or be on a clean git branch. If there's a --force/--dry-run flag, make --dry-run your default habit — it's the cheapest debugging tool you have.
• Clear caches after applying. Recipes that write config or register providers won't take effect until php artisan config:clear (and optimize:clear in deployed environments).
• Extension points: the source registry in config, custom recipe repositories (for private registries), and any pre/post-apply events the package dispatches. Hook the events if you need to run formatters or codemods after a recipe lands.
• Debugging a failed apply: re-run with -vvv, then inspect the recipe definition itself — failures are usually a missing target file the recipe expected to exist, not a bug in the package.