Oswis Web Bundle Laravel Package

Getting Started

Reality check before anything else: this is a Symfony bundle, not a Laravel package. The install footprint is config/bundles.php registration, a DI extension, XML/YAML service definitions, Doctrine entities, and Twig templates. There is no service provider, no publishable config, no migrations, no facades, and no framework contracts your Laravel app recognises. composer require oswis-org/oswis-web-bundle into a Laravel project will succeed and then do nothing — the bundle is never booted because Laravel has no kernel-registered bundle list.

So "getting started" for a Laravel team splits two ways:

Path A — you actually need this capability in a Laravel app. Start with a one-hour spike in a throwaway Symfony skeleton, not in your Laravel repo:

1. composer create-project symfony/skeleton oswis-probe && cd oswis-probe
2. composer require oswis-org/oswis-web-bundle
3. Register in config/bundles.php: OswisWebBundle::class => ['all' => true]
4. Import the bundle routing in config/routes.yaml
5. bin/console config:dump-reference oswis_web — this is where you learn the config tree, because it isn't documented in the README
6. bin/console debug:router, debug:container | grep oswis, and open a browser

You are not doing this to use the package. You are doing it to read the domain model, decide whether it's worth porting, and produce a defensible go/no-go.

Path B — you're evaluating whether to port. Read, in this order: the bundle class, DependencyInjection/Configuration.php (the real config contract), Entity/ (this is the data model you'd port to Eloquent), Controller/ + routing (your route map), and Resources/views/ (your Blade conversion list). That's your port estimate, and it's probably the most valuable artefact you'll get out of this dependency.

Implementation Patterns

The only pattern that reliably works in a Laravel codebase is the port, not the bridge. There is no maintained Laravel adapter and 0 dependents on Packagist means nobody has built one you can lean on. Plan for a one-off translation: Doctrine entities → Laravel migrations + Eloquent models, Symfony controllers → invokable Laravel controllers, Twig templates → Blade, bundle config → config/oswis.php. Do it in a branch, commit it as your own code, and drop the dependency. The result is a bounded cost you control instead of a pre-1.0 vendor you don't.

If you stay on Symfony (or bridge via a service boundary), the supported patterns are:

• Template override — Symfony resolves templates/bundles/<BundleName>/ before the bundle's own views. Copy and edit; never edit vendor/.
• Route override — declare a route with the same name earlier in config/routes.yaml to replace a shipped controller's behaviour without touching the controller.
• Entity extension — extend the bundle's entities in your src/Entity/ and wire them with Doctrine's resolve_target_entities in doctrine.yaml, or use single-table inheritance. Never fork the bundle to add a column.
• Config extension — the bundle's DI extension exposes a config tree under whatever root key the bundle declares; that's your seam for wiring.
• Service decoration — controllers are services; decorate or replace them with a compiler pass rather than subclassing.
• Anti-corruption layer — if you truly need both stacks, run the Symfony app as a standalone service and talk to it over HTTP or a queue. Do not attempt to embed the bundle in Laravel's container.

Bridging workflow if you go the service route: pin the exact version, commit the lockfile, add the dependency to your review list, and wrap every call behind an interface you own so the swap is a contained refactor. Two version bumps without breakage is your continue/re-evaluate gate.

Gotchas and Tips

• The composer install is the trap. It succeeds against Laravel. Nothing warns you that nothing will boot. Write this into the spike report so the next engineer doesn't repeat it.
• Maturity signals are thin. Two stars, zero dependents, one release (2025-05-25), pre-1.0. Treat the public API as explicitly unstable, semver as inapplicable, and every minor bump as a potential breaking change. Acceptable for internal tooling; needs a deliberate, documented decision on a revenue path.
• No documented config tree. bin/console config:dump-reference oswis_web (adjust the root key) is your only reliable source of truth. Read Configuration.php alongside it.
• Doctrine coupling is the hidden cost of a port. You inherit the bundle's table names, column types, indexes, and migration ownership. Run bin/console doctrine:schema:validate before every bump, and diff the generated schema, not the entity code.
• Twig overrides pull whole parent chains. Overriding one template can silently change three others. Snapshot rendered HTML in a test before upgrading if you're on the Symfony path.
• Check for CI tests before you trust any bump. If there's no test suite, every release is a manual regression pass — budget it.
• Debugging tooling (Symfony): the profiler, debug:router, debug:container, and debug:event-dispatcher | grep oswis find 90% of integration problems. The bundle almost certainly hooks the Symfony event dispatcher, not Laravel's, so any event-based extension you write is not portable.
• The likely extension points are narrow: template overrides, route overrides, config tree, and service decoration. Anything deeper — controller logic, entity behaviour, query shape — means a fork, and a fork means you own the upgrade path forever. Prefer the port.
• The exit is genuinely cheap, and that's the point. MIT licence, readable entities, no hosted component, no proprietary glue. A port is a contained, one-time cost with no residuals. If the package isn't pulling its weight after two bumps, the right move is to finish the port and delete the dependency rather than keep absorbing migration cost.