Elastic Query Bundle Laravel Package

Getting Started

1. composer require <vendor>/<package> — v3.1.1 is a patch release on the 3.x line, so it is a drop-in upgrade for anyone already on ^3.0; no composer.json constraint changes are needed.
2. Publish the config and confirm the schema loads: php artisan vendor:publish --tag=<package>-config, then php artisan config:clear.
3. Verify the package's config tree builds cleanly in a tinker session (app(<Package>::class) or the bound contract) — this is the fastest smoke test, and it is exactly the code path touched by v3.1.1.
4. First real use case: define your application-specific options, publish them into config/<package>.php, and let the package's config builder validate them at boot so misconfiguration fails loudly instead of silently falling back to defaults.

Implementation Patterns

• Config-first setup. Register overrides in config/<package>.php and keep environment-specific values in .env. Because configuration is schema-validated, prefer adding options through the published config rather than mutating the package at runtime.
• Service container binding. Resolve the package via its contract/interface in constructors and jobs rather than app(...) facades; this keeps your code testable and insulated from internal class changes like the TreeBuilder return-type fix in v3.1.1.
• Boot-time validation. If you extend the package to add your own config nodes, extend the schema in a dedicated service provider's register() method (before config caching kicks in), not in boot().
• Feature tests. Use config([...]) overrides inside setUp() or per-test to exercise alternate configurations; combine with RefreshDatabase where the package persists state.
• Queued work. If the package resolves config at container-boot time, snapshot any derived settings into your job payloads or a config object so long-running workers do not drift when config changes mid-queue.

Gotchas and Tips

• v3.1.1 change. The release only removes a deprecated native TreeBuilder return type declaration (PHP 8.4 deprecation noise). There are no behaviour changes, no signature removals, and no config key changes. Upgrading from any 3.1.x is safe without code modification.
• If you subclass or decorate the tree builder, drop any : TreeBuilder return type from your overrides to match, and add a test that instantiates your subclass — the parent's declaration is now less specific.
• Run php artisan config:cache after upgrading in production; a stale cached config can mask the fix and keep surfacing deprecation notices from previous deploy artefacts.
• Deprecation notices are not errors — they appear in storage/logs/laravel.log and the deprecation channel only. Check php -v if you are seeing them; the fix targets PHP 8.4, so the notice will not appear at all below that version.
• Extension points. Prefer the documented contract/schema extension hooks over overriding the config builder class directly; those hooks are the ones covered by the package's own test suite and are the least likely to churn in future patch releases.
• Debugging misconfiguration. If config validation fails after the upgrade, compare your published config against the current stub with php artisan vendor:publish --tag=<package>-config --force in a throwaway branch — the diff usually reveals a renamed or newly-required key.