Download the PHP package adhocrat-io/arkhe-main without Composer

adhocrat-io/arkhe-main

Bootstrap a Laravel backend with users, roles and permissions management, served by Livewire 4 and Flux UI Free. Ships first-class SEO, sitemap and cookie-consent integrations on top.

First module of the adhocrat-io/arkhe-* namespace.

Requirements

Recommended starting point

The installer expects a Livewire 4 + Flux UI host app. The smoothest experience is on Laravel 12 with the Livewire/Volt starter kit (or the Flux starter), because:

• the layout default layouts::app (the Livewire 4 convention) resolves to a view the starter kit ships;
• the sidebar partial injection (step 8 below) targets the starter's <flux:sidebar.nav>;
• the Tailwind v4 @source patch (step 9 below) targets the starter's resources/css/app.css.

On a bare Laravel app with no starter kit the package still installs cleanly — the optional steps (sidebar + CSS) are skipped silently. You then have to point Arkhe at its own bundled layout (header-only, no sidebar):

See Limitations for the full list of skip conditions.

Installation

The interactive installer walks through every step in order:

1. Publish config/arkhe.php.
2. Publish the migration that adds profile columns (first_name, last_name, avatar_path, phone, date_of_birth, civility, bio) to the users table.
3. If spatie/laravel-permission is not migrated yet, publish its config and migrations automatically — no need to run its setup separately.
4. If ralphjsmit/laravel-seo is not migrated yet, publish its migration + config (see SEO).
5. Optionally publish the views.
6. Run php artisan migrate.
7. Seed the four default roles: root, administrateur, user, guest.
8. Patch your <flux:sidebar.nav> with @include('arkhe::partials.sidebar-items') (idempotent — skipped if already done).
9. Patch your Tailwind v4 resources/css/app.css with the @source directive needed to scan the package's Blade views (idempotent). For Tailwind v3 setups, the installer prints the equivalent content glob to add to tailwind.config.js.
10. Offer to add the HasBackendProfile trait to your App\Models\User automatically (skipped if the model already uses HasRoles, which would conflict).
11. Create a first root user via interactive prompts.

Every step is idempotent — re-running arkhe:main:install after an upgrade is safe and is the recommended way to pick up new install-time integrations (see Upgrading).

Creating users from the CLI

Once installed, add new users without leaving the terminal:

The command lets you pick the role from a prompt populated by the roles table. CLI calls bypass the runtime role-hierarchy check (the assumption being that anyone with shell access already has full authority), so you can seed a root user from a deploy script without auth context.

Configuration

.env:

The full configuration lives in config/arkhe.php after publishing.

Wiring up your User model

Add the HasBackendProfile trait to your User model.

The trait adds three accessors (full_name, avatar_url, initials) and two helpers (isArkheRoot(), isArkheAdmin()).

Accessing the backend

By default: GET /administration/users (the prefix is configurable).

Access is granted to users carrying either the root or administrateur role; everyone else gets a 403 via the arkhe.backend middleware.

Coexisting with a custom admin (Livewire starter kit)

Arkhe is designed to plug into your existing admin shell rather than replace it. Two integration points:

1. Use your app's layout

In config/arkhe.php:

Arkhe pages will render inside your existing chrome (sidebar, topbar, your CSS).

2. Take over the dashboard route (opt-in)

Comment out the dashboard route in your routes/web.php and set the path:

Arkhe mounts a minimal users-by-role dashboard at the path you choose. Keep the env var unset and your own dashboard remains untouched.

Login redirect. The Laravel starter kits redirect to route('dashboard', absolute: false) after authentication. Two ways to point that at Arkhe:

• A — re-use the dashboard route name (zero patch on your starter):

  route('dashboard') now resolves to /administration/dashboard, the after-login redirect just works.

• B — keep arkhe.dashboard and patch the starter's login: open the login Livewire/Volt component and replace route('dashboard', absolute: false) with route('arkhe.dashboard', absolute: false). Pick this when another part of your app still needs dashboard to mean something else.

Fortify users (Laravel 12 Livewire starter kit included): the starter's login form posts to Fortify, which redirects to the literal value of config('fortify.home') after auth — not via the named dashboard route. Arkhe detects Fortify automatically and rewrites that value to your ARKHE_DASHBOARD_ROUTE at boot, so neither A nor B is needed for the form submission to land on the right page. Set ARKHE_OVERRIDE_FORTIFY_REDIRECT=false to opt out.

3. Inject Arkhe entries into your sidebar

Include the bundled partial at the top level of your <flux:sidebar.nav> — it emits its own Dashboard item plus the registry-driven groups ("Accès", "Réglages", and any group contributed by a satellite package), so it sits alongside your own groups rather than nested inside one:

You can also publish the partial to customise it:

4. Branch a package onto the shared menu — ArkheNav

