Fifreecorebundle Laravel Package

Getting Started

Read this before composer require: fi/fifreecorebundle is a Symfony bundle, not a Laravel package. The *Bundle suffix, vendor prefix fi (Comune di Firenze), and description ("Framework Fifree") all point at Symfony conventions — no ServiceProvider, no config/fifree.php, no Facade, no Illuminate\* references. If you paste it into a Laravel app the way you would a normal package, auto-discovery will not wire up a service provider because there likely isn't one to discover; you'll get a class that never boots. Plan accordingly.

Where to look first (in order):

1. composer.json — type, require (does it demand symfony/framework-bundle? symfony/http-kernel? a specific PHP floor?), autoload PSR-4 map, and extra.
2. LICENSE — Italian PAs commonly pick EUPL or AGPL. AGPL has direct implications for SaaS. Confirm before you write a single line of integration code.
3. src/ — look for a FifreeCoreBundle class extending Symfony\Component\HttpKernel\Bundle\Bundle. That tells you the actual runtime contract.
4. DependencyInjection/ — the Extension and Configuration classes reveal what services are registered and what config tree is expected.
5. README — expect Italian; expect it to describe the parent Fifree framework, not just this bundle.

First realistic use case: stand up a throwaway Symfony app (matching whatever Symfony version the package declares) and boot the bundle in isolation. That's your discovery spike. From there, decide whether you're going to (a) keep a Symfony microservice for this bounded context and call it over HTTP from Laravel, or (b) extract the domain classes you actually need into your own namespace. Do not attempt to bolt it into a Laravel kernel.

If you must stay in Laravel: the pragmatic entry point is an anti-corruption layer. Wrap the extracted/ported logic behind interfaces you own (App\Contracts\ItalianPa\SpedizioniService, etc.) and implement them with either a forked-and-vendored copy of the relevant classes or an HTTP client pointing at a small Symfony sidecar. Your Laravel code should never know the word "Fifree."

Implementation Patterns

Pattern 1 — Spike in a disposable Symfony container. Pin the Symfony major version the bundle declares, add the bundle to config/bundles.php, seed an App\Kernel, and exercise two or three concrete capabilities. Timebox it. The goal is to learn the domain model and confirm it runs, not to ship.

Pattern 2 — Extract to a framework-agnostic service namespace. Pull the domain classes you actually need (identity, registry lookups, payment metadata, protocol numbering — whatever your backlog needs) into App\Services\… or a small internal package. Strip Symfony AbstractController, ContainerAware, and event-dispatch coupling at the seam. Write contract tests against the original behavior so parity is provable.

Pattern 3 — Sidecar microservice. If the bundle's domain logic is entangled with Symfony runtime concerns you can't easily extract, run it as a Symfony app in its own container and expose a narrow HTTP API to your Laravel app. This isolates upgrade risk (one service to patch) and keeps your main app clean.

Pattern 4 — Vendored fork with a pinned SHA. Copy the source into packages/fifree-core/ or a private VCS repo, pin the commit you forked from, add a FORK_NOTES.md recording the license obligations and the fork point, and add a minimal test harness. This is the honest option when you decide to "own" it. Do not rely on Packagist for a package with no maintenance signal.

Day-to-day workflow once something is in place:

• Config: any published config (if the bundle ships a Configuration tree) stays in your app's config/packages/ — but if you've extracted, keep equivalent config in config/services.php (Laravel) or a dedicated config class you control.
• Testing: run bundle tests (if any) inside the spike container; run extracted domain tests inside your normal Laravel test suite. Never mix.
• Dependency updates: treat the vendored/extracted code as your code. Weekly Composer security audit of the host app; nothing upstream to watch.
• Code review gate: any PR touching the extracted namespace requires a reviewer familiar with the domain, because there's no upstream changelog to sanity-check against.

Integration tips:

• If you keep the bundle alongside Laravel in a monorepo, keep the two composer.json files separate — do not merge autoloads.
• Preserve upstream copyright headers in extracted files; EUPL/AGPL obligations typically require attribution.
• If the bundle has services that call municipal endpoints (ANPR, PagoPA), wrap them in timeout + circuit-breaker decorators immediately. Those endpoints are outside your control.

Gotchas and Tips

The framework mismatch is the first gotcha. Any instruction, tutorial, or Stack Overflow answer aimed at Laravel packages (service providers, facades, php artisan vendor:publish, package discovery) does not apply. If you find yourself fighting Illuminate\Foundation\Application, stop — you're on the wrong track.

Pitfalls to expect:

• Auto-discovery false positive. Composer may not auto-discover a Symfony bundle in a Laravel app, or worse, it might register something that fights the kernel. Verify composer.json type isn't library masquerading as a bundle.
• PHP/Symfony version ceiling. Bundles from PA contexts often target specific Symfony versions. A symfony/framework-bundle constraint like ^3.4 or ^4.4 will not resolve on modern runtime. Check before you plan.
• Global state mutation. Framework cores sometimes register error handlers, PHP ini changes, or autoloaders during boot. In a Laravel host this can silently break other packages. Audit prepend, boot, and any set_error_handler calls.
• Silent config defaults. If the bundle's Configuration sets defaults for a municipal environment (hostnames, certificate paths, auth schemes), the app may boot fine locally and fail on first real call. Grep for hard-coded URLs.
• No tagged release. If there's no tag, you're pinning a branch or SHA. Pin explicitly and record it.
• Language and vocabulary. Italian docs and PA-specific terms — SPID, CIE, ANPR, PagoPA, protocollo — will slow you down. Budget time or find a domain SME.

Debugging tips:

• Boot the bundle in the smallest possible Symfony app; use bin/console debug:container and debug:config to see exactly what services and configuration it registers. That's your fastest way to a capability inventory.
• If a service isn't resolving, check whether the Extension is loading services under a different filename convention or with environment-conditional blocks (if ($container->getParameter('kernel.environment') === …)).
• Use Xdebug stepping through DependencyInjection/FifreeCoreExtension::load — it's usually the map of the whole package.

Extension points (assuming a Symfony shape):

• Symfony bundles usually expose an Extension subclass plus a Configuration class — that's where you override defaults in your host app's config/packages/fifree_core.yaml.
• Compiler passes (if any) are where you can inject or replace services without forking.
• If there's no public extension point and you need behavior change, that's a signal to extract, not patch — you'll be fighting the maintainer's assumptions forever otherwise.

When in doubt: treat this as reference material to read, not a dependency to install. Zero stars, zero dependents, no release cadence, and an apparent framework mismatch all point the same direction. Vendor and own, or don't use it — but don't leave it as a live Composer dependency in a Laravel application you have to support.