Faq Bundle Laravel Package

Getting Started

v0.1 is the first public release, and its changelog contains no feature list, no upgrade notes, and no deprecation notices. Treat it as an unvetted 0.x package until you've read the source yourself.

1. Pin it exactly. With no changelog detail and a 0.x version, assume breaking changes are permitted in any minor bump:

   composer require <vendor>/<package>:0.1.*
   

   Commit composer.lock. Do not use ^0.1 in a project you can't afford to patch quickly.
2. Read these first, in order: composer.json (PHP/Laravel constraints, autoload, dependencies), README.md, then src/ — the surface area of a v0.1 is usually small enough to read end to end in one sitting.
3. Check the test suite exists and passes before trusting anything:

   vendor/bin/phpunit --testsuite=<package>
   

   No tests on a 0.1 release is normal but should downgrade your confidence accordingly.
4. First use case: pick one non-critical, easily reversible integration — a single read-only query path, an admin-only screen, or a queued job — and prove it end to end before wiring it into anything user-facing.

Implementation Patterns

Wrap it behind your own boundary. The single most valuable pattern for an unproven 0.x dependency is an adapter you control:

• Define a small interface in your domain (ReportExporter, PaymentGateway, etc.).
• Implement it with the package in one class.
• Bind it in a service provider and resolve the interface everywhere else.

If v0.2 breaks the API, you rewrite one class instead of grepping the codebase.

Bind configuration through config/. Publish the package config (if it ships one) and reference only your own config keys in application code. Package-level config keys are the most likely thing to be renamed between 0.x releases.

Isolate the service provider. If the package supports Laravel auto-discovery, let it register, but keep any manual register()/boot() customisation in your own provider so you can see exactly what you changed when you upgrade.

Test at the seam, not through the package. Write contract tests against your adapter interface. When you bump the version, those tests tell you whether behaviour changed without you having to read the diff.

Canary the rollout. For anything touching money, auth, or persisted data, ship behind a feature flag or a config switch so you can disable the package path without a deploy.

Track upstream deliberately. Subscribe to the repo's releases. For a 0.x package this is not optional — there is no semver safety net.

Gotchas and Tips

• No upgrade guide exists yet. v0.1 is the baseline; there is nothing to diff against. Record the exact version you adopted (in composer.json and in your team docs) so the next release is diffable.
• 0.x semver semantics. 0.1.x → 0.2.0 may contain breaking changes by design. Read every changelog before bumping; don't let composer update do it silently in CI.
• PHP/Laravel constraint surprises. Check the package's require block against your supported matrix. Initial releases often target the newest Laravel only, which will block you on an LTS project.
• Auto-discovery failures are silent-ish. If the package's provider isn't discovered (wrong extra.laravel key, cached config), you get opaque "class not found"/"target not instantiable" errors. Run php artisan config:clear and php artisan package:discover when debugging boot issues.
• Facade aliases vs. real classes. If the package ships facades, prefer injecting the underlying class in your adapter — facades are harder to mock and more likely to be restructured.
• Check for global side effects on boot. New packages sometimes register middleware, publish migrations, or add routes unconditionally. Inspect boot() for anything that runs on every request.
• Unpublished migrations. Run php artisan vendor:publish --tag=<package>-migrations (tag name varies) and read the migration before running it — column types and index choices in a 0.1 release are rarely battle-tested.
• Extension points are unstable. Events, macros, and custom drivers are the most likely thing to change shape between 0.x versions. If you hook one, comment why and link the release you depended on.
• Exit criteria. Decide up front what would make you drop the package (no release in 6 months, a breaking change you can't absorb, a security advisory). Write it down while adoption is still cheap.