Sphinx Search Propel Bundle Laravel Package

Getting Started

This is the first tagged release (v1.0.0), so there is no upgrade path to follow and no prior assessment to reconcile against — treat adoption as a green-field evaluation rather than a migration.

• Install and inspect first. Run composer require into a scratch Laravel app, then immediately read the package's composer.json (Laravel and PHP version constraints, autoload type, whether the service provider is registered under extra.laravel.providers) and the README. With a 1.0.0 and a one-line changelog, the composer constraints and the service provider are the source of truth for what the package actually supports.
• Confirm discovery. Run php artisan about and php artisan package:discover to verify the provider is auto-discovered (or deliberately not). If there is a publishable config, php artisan vendor:publish --tag=... it in the same commit so the defaults are visible in review.
• First use case. Exercise the package's public surface from a single throwaway route or a php artisan tinker session before wiring it into anything real. At 1.0.0 you are validating that the documented happy path works on your Laravel/PHP versions, not just the author's CI.

Implementation Patterns

• Wrap the package behind a thin adapter. Bind a small interface in your own service provider and let one class own all calls into the package. At a first major release the public API is still settling; the adapter is what stops a 1.x minor from rippling through your codebase.
• Prefer constructor injection over facades for anything testable. Keep facade usage confined to blade/UI edges.
• Drive configuration from config files, not literals. Publish the config and override per environment; keep secrets in .env and reference them via env() only inside config/.
• Gate adoption behind a feature flag. For a first release, register the provider unconditionally but guard actual usage (routes, listeners, jobs) behind a config boolean so you can turn it off without a deploy rollback.
• Write contract tests around the adapter, not the package internals. Assert behaviour you depend on; that suite is your early-warning system when 1.1.0 lands.
• Integration tip: if the package dispatches events, log them in a staging listener for a week. First releases often over- or under-fire events, and the event log is the cheapest way to catch it before users do.

Gotchas and Tips

• A 1.0.0 is not a stability promise. Expect the API to move in 1.x minors. Use a caret constraint, commit the lock file, and subscribe to the changelog/releases feed — the one-line "First version" note tells you the author is not verbose, so read diffs.
• Config caching bites first releases. If config/*.php is merged but not published, php artisan config:cache will freeze defaults and confuse local debugging. Publish before caching, and clear config after every package update.
• Auto-discovery can be disabled in some environments (composer.json extra.laravel.dont-discover). If bindings are missing in one environment but present in another, check discovery before you debug the container.
• Version matrix is the most likely blocker. First releases frequently lag the newest Laravel or PHP minor. Verify against the constraints in composer.json rather than assuming the README is current.
• Debugging ladder: composer show -t for the dependency tree, php artisan about for provider/config state, php artisan vendor:publish --list to confirm tags exist, and php artisan tinker to poke the container binding directly.
• Extension points to check while the API is small: service provider bindings/singletons, published config, events, and any macroable classes. Note which are marked @internal — everything internal at 1.0.0 should be assumed to change without a major bump.
• Pin and watch. Until a 1.1 with a real changelog appears, treat every release as potentially breaking and review the diff before merging.