Schema Context Bundle Laravel Package

Getting Started

First, a reality check on the framing. This is a Symfony bundle, not a Laravel package. In Laravel there is no bundle auto-registration, no config/bundles.php, and no Kernel::registerBundles(). With 1 star and 0 dependents, there is also no blog post, no Stack Overflow tag, and no community to fall back on. Budget your first hour for reading source in vendor/macpaw/schema-context-bundle, not for reading docs.

Minimal steps

1. composer require macpaw/schema-context-bundle — then immediately inspect vendor/macpaw/schema-context-bundle/composer.json for "type": "symfony-bundle" and its symfony/* constraints. Those constraints are your single biggest integration risk (see Gotchas).
2. Read three files in this order: src/*Bundle.php (the Bundle subclass — tells you what's registered), src/DependencyInjection/Configuration.php (the full config tree), and Resources/config/services.* (every service ID you could reuse). That trio is the real documentation.
3. Decide which half you want. You almost never want the bundle; you want the classes behind it. Instantiate them directly and bind them into Laravel's container:

// app/Providers/SchemaContextServiceProvider.php
public function register(): void
{
    $this->app->singleton(SchemaContext::class, function ($app) {
        return new SchemaContext(
            schema: config('schema-context.schema'),
            // ...construct with plain arrays, not Symfony container refs
        );
    });
}

First use case: pick the narrowest one — validate a single webhook or API payload against a schema in a FormRequest or a queued job, behind a thin wrapper class of your own. Do not start by wiring the whole bundle into the framework; prove the core class does something useful before you invest in plumbing.

Also: pin the version explicitly ("macpaw/schema-context-bundle": "1.x-dev#<sha>" or an exact tag) and commit the lock file. A package with this little traffic can be re-tagged or force-pushed without anyone noticing.

Implementation Patterns

Adapter-first architecture. Wrap whatever the bundle exposes in a single first-party class (App\Schema\SchemaContext) and reference only that class from application code. The bundle becomes an implementation detail you can delete in an afternoon. Given the abandonment risk, this is not optional hygiene — it's the whole strategy.

Translate the semantic config into Laravel config. The bundle's config tree lives in DependencyInjection/Configuration.php. Mirror it as config/schema-context.php with env()-driven values, and let your service provider map your flat array onto whatever shape the bundle's services expect. Publish it with php artisan vendor:publish --provider=... so it's discoverable.

Use it at the edges, not in the domain. The two integration points that pay off:

• Inbound: a custom validation rule or FormRequest::rules() that delegates to the schema check, so failures surface as normal ValidationExceptions with 422 responses rather than a bundle-specific exception leaking out.
• Outbound: a JsonResource or response macro that normalises payloads against the same schema, so request and response shape can't drift.

Validator::extend('schema', function ($attribute, $value, $params) {
    return app(SchemaContext::class)->conforms($value);
});

Bridge events manually if needed. If the bundle ships an event subscriber, don't fight Laravel's dispatcher to make it fire. Register the subscriber class yourself and call its handler from a Laravel listener — or just call the handler directly. Symfony's EventDispatcherInterface and Laravel's Dispatcher are compatible enough in shape but not in wiring.

Replicate compiler passes as an explicit registry. Bundles often collect services by tag via a CompilerPass. Outside Symfony that machinery never runs, so you get an empty collection and a confusing "no schemas registered" error. Replace it with a Laravel TaggedServices-style registry or a plain config array, and register your schemas there deliberately.

A console command is the best week-one deliverable. php artisan schema:list / schema:show {name} that dumps what the context currently resolves. It's a 30-line command that turns a black box into something debuggable, and it doubles as onboarding material for the rest of the team.

Test against the wrapper, not the bundle. Unit-test your adapter with a fake; keep exactly one integration test that exercises the real class, so an upstream breakage fails one test instead of fifty.

Gotchas and Tips

The number one failure mode is Composer, not code. Laravel 10/11 pull symfony/* at 6.x/7.x. If this bundle requires ^5.4 (plausible for a low-traffic MacPaw bundle), you'll get a resolution conflict, not a runtime error. Run composer why-not macpaw/schema-context-bundle and check whether the conflicting package is a Laravel core dependency before you spend an hour on it. If it conflicts, stop — the fork cost is lower.

FrameworkBundle absence causes weird failures. Some code paths do class_exists(FrameworkBundle::class) or rely on Symfony's Kernel being booted. If you hit a ClassNotFoundError from deep inside the vendor tree, don't chase it — you've found a spot where the bundle genuinely requires a Symfony runtime and you need to bypass that code path entirely.

Config typos fail silently. Symfony's semantic config validates and rejects unknown keys with a helpful InvalidConfigurationException. Your flat Laravel array does not. A misspelled key becomes null, which becomes a default, which becomes a bug three layers away. Validate your own config array in the provider and fail loudly on unknown keys.

Cache invalidation is not yours. Bundles commonly cache compiled schema definitions to a filesystem path. php artisan optimize:clear will not touch it. Look for a cache_dir / cache config key, point it at storage_path('framework/schema-context'), and add it to your deploy's clear step. If you skip this, you'll ship a config change that appears to do nothing.

Debugging without Symfony's tooling. You don't have the profiler, debug:container, or debug:config. Your substitutes are dd() inside the vendor file (temporarily, on a branch), a Laravel log channel scoped to the wrapper, and the schema:list command above. Write the log line before you need it.

Tagged services and compiler passes are dead code here. If the README mentions tags like schema_context.provider, understand that nothing in Laravel collects them. Read the compiler pass to learn the intended ordering and semantics, then hard-code that ordering in your registry.

Treat it as vendored. With 0 dependents and 1 star, assume no upstream responsiveness. Fork it, use a path or VCS repository, and keep your diff minimal so you can rebase if a fix ever lands. Check composer audit — the MIT license is fine, but there's no evidence of a security policy or a maintainer on rotation.

Extension points worth knowing: the bundle's config tree (for toggling behaviour without code), its service IDs (for decoration — bind your own class over the vendor one in the container), and its event/subscriber hooks (for injecting validation or normalisation). Everything else — bundle bootstrapping, compiler passes, DI extensions — is Symfony scaffolding you should strip out rather than emulate.