Development

Install dependencies

Install package dependencies from the package root.

If you change development dependencies, update the lock file intentionally.

Run tests

Adminix uses PHPUnit with Orchestra Testbench for package-level regression tests.

or

Verify frontend end to end

UI-facing work must be verified in a live browser against a real rendered Adminix page. Use a consuming Laravel app, a Testbench/workbench harness, or another reproducible local Laravel runtime that exercises Adminix service provider registration, routes, Blade views, assets, CSRF/session behavior, API endpoints, and persistence.

Interact with the frontend directly instead of only inspecting markup:

• click buttons, links, tabs, dropdowns, drawers, modals, filters, actions, and notification controls;

• type into inputs and submit real forms;

• drag reorder/upload controls where the feature supports pointer input;

• use keyboard fallbacks for interactive controls that support them;

• trigger and inspect success and failure states.

For each browser check, confirm the visible layout and the relevant DOM state, network/API response, persisted data, toast/modal output, and responsive behavior. Static HTML inspection, PHPUnit-only assertions, or direct JavaScript state mutation are not a substitute for live browser interaction when the feature has a frontend surface. If browser verification cannot be completed, record the exact blocker and residual UI risk.

For the built-in reorder regression harness, start the Testbench server in one terminal.

Then install Node dependencies once and run the browser suite.

The e2e:reorder, e2e:pinned, and e2e:soft-delete scripts refresh Testbench-published Adminix assets before opening the live page.

Check coverage

Coverage requires a PHP coverage driver such as Xdebug or PCOV.

The command writes:

• build/logs/clover.xml;

• coverage/ HTML report;

• text summary in the terminal.

Use coverage locally before release-sensitive changes when a coverage driver is available.

Format code

Run Laravel Pint before publishing changes.

Inspect package integration

Use Adminix Doctor when changing configuration, page discovery, modules, console commands, or docs that affect consuming app setup.

Use --json for machine-readable output and --strict when warnings should fail a local or application pipeline.

Run Qodana

Adminix includes a local Qodana PHP scanner configuration. Run it locally only when needed. Adminix CI does not run Qodana and the project does not use Qodana tokens.

What to cover

When changing core behavior, add or update regression tests for the affected public contract:

• page generation and route parameters;

• module factories and data provider resolution;

• datasource validation for table names and Eloquent class strings;

• list lenses, filters, escaped search, sorting, pagination, actions, and criteria validation;

• invalid date filters and browser-provided sort directions;

• resource loading, validation, create, update, readonly, empty writable input, image URL/path, and JSON textarea flows;

• unique validation ignores for string rules and Rule::unique() objects;

• modal API fetch, save, create, malformed params, empty writable input, and validation behavior;

• authorization middleware behavior, session regeneration on login, and POST-only CSRF-protected logout;

• console commands, Adminix Doctor diagnostics, and publish paths for public assets.

• generator options, generated stubs, force behavior, and package-safe test stubs.

• CKEditor 5 runtime publishing and editor textarea synchronization.

• shared endpoint resolution, controlled endpoint errors, criteria operators, SQLite-compatible query behavior, and no-JS fallbacks where the rendered HTML can still submit safely.

Keep tests focused on package contracts rather than implementation details.

Roadmap work

When continuing roadmap implementation, work through the next actionable items in order without stopping after each completed item for a separate continuation prompt. Pause only for a real blocker, an external decision, a destructive operation, a release/publish step that cannot be safely inferred, or an architectural change requiring explicit approval.

SemVer

Use patch versions for bug fixes, docs, tests, frontend polish, and internal refactors that preserve the public PHP DSL and route/config contracts. Use minor versions for additive Adminix APIs such as new modules, fields, opt-in module methods, console options, providers, DTOs, and publishable assets. Use a major version only for breaking DSL/config/route contracts, changed persistence semantics, removed module methods, changed package support ranges, or behavior that consuming Laravel applications must rewrite.

CI

GitLab CI only builds the Writerside documentation artifact and publishes GitLab Pages. Package tests, Pint, coverage, and compatibility checks are local release gates, not CI jobs.

Laravel Boost

Adminix exposes Laravel Boost resources:

• resources/boost/guidelines/core.blade.php;

• resources/boost/skills/adminix-development/SKILL.md.

Keep guidelines short and action-oriented. Keep the skill as a high-signal Adminix module API reference for agents in parent Laravel projects, covering page providers, menus, list/search/filter/action flows, resource forms, modal CRUD, charts, counters, links, safety rules, and package checks. It should summarize operational behavior without duplicating every Writerside example.