Bi Laravel Package

Getting Started

The fastest path to understanding this package is not the readme — that is Portuguese and aimed at a human browsing Packagist. It is the shipped agent skill:

composer require luminix/bi
php artisan vendor:publish --tag=luminix-skill

That drops skill/SKILL.md plus skill/references/ into your app. Read SKILL.md first; it describes the routes, config keys, block classes, request payloads and published boot keys that src/ actually implements. Treat it as the API contract and the readme as marketing.

Minimal first-use case:

1. Publish config and frontend assets (vendor:publish for the bi and luminix-frontend tags).
2. Create app/Bi/Dashboards/ — this directory is what DashboardResolver scans.
3. Add one dashboard class with a single block/widget.
4. Hit the BI route and confirm the boot payload contains your dashboard.

Because the package is at 0 stars with 0 dependents, budget a half-day for install friction. Pin an exact version in composer.json from day one; the last release is dated late 2026 and the release process is still moving (see Gotchas).

Implementation Patterns

Dashboards as classes, not config. The resolver discovers PHP classes under app/Bi/Dashboards. The day-to-day pattern is one class per screen, composing widgets/blocks in a blocks()-style method. Keep dashboard classes declarative — they are metadata, not business logic. Put queries in dedicated data classes so a dashboard can be re-rendered without hitting the DB in its constructor.

Resolver as the integration seam. DashboardResolver is built on every boot payload, not just BI routes. This means the resolver is effectively a global service. If you need to gate dashboards by permission or tenant, do it inside the resolver's discovery filter, not inside individual dashboard classes — the resolver runs everywhere, individual dashboards do not.

Frontend reducers via luminix/frontend. BI registers reducers through BootService. If you are extending the UI, register your reducer during boot() of a service provider and make sure it is idempotent. Reducers are static state — see the test caveat below.

Publish the skill into CI, not just locally. A common workflow: run vendor:publish --tag=luminix-skill --force in a CI job and lint the resulting skill/ against your own docs. When the package ships a behavioural change (new config key, changed payload), the skill file is the thing that tells you, and --force is how you pick it up on the next publish.

Test against a throwaway Laravel, not a workbench. There is no host app. Use orchestra/testbench; each DB-touching test builds its own SQLite schema in setUp(). Copy that pattern for your own feature tests — do not assume a migrated app database exists.

Gotchas and Tips

DashboardResolver runs on every page. It is constructed on all boot payloads, so its constructor must be cheap and incapable of throwing. A dashboard class with a bad constructor argument, a missing config key, or a ::class reference to a deleted class will break every page in the app — including login. Validate dashboard registration in a test that boots the app with an empty app/Bi/Dashboards/, then with each dashboard individually.

Static reducers leak across tests. luminix/frontend's BootService stores reducers in a static property. Any test that lets BiServiceProvider::boot() register one must call BootService::flushReducers() in tearDown(), or the reducer bleeds into every later test in the same PHP process. This is the single most likely source of "works alone, fails in suite" flakiness.

Branch and release confusion for contributors. origin/HEAD still points at v0.x; the live line is v1.x. A fresh clone lands in the wrong place. If you are patching, branch from v1.x and target v1.x. Semver is derived from the commit subject: (MAJOR) and (MINOR) markers are load-bearing, absence means patch. Getting this wrong silently ships a patch as a feature.

Tag prefix is empty now. Older tags are v1.1.x-style, but tag_prefix was removed. Do not write version constraints that assume a v prefix without checking what is actually on the remote.

Portuguese docs, English skill — keep them separated. readme.md and docs/ are Portuguese; skill/ is English and is the only tree that ships to consumers. When you read a discrepancy between the readme and the skill, the skill wins — the package's own contributing guide treats an API described in skill/ that src/ lacks as a bug in skill/, not in src/.

No local PHP. Everything runs through the image:

docker run --rm -u 1002:1002 -v "$PWD":/app -w /app php-composer:8.3-imagick composer test

Do not expect vendor/bin/phpunit to work on the host.

Maturity risk. Zero stars, zero dependents, and an unusual release cadence mean you should expect breaking changes between minor releases despite the semver scheme. Vendor-review the src/ you depend on, wrap the resolver and boot integration behind your own thin adapter, and keep dashboard definitions data-only so an API change costs you one adapter file rather than every screen.