Framework Core Bundle Laravel Package

Getting Started

Know what this is first: sumocoders/FrameworkCoreBundle is a Symfony bundle, not a Laravel package. It ships the shared "framework core" that SumoCoders uses across its Symfony applications: base controller/service/form-type classes, Twig layout extensions, form types, and small UI components. There is no Illuminate\Support\ServiceProvider, so you cannot composer require it into a Laravel app and expect anything to boot.

If you are on Symfony (or evaluating a codebase that uses it):

1. composer require sumocoders/framework-core-bundle
2. Register in config/bundles.php:

   SumoCoders\FrameworkCoreBundle\FrameworkCoreBundle::class => ['all' => true],
   

3. Import its routing if you use the shipped controllers (including the new quick-search endpoint):

   # config/routes/framework_core.yaml
   framework_core:
       resource: '@FrameworkCoreBundle/config/routes.yaml'
   

4. Clear cache (bin/console cache:clear) and load any page that extends the bundle's base layout.

First use case — the new quick search (v19.2.0): if your app's layout extends the bundle's base template, the header search box should render automatically. Type in it, hit the keyboard shortcut, and confirm results appear. That single interaction is the fastest smoke test that the bundle is wired correctly (templates + routing + assets + firewall all at once).

If you are on Laravel: treat this as a reference implementation, not a dependency. Skim BaseController, BaseService, and the form types to see how they factor shared behaviour, then re-implement the parts you want (global quick search, paginator helpers, base form type) with Laravel equivalents — a Blade component, a Livewire/Alpine search modal, and a FormRequest-style base class.

Implementation Patterns

Extending the base classes. The bundle's value is inheritance, not composition. Controllers extend BaseController to get the shared helpers (redirect-with-flash, pagination plumbing, breadcrumb/menu registration). Services extend BaseService for common logger/repository access. Form types extend BaseFormType to inherit the bundle's default options and validation wiring. Do this consistently — mixing in raw AbstractController breaks the conventions other bundle features assume.

Quick search integration (v19.2.0). The feature is a global search entry point in the layout, so the integration surface is small:

• Ensure your layout chain still ends at the bundle's base template ({% extends '@FrameworkCoreBundle/layout.html.twig' %} or your app layout that extends it). If you copied the layout into your app instead of extending, the search box will not appear — port the new partial across.
• Wire a search provider/endpoint so the box has something to query. Results are normally supplied by the app; the bundle only owns the UI and the request handling. Check the bundle's route definition for the exact path and expected response shape.
• Include the bundle's JS. If you use AssetMapper or Webpack Encore, confirm the new search script is in the built entry — a stale public/build is the most common reason "the box renders but nothing happens".

Service and DI conventions. Use autowiring and the bundle's interface aliases rather than instantiating helpers manually; several bundle services are designed to be decorated or replaced. When you need different behaviour, prefer decorating an existing service over subclassing a controller.

Template overrides. Override individual templates via templates/bundles/FrameworkCoreBundle/... rather than forking the whole bundle. This keeps you on the upgrade path — important because the bundle cuts frequent minor releases.

Upgrade cadence. Versions are released as vX.Y.Z minors with changelog entries. Pin to ^19.2 in composer.json, read the changelog per bump, and run your smoke test (page load + quick search + a form submit) after each one.

Gotchas and Tips

• Framework mismatch is the headline gotcha. No Laravel support, no facades, no config/*.php publish tags. If a Laravel developer is asked to "add this package", clarify scope before writing code — the realistic outcome is a port, not an install.
• Routes are not auto-registered. The quick-search endpoint only exists once the bundle's routing file is imported. Symptom: a 404 from the search box while the UI renders fine.
• Firewall/access control. Global search is often hit before authentication or from the login layout; make sure the route is reachable for the roles that need it, and that it does not leak data to anonymous users. Restrict the provider, not just the template.
• Assets are stale more often than code is broken. After upgrading to v19.2.0, rebuild assets before debugging JS. cache:clear alone does not rebuild Encore/AssetMapper output.
• Template overrides shadow new features. A copied-and-pasted layout silently drops anything the bundle adds — exactly the failure mode for quick search. Keep {% extends %} chains intact and diff overrides on every minor bump.
• Debugging checklist for the new feature: (1) is the layout extending the bundle base? (2) is the route imported? (3) are assets rebuilt? (4) does the search endpoint return the expected payload for a manual curl? (5) does the firewall allow it?
• Extension points for quick search: the useful customisation is the result provider (what gets searched and how results are shaped), not the markup. Register your own provider/adapter service and keep the bundle's template untouched so future releases apply cleanly.
• Minor release, low risk. v19.2.0 is additive (one PR, one feature) with no changelog entry suggesting deprecations or BC breaks. Nothing to migrate — but it is a good trigger to verify the whole layout/asset/routing chain still works end to end.