Business Logic Bundle Laravel Package

Getting Started

• Update the package (composer update) and confirm the new generators are registered by running php artisan list make. You should see make:specification and make:rule alongside the existing makers.
• If your app caches the container/manifest in CI or production, re-run php artisan package:discover (or composer dump-autoload) after the upgrade — new maker commands are registered through the service provider and won't appear until discovery re-runs.
• Look first at the package's config/ file (maker namespaces/paths) and its stubs/ directory. Those two places tell you where generated classes land and what they look like before you commit to the pattern.
• First use case: scaffold your first business rule pair.
  • php artisan make:specification ActiveSubscriptionSpecification for a reusable, composable domain predicate.
  • php artisan make:rule EligibilityRule for a Laravel validation rule object consumed by a FormRequest.
• Read the generated files immediately — they encode the package's intended contract (method signatures, return types, namespace conventions). Treat them as the canonical example rather than the README.

Implementation Patterns

• Specification for domain predicates. Generate one specification per business concept (ActiveSubscription, WithinSpendLimit), keep them side-effect free, and compose them rather than branching in controllers or services. This is the pattern that pays off fastest: specifications become the single source of truth reused by policies, queries, and validation.
• Rule objects for request-level validation. Use make:rule to produce ValidationRule implementations, then reference them from FormRequests via new EligibilityRule($tenant). Keep rules thin — inject or delegate to a specification so the same logic isn't duplicated in two dialects.
• Bridge the two. A common workflow is specification → thin rule adapter. Generate the specification first, write the logic there, then generate the rule and have validate() call isSatisfiedBy(). This keeps rules testable in isolation and reusable outside HTTP.
• Pair every generated class with a test. Generate the class, then immediately create the matching unit test. Specifications are pure and trivially testable with data providers; rules deserve one test per failure message so you don't regress user-facing error text.
• Namespacing per bounded context. If the config supports per-maker namespaces, point specifications at App\Domain\...\Specifications and rules at App\Rules. Doing this on day one avoids a later rename sweep.
• Scaffold in bulk for a new module. When introducing a feature, generate the full set (specifications, rules, plus the pre-existing makers) in one pass, then fill in logic. The generators are cheap; the consistency is the value.

Gotchas and Tips

• Name collision with Laravel's built-in make:rule. Laravel ships its own make:rule. Depending on registration order, one wins. Verify which stub you actually got by diffing the generated file, and prefer the fully-qualified command form if the package namespaces its commands.
• Stale command list after upgrade. The single most common "the feature doesn't exist" report is a cached manifest. php artisan optimize:clear before filing a bug — especially in Docker/CI images built from a layer cache.
• Generated ≠ configured. Makers that resolve target paths from config will silently fall back to a default namespace if your config was published before 1.1.0. Re-publish or diff the config file to pick up new maker entries.
• Stub drift on upgrade. If you published stubs to customise them, new releases won't update them. The new makers may ship stubs with signatures your old published stubs don't match — check for void return types on validation rules (required in Laravel 10+) and typed parameters.
• Rules are stateful; specifications should not be. A rule instantiated with constructor dependencies per-request is fine. A specification holding mutable state will break composition — keep isSatisfiedBy() referentially transparent.
• Extension points: the maker base class and the stub files are the intended seams. Subclass a maker to change the generated namespace or add a --test flag, and register it in the service provider rather than editing vendor files.
• Debugging generators: run with -v to see the resolved target path. If a file is created in an unexpected directory, the cause is almost always the config path value, not the maker.
• Don't over-generate. These makers produce empty shells; a codebase with forty one-line specifications is worse than five real ones. Generate when you have a second caller in sight.