Eloquent Unique Attributes Laravel Package

Getting Started

This is the initial public release (v0.1.0). The release notes contain only "Initial Release" — no changelog entries, deprecations, or migration notes — so treat everything below as the discovery checklist for a brand-new, unreviewed package rather than a description of known behaviour.

First steps, in order:

1. Install and pin. composer require <vendor>/<package>:0.1.* and commit the lockfile. Do not use a floating constraint on a 0.x package.
2. Read the source of truth, not the tagline. In the repo, look at composer.json (Laravel version support, extra.laravel.providers / aliases for auto-discovery, PHP constraint), then src/ for the service provider, then the tests/ directory. Test files are usually the most accurate documentation a 0.1.0 has.
3. Check what is publishable. php artisan vendor:publish --provider="Vendor\Package\PackageServiceProvider" (add --tag= once you know the tags). If there is a config file, publish it before writing any integration code — retrofitting config paths later is painful.
4. Confirm registration. php artisan about and a quick app()->bound('...') check in tinker will tell you whether auto-discovery worked on your Laravel version, or whether you need to register the provider manually in bootstrap/providers.php (Laravel 11+) or config/app.php (older).

First use case: pick the smallest, most reversible integration point in your app — one job, one controller action, or one console command — and call the package from there. At 0.1.0 the goal of the first integration is to learn the package's shape and failure modes, not to make it load-bearing.

Implementation Patterns

Resolve through the container, never new. Laravel packages almost always bind their core object in the service provider. Inject the interface/class into constructors or resolve via app(). If you construct it manually you will bypass whatever config and dependencies the provider wires up, and you will break the day the constructor signature changes.

Wrap it in a thin adapter. Create one small class in your app (e.g. App\Support\XyzClient) that owns every call into the package, and let the rest of your codebase depend on that. This is the single highest-value pattern for a 0.x dependency: when v0.2.0 renames or re-signatures something, you fix one file instead of grepping the codebase.

Config-first, hardcode-never. Read package behaviour from config/<package>.php and set environment-specific values in .env. Credentials and endpoints belong in env vars referenced by the config file, not inline in service classes.

Feature-flag the integration. Put the call behind a config flag or Laravel Pennant feature so you can disable it in production without a deploy. At 0.1.0 you have no track record of how the package behaves under load, on queue workers, or against malformed input.

Testing integration:

• If the package ships fakes or a ::fake() helper, use them — it's a strong signal of quality and keeps tests fast.
• If not, bind a mock or stub of the container key in your test's setUp() rather than hitting the real dependency.
• Add one contract test per integration point that asserts the shape of what the package returns (types, nullability, exception classes). That test is what will catch a breaking change on the next bump.

Queues and long-running processes. If you call the package from a job, verify it survives queue:work restarts and doesn't hold stale state between jobs. Resolve inside handle(), not in the constructor, if the object is stateful.

Version pinning and upgrade cadence. Pin to ~0.1.0. Read the diff between tags yourself before bumping — at 0.x the release notes are frequently thinner than the actual change.

Gotchas and Tips

• 0.x semver is not stable. By convention, a minor bump (0.1 → 0.2) may contain breaking changes. Do not let Dependabot or Renovate auto-merge minor bumps for this package; require a human review of the diff.
• There is no upgrade guide yet. For v0.1.0 that's expected, but it also means the burden of detecting breakage is entirely on your tests. Budget for that.
• Config caching bites first. After publishing config or changing env values: php artisan config:clear locally, and remember that config:cache in production freezes the config file — a package that reads env() outside its config file will silently return null once cached. This is a common 0.1.0 bug and worth checking in the source before you deploy.
• Auto-discovery is version-dependent. Packages declaring extra.laravel.providers are auto-registered; ones that only document manual registration will appear to "do nothing" until you add the provider yourself. If container resolution fails with a "target not instantiable" error, check this first.
• Publish tag collisions. Generic tags like config or views can collide with other packages. Always publish with the package-specific tag.
• Facade vs injection. If the package offers a facade with a short alias, prefer injection for testability; use the facade only where injection is impractical. Facade aliases registered globally can also clash with your own classes — check config/app.php aliases.
• Debugging checklist: php artisan about (provider list), app()->bound($key) in tinker, php artisan vendor:publish --provider=... --tag=..., and composer show <vendor>/<package> to confirm the installed version matches what you think.
• Extension points to look for in the provider: singleton/bind calls (what can you swap?), interfaces published in src/Contracts (what can you implement?), and any macroable or event dispatching (hooks without forking). If none exist, your adapter wrapper is the extension point.
• Report early. At 0.1.0, upstream is most responsive. File issues for anything you had to work around — those workarounds are the most likely thing to become tech debt.