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

Validate input in layers

For every browser-facing input, design validation as three cooperating layers. Use HTML attributes for native hints and constraints, JavaScript for immediate feedback where it improves the workflow, and Laravel/backend validation as the required authority before any write, upload, import, handler call, queued job, or external request.

Do not rely on HTML or JavaScript as a security boundary. Tests and browser checks should cover the successful path and, where practical, at least one invalid or tampered input path that proves the backend returns a controlled validation, authorization, or not-found response. For file inputs, validate configured formats and maximum sizes on the backend even when the dropzone shows those limits in the UI.

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 workbench runs with ADMINIX_ASSET_MODE=local. The e2e:* scripts refresh Testbench-published Adminix assets before opening the live page, so local Bootstrap, Bootstrap Icons, Chart.js, Popper, CKEditor lazy loading, and Adminix runtime files are exercised in the browser.

Visual regression checklist

For UI-facing changes, inspect the rendered Adminix page in a browser after the automated tests pass. Use the smallest page that exercises the changed module, then check the shared shell and responsive states.

• Shell: sidebar, mobile menu, theme switcher, footer, toast stack, focus states, and dark/light contrast.

• Lists: search, filters, quick filters, pagination, sorting, row actions, bulk actions, pinned columns, grouping, summaries, reorder handles, drag preview, and mobile overflow.

• Resource and create forms: labels, validation messages, readonly/hidden fields, uploads, WYSIWYG lazy loading, selects, date/time controls, JSON/markdown/key-value fields, submit feedback, and old input after validation errors.

• Modals and relation managers: open/close behavior, backdrop, validation, nested form controls, signed context, and scroll containment.

• Import, media, tenant, notification, audit, progress, metric, chart, text, link, and clock modules: empty states, loading states, action buttons, icons, hover states, and server-returned errors.

• Responsive states: desktop, narrow mobile, horizontal tables, sticky columns, touch-size controls, no text overlap, and no controls clipped outside containers.

• End-to-end result: click or type through the actual control and confirm DOM, network/API response, persisted data, notification/modal state, and visual layout.

Check coverage

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

composer coverage writes a Clover report and then checks coverage-thresholds.json. The first stage requires at least 30% project line coverage and at least 50% line coverage for selected critical services:

• AdminixEndpointResolver;

• CriteriaDefinition;

• ResourceRepository;

• TenantContextProviderResolver.

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. Raise coverage-thresholds.json in small stages after adding or improving tests for the affected critical service.

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.

Release checklist

Before tagging an Adminix package release:

• Review git status --short and stage only release-related files.

• Update CHANGELOG.md with the version, date, and user-facing changes.

• Update README, Writerside topics/tree, Boost resources, and roadmap when the release changes public behavior, install flow, support policy, commands, security expectations, or developer workflow.

• Run composer pint, composer test, composer validate --strict, ./vendor/bin/testbench adminix:doctor --strict, xmllint --noout Writerside/writerside.cfg Writerside/hi.tree Writerside/cfg/buildprofiles.xml, and git diff --check.

• Build and inspect Writerside with the project wrapper. It uses the same GitLab Pages builder image, mounts a disposable parent artifact directory, verifies report.json (174/174 or higher, no errors or warnings), and confirms every tracked screenshot is present in the ZIP:

  scripts/verify-writerside.sh

  Set ADMINIX_WRITERSIDE_ARTIFACTS_DIR=/absolute/path to retain the disposable build/ output for manual inspection.

• Run composer test:databases with the local MySQL/MariaDB/PostgreSQL containers for SQL- or migration-facing changes.

• Run composer archive --format=zip and inspect the archive when release packaging rules change; development dependencies, IDE files, tests, and generated output must be absent.

• Run composer coverage when Xdebug or PCOV is available; otherwise record that coverage was skipped because no coverage driver is installed.

• For UI-facing releases, run the relevant Playwright E2E script on a live Testbench server and complete the visual regression checklist.

• Create a focused commit and annotated tag such as v2.63.0.

• Push the branch and tags, then confirm the GitLab Pages documentation build and corrected public docs URLs.

• Confirm Packagist receives or can fetch the new tag.

• If push, Pages, Packagist, or publication is externally blocked, record the exact blocker and keep the local worktree clean.

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, custom registry, Blade component registration, 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, cross-driver 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.