Discriminator Map Bundle Laravel Package

Getting Started

1. Install: composer require <vendor>/<package> — the 1.0.x line has no breaking changes across patches, so ^1.0 is a safe constraint.
2. Read the README first. The v1.0.4 release refreshed it; the install section now reflects the current config-publishing workflow. Check the README's "Configuration" block before touching config/*.php — the package validates its config against a schema, so guessing keys produces a hard failure rather than a silent default.
3. Publish the config: php artisan vendor:publish --provider="Vendor\Package\PackageServiceProvider" --tag=config. The published file is the contract — every key in it is validated by a Symfony TreeBuilder definition, and unknown keys are rejected at resolution time.
4. Locate the entry point. Open the service provider and look for mergeConfigFrom() and the container binding. Whatever the provider binds (a manager, a client, a repository) is what you should type-hint — not the concrete class.
5. First use case: set the minimum required keys in config/<package>.php, then resolve the bound contract from the container in a tinker session (app(\Vendor\Package\Contracts\...::class)) to confirm the config passes schema validation before wiring it into a job or controller.

Implementation Patterns

Config as the single source of truth. Because config is schema-validated, treat the published file as the API surface. Prefer editing the published config over passing constructor arguments — the schema definition is where defaults and required keys live, and it stays consistent with what the package actually reads.

Merge, don't duplicate. The provider uses mergeConfigFrom(), so your published file only needs the keys you actually change. This keeps upgrades cheap: when a new version adds a config key, you get the package default without republishing.

Environment-specific overrides. Keep secrets in .env and reference them from config ('key' => env('PACKAGE_KEY')). Never call env() outside config files — with config:cache the call returns null.

Container binding over static calls. Resolve the bound contract via constructor injection. This makes the package swappable in tests and lets you bind a fake in a service provider for integration tests.

Testing pattern. Override config per-test with config(['package.key' => 'value']) in setUp(), or use Config::set() inside the test. If the package resolves config at construction time, re-resolve from the container after changing config ($this->app->forgetInstance(...)), otherwise you'll assert against a stale singleton.

Bootstrapping validation in CI. Since the config is validated on resolution, add a smoke test that resolves the package's main binding with the default published config. That catches schema drift on upgrade without needing a full feature test.

Gotchas and Tips

The 1.0.4 deprecation fix. Prior to 1.0.4, the package's config definition triggered Symfony\Component\Config\Definition\Builder\TreeBuilder::root() deprecation notices on newer Symfony Config releases (the root() method's signature/usage was deprecated in favour of defining the root node explicitly). If your test suite runs with convertDeprecationsToExceptions="true" (PHPUnit 10+ default) or you surface deprecations via Log::deprecations(), this was likely breaking CI on an otherwise unrelated dependency bump. Upgrade to 1.0.4 — no code changes needed.

Watch the transitive Symfony version. The fix targets modern symfony/config. On older Symfony Config versions still pulled in by a legacy dependency, you may see different behaviour. Run composer why symfony/config if the deprecation persists after upgrading, and check that a second package isn't pinning an older major.

Config cache invalidation. php artisan config:cache snapshots the validated config. After changing the published file locally or in a deploy, run php artisan config:clear — otherwise you'll debug a problem that no longer exists in the file.

Schema failures are loud and early. Unknown or malformed keys throw during resolution, not at boot, so a broken config may only surface the first time a request hits a code path that resolves the package. If you need earlier feedback, resolve the binding in a php artisan about-style command or a health check.

Publishing after an upgrade. Patch releases can add config keys. Compare vendor/<vendor>/<package>/config/<package>.php against your published copy after upgrading; the package default is applied via merge, but any key you've removed from your published file reverts to the package default rather than staying absent.

Extension point. If the package's schema doesn't cover your case, don't append arbitrary keys — the tree definition will reject them. Instead look for a documented extension hook (a driver/strategy interface or an extend()-style method on the manager), or bind your own implementation of the contract in a service provider registered after the package's.

Debugging config resolution. config('package') shows the merged result, which is what the schema validates. When an exception names a node path, compare that path to the published file first, then to the vendor default — mismatches almost always come from a stale published copy.