The sidebar is driven by a navigation registry (Arkhe\Main\Support\ArkheNav). Arkhè seeds two sections — access ("Accès") and settings ("Réglages") — and any package can branch onto the same menu from its service provider's boot(), with no Blade patching. This is how adhocrat-io/arkhe-watcher and future packages plug in.

Add an entry to the shared Réglages section (one line per package — the goal: every package's settings in one place):

Or declare your own collapsible group (for a richer tool with several pages):

A section is rendered only when its gate passes and it has at least one visible item; items are filtered per-user by their own can. Sections and items order by priority (lower first). Because registration is keyed and idempotent, Main and packages can register in any order.

A menu can only hides the link — it is not access control. It governs visibility in the sidebar, nothing more. You must still protect the destination yourself by gating the package's routes with middleware (arkhe.backend, arkhe.root, or your own). Treat the menu gate and the route guard as two independent layers and keep them in sync. For example, adhocrat-io/arkhe-watcher gates its routes with arkhe.watcher (and arkhe.root for its settings page) in addition to the matching menu can.

Role hierarchy & authorization

The Arkhe\Main\Support\RoleHierarchy helper encodes a configurable role hierarchy. A user can only assign roles whose rank is less than or equal to their own. The default order, highest first, is:

This means: only root can assign root; an administrateur cannot promote anyone to root; and so on.

The hierarchy is enforced at three layers:

• the role <select> only lists roles the acting user can assign;
• a closure rule on UserForm rejects any out-of-rank role at validation time;
• UserService::syncRolesAndPermissions() throws AuthorizationException as a backstop for direct service callers.

Extending the hierarchy

Two extension paths are available — pick the one that matches your situation.

Option A — Static, via config/arkhe.php

Use this when the roles are known at deploy time and live with the application: the values you want are part of the codebase, not contributed by an external package.

The order of config('arkhe.roles') IS the hierarchy (first entry = highest rank). Insert your role at the right position between two existing entries:

Then create the matching row in the roles table by re-running the bundled seeder:

Pros: declarative, version-controlled, visible to every dev reading the config. Cons: requires editing the published file in each host app.

Option B — Runtime, via RoleHierarchy::register()

Use this when the role is contributed by a package, module or feature flag — i.e. you cannot (or do not want to) require the host app to edit config/arkhe.php.

From your package's service provider:

register() can also reposition an already-known role on subsequent calls. Your package is still responsible for creating the matching row in the roles table (typically via its own seeder).

Pros: zero config edit on the host side, perfect for distributed packages. Cons: invisible at first glance — document loudly which role(s) your package contributes.

Which one to pick?

Contract

The four canonical Arkhe keys — root, administrator, user, guest — must remain in config('arkhe.roles'). Internal Arkhe code references them directly (config('arkhe.roles.root'), …). You can:

• ✅ insert new roles between them,
• ✅ change the value (the actual role name stored in DB), e.g. 'user' => 'membre',
• ❌ rename or remove the four canonical keys.

Styling — Tailwind / Flux

Tailwind only compiles classes it can see. Since this package's Blade files live in vendor/adhocrat-io/arkhe-main/resources/views/, they are not scanned by the default Laravel setup. The installer takes care of this for Tailwind v4 (step 8 above); the snippets below document the same thing for reference or for manual setups.

Tailwind 4 (recommended, used by Flux 2):

Tailwind 3:

Then:

The layout published with the package uses @fluxAppearance and @fluxScripts from livewire/flux — make sure those directives are reachable (they ship with Flux automatically).

Architecture

The package strictly follows the Repository + Service pattern:

No Eloquent query happens outside src/Repositories/. No mutation happens outside src/Services/. When extending, follow the same rule — see CONTRIBUTING for details.

Events

Translations

Locale by default: fr (with en fallback). Override per-app via:

SEO

adhocrat-io/arkhe-main ships ralphjsmit/laravel-seo as a first-class dependency since 3.1.0. The arkhe:main:install command publishes the SEO package's migration and config, and the package's seo() helper is rendered in the Arkhe layout's <head>.

Site-wide defaults — /administration/seo

A root-only Livewire page at /administration/seo (named arkhe.site-seo.edit) edits the site SEO defaults stored in the arkhe_site_seo table:

• Site name (used in OpenGraph tags)
• Title suffix (appended to every page <title>, e.g. | Acme)
• Default description
• Default OG image
• Author
• Robots
• Twitter / X handle
• Favicon

These values are merged into the SEOData rendered on every page via a SEOManager::SEODataTransformer registered by Arkhe\Main\ArkheMainServiceProvider::bootSeo(). They serve as fallbacks: anything provided per-page or per-model (see below) wins.

Per-model SEO — HasArkheSeo trait

Drop the trait on any Eloquent model to get per-record SEO storage:

This creates a polymorphic seo row on every new Post, exposes a $post->seo relation, and lets you render:

You can also override SEO dynamically by implementing getDynamicSEOData() on your model (see the upstream package docs for the full API).

The merge order (highest priority first):

1. getDynamicSEOData() overrides on the resolved model
2. The polymorphic seo row ($model->seo)
3. Arkhe site defaults from /administration/seo
4. config('seo.php') (the upstream package's static defaults)

Disabling the integration

Set arkhe.features.seo to false in your config/arkhe.php to skip the SEOData transformer registration. The seo() helper still works (the upstream package is always loaded), it just won't pick up Arkhe's site defaults.

Sitemap

Arkhe ships spatie/laravel-sitemap since 3.1.0. The package registers a scheduled GenerateSitemap job and exposes a root-only admin page at /administration/sitemap (route arkhe.sitemap.edit) to inspect status and trigger a regeneration on demand.

Configuration

config/arkhe.php:

The cron expression is registered with callAfterResolving(Schedule::class, …) so it lights up as soon as the host app's scheduler runs. To skip the automatic scheduling without losing the admin button, set ARKHE_SITEMAP_ENABLED=false.

Running the job manually

The Regenerate now button dispatches Arkhe\Main\Jobs\GenerateSitemap onto the host app's default queue. With the sync driver, the regeneration runs inline — same code path, no scheduler dependency.

Customising the generator

Subclass Arkhe\Main\Services\SitemapService and override configureGenerator(SitemapGenerator $generator): void to add URLs, swap the crawl profile, or filter pages. Then point the binding at your subclass:

For per-model integration, implement Spatie's Sitemapable contract on any Eloquent model — see the upstream docs.

Cookies & GDPR

Arkhe ships whitecube/laravel-cookie-consent since 3.1.0. The package's @cookieconsentscripts and @cookieconsentview blade directives are rendered in the Arkhe layout, gated by Features::hasCookieConsent() (defaults to true).

Out-of-the-box behaviour

Arkhe\Main\Cookies\ArkheCookiesServiceProvider is registered automatically and declares Laravel's session + CSRF cookies under the essentials category. As soon as you install the package, the consent banner appears with a GDPR-compliant baseline — no extra setup required.

Registering app-specific cookies

For cookies your app sets beyond the essentials (analytics, optional features, …), publish the upstream stub provider and register your own cookies in it:

Then add App\Providers\CookiesServiceProvider::class to bootstrap/providers.php and edit it as documented upstream:

Both providers coexist — Arkhe registers essentials, your provider adds the rest.

Audit page — /administration/cookies

A root-only read-only Livewire page at /administration/cookies (route arkhe.cookies.index) lists every category and cookie currently registered through both Arkhe and any consumer-side providers. Use it as a GDPR audit trail.

Disabling the integration

Set arkhe.features.cookie_consent to false in config/arkhe.php to remove the banner directives from the Arkhe layout and skip registering Arkhe's essentials. The upstream package remains installed (Cookies::hasConsentFor(...) keeps working) — only the banner is silenced.

Feature flags

Both SEO and cookie consent became first-class features in 3.1.0 and default to on. The flags remain as escape hatches for consumers that want to keep the dependencies installed but silence the integration:

Read them programmatically via \Arkhe\Main\Support\Features::hasSeo() / hasCookieConsent().

Extension points at a glance

Seven layered ways to customise Arkhe without forking it — pick the lightest one that fits:

Subclass override example (lever 3 + lever 2):

No route changes needed in the host app.

Limitations

Things that may surprise you. None are blockers — most are deliberate trade-offs to keep the installer non-destructive.

Upgrading

Between minor / patch versions

arkhe:main:install is idempotent on every step (publish, migrate, seed, sidebar patch, css patch, trait patch). Re-running it after upgrading is the canonical way to pick up new install-time integrations (e.g. a new @source to add to app.css, a new sidebar entry to inject).

If you'd rather skip the prompts, the manual snippets in the Wiring up your User model sections give you the exact lines to add.

From V2 to V3

V3 keeps the V2 public surface — namespace Arkhe\Main, service provider, config prefix — so no global search-replace is required. A dedicated Artisan command handles the config migration:

What it does:

• Appends V3-only keys to your published config/arkhe.php (dashboard_route, role_permissions, components, backend_permission, root_permission, features) without touching existing V2 entries.
• Rewrites legacy Livewire aliases inside resources/views/ (e.g. arkhe.main.livewire.admin.users.users-list → arkhe.list-users).
• Runs the V3 permission seeder so the new 16 default permissions and their role mappings land in your DB.

See CHANGELOG.md for the full breaking-change list and the V2 → V3 migration playbook.

Testing

CI runs the matrix PHP 8.3/8.4 × Laravel 12.*/13.* × prefer-lowest/prefer-stable.

License

MIT — Luc, adhocrat.io.