Fb Report Laravel Package

Getting Started

Start by installing the package and publishing its config, views, and assets using the publish tags documented in the README:

composer require mortezamasumi/fb-report
php artisan vendor:publish

Then inspect, in this order:

1. config/fb-report.php — global defaults, report registration, and loading-screen behavior.
2. The package README — report definition API, routes, and supported customization points.
3. Published views under resources/views/vendor/fb-report — especially the loading-screen partial.
4. Existing report classes/config entries — how reports are registered and rendered.

The first practical use case is to render one existing report and confirm the new v5.4.0 default: a loading screen is now shown for all reports. Use that as your baseline, then decide whether to keep the global default or override it per report.

For a new report, wire up the smallest possible report definition, hit its route, and verify the loading state appears before the report content. Once that works, customize the loading view or opt specific reports out if the loader is unnecessary.

Implementation Patterns

Treat the loading screen as a global default with per-report overrides. Since v5.4.0 enables loading screens for all reports by default, the cleanest pattern is to leave the global setting on and override only fast or embedded reports where the loader adds noise.

Customize the loading view once, reuse everywhere. Publish the package views and replace the loading partial with your application’s skeleton/spinner component. This keeps every report visually consistent without touching individual report definitions.

Use the loading screen for data-heavy reports. Reports that call external APIs, aggregate large datasets, or render charts benefit most. Pair the loading state with cached report data so repeat views are fast and the loader does not flash unnecessarily.

Disable or shorten the loader for inline dashboard widgets. If reports are embedded in a dashboard alongside other content, a full loading screen can be disruptive. Prefer a per-report opt-out or a compact inline loading state if the package exposes one.

Keep report routes behind your normal middleware. Apply auth, authorization, and tenant scoping at the route/controller layer rather than inside report definitions. This keeps report classes focused on data and presentation.

Test the loading and loaded states separately. Assert that the loading markup is present in the initial response, then assert the final report output. If the loading screen is configurable, add tests for both enabled and disabled configurations.

Use config and view overrides as the primary extension points. Avoid editing vendor files. Publish config/views, override the loading partial, and use per-report settings where available.

Gotchas and Tips

• v5.4.0 changes default behavior. All reports now show a loading screen by default. If you previously had no loader, or implemented your own, verify you are not rendering two loading indicators. Check both global config and any per-report settings.
• Fast reports may flash the loader. If a report renders in milliseconds, a loading screen can look like a glitch. Disable it for those reports or enforce a minimum display time only if the package supports it.
• Republish or diff published views after upgrading. If you published views before v5.4.0, the new default loading view may not be present or may conflict with your overrides. Compare your published views against the package’s current views.
• Clear caches after config changes. Run php artisan config:clear and php artisan view:clear when changing loading-screen settings, especially in environments where config is cached.
• Check whether the loader is server-rendered or JavaScript-driven. If it depends on package assets, ensure assets are published and served correctly. If it is purely server-rendered, confirm your route response is not being cached in a way that skips the loading state.
• Per-report overrides beat global toggles. If only a few reports need different behavior, avoid disabling the loader globally and re-enabling it everywhere else. Use the narrowest override available.
• Watch for layout assumptions. A full-page loading screen may not fit inside an existing dashboard panel. Publish and adapt the loading partial if you need an inline variant.
• Debug by inspecting the initial HTML. Confirm the loading markup is present before the report content. If it is missing, check config, published views, and whether the report is using a custom view that bypasses the package layout.
• Extension points to prefer: published config, published views, per-report options, and custom report classes. Avoid subclassing internals unless the package documents them as stable.