Backend Laravel Package

Getting Started

composer require luminix/backend

Laravel's package discovery registers the service provider; there is no manual providers entry to add. The single highest-value first step is not reading the README (it is in Portuguese and aimed at Packagist visitors) — it is pulling the agent-facing guide into your app:

php artisan vendor:publish --tag=luminix-skill

That drops skill/SKILL.md plus skill/references/ into your project. This is the English, consumer-facing contract for the package: routes, status codes, config keys, scopes, hooks and gate names all live there. Read it before touching anything else; it describes behaviour, not marketing.

Then, in order:

1. php artisan vendor:publish (no tag) to see which config/migration tags exist, and publish the config so you can diff it against the package defaults.
2. php artisan route:list and filter for the package's prefix — the route table is the fastest way to confirm what the backend actually exposes in your app with your config, which can differ from the skill's description.
3. Check whether the package ships migrations (vendor:publish --tag=...migrations or a migrations entry in the provider). If it doesn't, your app owns the models and only consumes the routes/scopes/gates.

First use case: stand up the backend routes on a scratch app, authenticate a user, and hit one resource endpoint end-to-end. That single round trip exercises the provider, the config, the auth gate and the query scope layer at once — if any of those are misconfigured, this is where it shows. Do this on a throwaway branch before wiring it into anything real.

Implementation Patterns

Treat skill/ as the spec, not the README. The repo maintains two doc trees deliberately: skill/ ships and is written for a consuming agent, docs/ and the README do not ship and are tutorial-length Portuguese prose. When they disagree, skill/ is correct — an API it describes that src/ lacks is explicitly called a bug there. If you're generating code from docs, generate from skill/.

Keep the published skill in sync. The copy in your app goes stale on upgrade. After every composer update luminix/backend, re-run:

php artisan vendor:publish --tag=luminix-skill --force

Do this as a post-update step in your workflow (or a composer script) rather than remembering ad hoc — otherwise you'll code against last version's routes and gate names.

Authorize at the gate layer, don't fork routes. The package exposes named gates. Map them to your app's roles/permissions in a service provider rather than overriding controllers:

Gate::define('luminix.some-resource.view', fn (User $u) => $u->hasRole('editor'));

Confirm the exact gate names from skill/references/ — they are part of the public contract and may change between minors.

Compose query scopes instead of writing raw filters. The package ships scopes intended to be chained in your own queries and controllers. If you find yourself replicating filtering logic the skill documents as a scope, you're rebuilding something that will drift.

Use hooks for extension, not subclassing. Hooks are the designed extension point; overriding classes or copying controllers couples you to internals the package reserves the right to refactor (and the maintainers explicitly say internal refactors don't update skill/, i.e. internals are not contract). Anything observable — a route, a status code, a config key, a scope, a hook, a gate — is contract. Everything else is not.

Config-driven behaviour first. Before writing code, check whether the config already has a key for it. The package's own docs treat "a config key" as an observable change worth documenting, which implies the config surface is broad and intentional.

If you need to patch the package, the repo has no host app: orchestra/testbench builds a throwaway Laravel and workbench/ holds the models and migrations tests run against. Reproduce your bug there against v1.x before opening an issue:

composer test        # testbench package:test
composer artisan migrate

Gotchas and Tips

composer artisan splits each shell word into its own argument. The documented workaround is to call testbench directly for any command with options:

php vendor/bin/testbench vendor:publish --tag=luminix-skill --force

If you're contributing and a command mysteriously ignores a flag, this is why.

A lot of the repo does not ship. .gitattributes controls the archive: skill/ ships; AGENTS.md, CLAUDE.md, docs/ and workbench/ do not. So when you're debugging inside vendor/luminix/backend, don't go looking for docs/ or the workbench fixtures — they aren't there, by design. git archive HEAD | tar -t is the maintainers' check for this; you can use the same command against a tag to see exactly what you received.

The skill describes the current commit, not your installed release. It has no versioning of its own. A published copy from three releases ago will confidently describe routes that no longer exist. If behaviour and skill disagree, check composer show luminix/backend first — odds are the skill copy is stale, not the code.

Pin the version. One star, zero dependents, first tagged release in late 2026. This is pre-adoption software with an active v1.x release branch and automated tagging on every push. Use an exact constraint or ~1.x.y with a narrow floor, and read release notes rather than assuming patch-level safety — semver here is derived mechanically from commit subjects ((MAJOR) / (MINOR) / absence → patch), so a mislabelled commit can smuggle a breaking change into a patch.

Debugging checklist, in order: route:list (is the route even registered?), config('...') via php artisan tinker (did your cached config win over the published file? run config:clear), then Gate::forUser($user)->allows('...') to isolate auth from query logic. Most "the package is broken" reports in config-heavy Laravel packages resolve at step two.

If you're contributing: branch off v1.x with feat/ or fix/ prefixes, and write commit messages and branch names in Portuguese — the release automation reads the commit subject for the semver bump, so an English or malformed subject changes your release semantics. Any change observable from a consuming app (route, status code, config key, scope, hook, gate name) must be mirrored into skill/ in the same PR; internal refactors must not touch it.