Symfony Fetch Table Laravel Package

Getting Started

Start with the resolver configuration, not the source. The package's surface area is small: a service provider registers resolvers, and each resolver carries a configuration array. Version 1.2.1 adds an optional querySelector key to that array, so the fastest orientation is:

1. composer require the package and let Laravel's package discovery register the provider (no manual config/app.php edit on Laravel 5.5+).
2. php artisan vendor:publish --tag=config (or the package's equivalent tag) and open the published config.
3. Read the resolver list top to bottom — resolution order is the whole behaviour of this package, and the new option slots into it as a per-resolver filter rather than a new resolution stage.

Where to look first: the published config file, then the resolver class shipped as the default. Every question you'll have ("why did this implementation get injected?") is answered by those two files plus the order of entries between them.

First use case: take a resolver you already have working, add querySelector to its configuration, and confirm the resolved concrete class changes without touching any constructor signature. That's the value proposition in one step — you gain container flexibility at the config layer, and call sites stay untouched. If your first attempt requires editing a class to see the difference, you've applied it at the wrong layer.

If you're evaluating rather than adopting, wire one non-critical binding through a querySelector-filtered resolver, run the test suite, and check the container's resolved-instance graph. That tells you more than the README does.

Implementation Patterns

Filtered candidate selection. The pattern querySelector enables is "many implementations registered, one selected by a predicate." Register all candidates normally, then let the resolver's selector pick among them:

'resolvers' => [
    \App\Contracts\PaymentGateway::class => [
        'resolver' => \Vendor\Package\Resolvers\TaggedResolver::class,
        'querySelector' => 'gateway.stripe',   // selector evaluated against candidates
    ],
],

The selector should be treated as data — a tag, a name, an attribute filter — not as a closure that reaches into application state. Selectors that read the request or the authenticated user turn your container configuration into runtime logic, and that's where the debugging pain starts.

Environment-split configuration. Because the selector lives in config, you can express environment differences declaratively instead of with if (app()->environment(...)) inside a service provider:

// config/resolvers.php
'querySelector' => env('PAYMENT_GATEWAY_SELECTOR', 'gateway.fake'),

This is the cleanest integration point for testing: the test suite sets the env var (or overrides config in setUp) and gets a deterministically selected implementation, with no container gymnastics per test.

Layered resolvers with a fallback. Where the package supports chaining, keep an unfiltered resolver as the last entry. A querySelector that matches nothing is a realistic outcome — new environment, config drift, a tag that only exists in staging — and the fallback is what turns that into a degraded-but-working application instead of a BindingResolutionException in production.

Contextual binding interplay. querySelector resolves which implementation; Laravel's contextual bindings decide where. They compose: use when(...)->needs(...) for genuinely local variations and reserve the selector for global choices. If you find yourself adding a selector per consumer, you wanted contextual binding.

Testing. Prefer $this->app->instance(Contract::class, new FakeGateway) in tests over manipulating selectors. Selector behaviour itself deserves two or three dedicated tests — one match, zero matches, multiple matches — asserting the resolved class, not the internals of the matching.

Gotchas and Tips

Config caching will bite you. Selectors read from config, so php artisan config:cache in a deploy means changes to the selector need a re-cache. The classic symptom: the selector works locally, does nothing in staging. Add config:clear to your local troubleshooting reflex before you debug the resolver itself.

Resolution order is implicit and unforgiving. With multiple candidates, the first match wins. Reordering the config array — which looks like a cosmetic diff in review — changes application behaviour. Keep candidate registration ordered intentionally and comment the ordering.

A no-match is silent until it isn't. Depending on configuration, an unmatched selector either falls back or throws deep inside the container, where the stack trace points at an unrelated constructor. When you see a baffling BindingResolutionException, check selector matches before you check bindings. Logging the selected concrete class once at boot in non-production pays for itself.

Don't put resolution in hot loops. Selector evaluation happens on resolution; resolved instances are shared, but code that calls app() repeatedly inside a loop re-enters the resolver path. Inject once via constructor and let the container do its job.

Upgrading to 1.2.1 is additive, but verify the shape. The querySelector option is new and optional, so existing configurations should be unaffected — no migration, no config restructure. Still confirm two things before rolling out: that the key is spelled identically in your config and the package's expectations (a silently ignored unknown key is the most common failure here, and it looks exactly like "the feature doesn't work"), and that any custom resolver classes you wrote extend a base class that hasn't gained an abstract method. If you maintain custom resolvers, this is the release to re-run their tests.

Extension points. A custom resolver is usually the right answer when a selector can't express your rule. Implement the package's resolver contract, register it as you would any other class, and keep the selection logic isolated — custom resolvers that also do instantiation are the ones that become untestable.

Debugging checklist, in order: is config cached? does the selector match anything? is the resolver ordered correctly? is a contextual binding overriding the result? That sequence resolves most reports, and it's worth writing into your team's runbook the first time you hit it.