README

componist/core ist das Basis-Package fuer das Componist-Dashboard in Laravel. Es liefert:

Dashboard-Routen unter /dashboard
Livewire-Module fuer Menues, Menu-Items, Settings und Notifications
Blade-Komponenten und Layouts
Datenbanktabellen inkl. Seeder fuer einen schnellen Start
Helper-Funktionen zur Einbindung in eigene Views

1) Voraussetzungen

PHP 8.2+ (im Monorepo aktuell mit Laravel 12 genutzt)
Laravel 12.x
Livewire 4.x
Node.js LTS (fuer Vite/Tailwind-Assets)

Installation

Monorepo (dieses Projekt)

Das Package ist bereits im Monorepo vorhanden. In der Regel reichen:

composer dump-autoload
php artisan package:discover

Externes Projekt

Wenn du componist/core ausserhalb des Monorepos nutzt:

composer require componist/core

Hinweis: Je nach Setup brauchst du ggf. einen VCS- oder Path-Repository-Eintrag in der Host-composer.json.

3) Publish-Tags im Ueberblick

Der CoreServiceProvider stellt mehrere Tags bereit.

Vollinstallation (empfohlen fuer schnellen Start)

php artisan vendor:publish --tag=componist.core.install

Veroeffentlicht:

CSS/JS nach resources/css und resources/js
config/markdownx.php
config/componist.php
resources/views/dashboard.blade.php
tailwind.config.js, vite.config.js, package.json in die Projekt-Root

Wichtig: Dieser Tag kann vorhandene Build-Dateien in der Root ueberschreiben.

Weitere Tags

# Blade-Views + View-Komponenten-Klassen
php artisan vendor:publish --tag=core.publishes

# Core Components (Views)
php artisan vendor:publish --tag=core.components

# Error-Pages (Canonical unter packages/componist/core/resources/views/errors)
php artisan vendor:publish --tag=core.pages.errors

# E-Mail-Branding (config/componist_mail.php)
php artisan vendor:publish --tag=componist.core.mail

# Dashboard-Layout als anpassbare App-Kopie
php artisan vendor:publish --tag=core.page.dashboard

Error-Pages: Locale aus app()->getLocale(), Light/Dark, Primary Teal. Nach Änderungen im Package erneut publishen bzw. Root syncen.

4) Datenbank: Migrationen und Seeder

Migrationen

Das Package laedt Migrationen automatisch (loadMigrationsFrom).

php artisan migrate

Relevante Tabellen:

menus
menu_items (inkl. icon, page_id, Indizes/FKs je nach Migrationstand)
settings
componist_core_notifications

Seeder

php artisan db:seed --class="Componist\Core\Seeders\SettingsTableSeeder"
php artisan db:seed --class="Componist\Core\Seeders\MenuTableSeeder"
php artisan db:seed --class="Componist\Core\Seeders\MenuItemTableSeeder"

Der MenuItemTableSeeder legt u. a. Standardeintraege fuer folgende Route-Namen an:

dashboard.index
componist.core.menus
componist.core.settings

Nutzung

Das Package registriert seine Routen unter:

Prefix: /dashboard
Name-Prefix: componist.core.
Middleware: config('componist.auth') (Standard: ['auth'])

Home-Routen (Auth)

dashboard.index -> /dashboard (Middleware: auth, twofactor, verify)
profile -> /profile (gleiche Middleware)
Views: component::backend.dashboard, component::backend.profile

Verfuegbare Routen (je nach Modul-Flags)

componist.core.settings -> /dashboard/settings
componist.core.menus -> /dashboard/menu
componist.core.menu.items -> /dashboard/menu/items/{id}
componist.core.notification -> /dashboard/notification
componist.core.notification.show -> /dashboard/notification/{componistCoreNotification}

Beispiel zum Deaktivieren eines Bereichs:

// config/componist.php
'routes' => [
    'settings' => true,
    'menu' => true,
],

Berechtigungen

Standardmaessig wird eine Gate-Ability registriert:

Ability: componist.core.manage
Default-Logik: erlaubt, wenn User->is_admin truthy ist

Mutierende Aktionen in Menue- und Menu-Item-Livewire-Komponenten verwenden:

Gate::authorize(config('componist.manage_ability', 'componist.core.manage'));

Eigene Berechtigungsstrategie

In config/componist.php:

'manage_ability' => 'admin.panel.manage',

Und in deiner App (z. B. in AppServiceProvider):

use Illuminate\Support\Facades\Gate;

Gate::define('admin.panel.manage', function ($user): bool {
    return $user->hasRole('admin');
});

Konfiguration

`config/componist.php`

Wichtige Keys:

routes.*: schaltet Dashboard-Module ein/aus
template.*: Layout-Komponenten
dark_mode: Feature-Flag fuer UI
auth: Middleware-Stack fuer Dashboard-Routen
manage_ability: Gate-Ability fuer Admin-Aktionen
select2.allowed_tables: Allowlist fuer dynamische Select2-Datenquellen

`config/config.php` (`componistConfig`)

Steuert die automatische Registrierung:

components: Blade-Komponenten-Mapping
livewire: Livewire-Komponenten-Mapping
prefix: globaler Prefix fuer Aliasnamen

Prefix-Beispiel:

// config/config.php
'prefix' => 'core-',

Dann lautet z. B. der Alias:

Blade: <x-core-layouts-dashboard />
Livewire: @livewire('core-menu.index')

Dark / Light Mode

Einheitlich über Alpine:

Im Layout-<head>: @include('component::components.layouts.partials.theme-boot')
Toggle: $store.theme.toggle() / Zustand: $store.theme.dark
Persistenz: localStorage.theme (dark|light), Klasse dark auf <html>

Keine parallelen Theme-Scripts oder sessionStorage. Details: Cursor-Rule .cursor/rules/theming.mdc.

`config/componist_mail.php` (E-Mail-Design)

Einheitliches Soft-Split-Layout (linke Teal-Akzentschiene, strukturierte Blöcke) für die ganze App:

Key	Bedeutung
`brand_name`	Markenname (Default: `APP_NAME`)
`logo_path`	Logo unter `public/` oder absolute URL
`primary`	CTA-/Akzentfarbe (Default `#14b8a6`)
`footer_text`	Optionaler Footer-Hinweis
`support_url`	Support-Link im Footer
`theme`	Laravel-Markdown-Theme (Default `componist`)

MailMessage / Auth-Notifications nutzen automatisch Theme componist (Provider setzt mail.markdown.*).

HTML-Mailables wrappen Inhalt so:

<x:component::mail.shell title="Passwort zurücksetzen" label="Sicherheit" preheader="Link 60 Minuten gültig">
    <x:component::mail.heading title="Passwort zurücksetzen" greeting="Hallo Anna," />
    <x:component::mail.sep />
    <x:component::mail.section>
        <p>wir haben eine Anfrage erhalten …</p>
    </x:component::mail.section>
    <x:component::mail.sep />
    <x:component::mail.section padding="cta">
        <x:component::mail.button url="{{ $url }}">Neues Passwort festlegen</x:component::mail.button>
    </x:component::mail.section>
    <x:component::mail.section>
        <x:component::mail.panel title="Sicherheitshinweis">…</x:component::mail.panel>
    </x:component::mail.section>
</x:component::mail.shell>

Neue Feature-Mails sollen kein eigenes HTML-Layout erfinden.

8) Blade- und Livewire-Komponenten

Form- und Button-Primitives (einheitlich)

Alle Form-/Button-Klassen liegen zentral in Componist\Core\Support\Ui. Nutze die Blade-Komponenten statt eigener Tailwind-Strings:

<x:component::form.label value="E-Mail" />
<x:component::form.input type="email" wire:model="email" />
<x:component::form.input-error for="email" />

<x:component::form.textarea wire:model="notes" />
<x:component::form.select wire:model="status">…</x:component::form.select>

<x:component::button.primary wire:click="save">Speichern</x:component::button.primary>
<x:component::button.secondary wire:click="cancel">Abbrechen</x:component::button.secondary>

Tokens (Auszug): Ui::FIELD, Ui::TEXTAREA, Ui::LABEL, Ui::BUTTON_PRIMARY, Ui::BUTTON_SECONDARY, Ui::SURFACE. Light/Dark und Teal-Focus sind darin enthalten; Fehlerzustände über aria-invalid="true".

Blade

<x-layouts-dashboard>
    <x-element-modal id="example-modal">
        <x-slot name="title">Beispiel</x-slot>
        Inhalt im Modal
    </x-element-modal>
</x-layouts-dashboard>

Livewire

@livewire('menu.index')
@livewire('menu-item.index', ['id' => $menuId])
@livewire('notification.componist-core-notification-bell')
@livewire('notification.componist-core-notification')

9) Helper-Funktionen mit Beispielen

Das Package autoloaded src/Helpers/helpers.php.

`setting(string $key)`

Liest einen Setting-Wert aus der Tabelle settings.

$siteTitle = setting('site_title');

`menu(string $menuName, ?string $type = null)`

Liefert ein Menue als HTML oder als Array.

{{-- Standard-Template --}}
{!! menu('admin') !!}

{{-- Spezifisches Template --}}
{!! menu('admin', 'vertical') !!}

// Als Datenstruktur statt HTML
$items = menu('admin', 'array');

`componist_menu_href($menuItem)`

Resolved den Link fuer einen Menu-Item anhand von Typ und Route-Fallback.

$href = componist_menu_href($menuItem);

10) Benachrichtigungen erstellen

Du kannst programmatisch Eintraege fuer die Core-Notifications anlegen:

use Componist\Core\Models\ComponistCoreNotification;

ComponistCoreNotification::CreateMessage(
    auth()->id(), // alternativ E-Mail als String
    'Deployment erfolgreich',
    'Das neue Release wurde erfolgreich ausgerollt.'
);

Die Notification-Livewire-Seiten zeigen anschliessend:

Liste (/dashboard/notification)
Detailansicht inkl. Read-Markierung (/dashboard/notification/{id})

11) Assets (Vite, JS, CSS)

Nach vendor:publish --tag=componist.core.install stehen die Assets in deinem Host-Projekt bereit.

Build

npm install
npm run build

Development

npm run dev

Typische Files:

resources/css/dashboard.css
resources/js/dashboard.js
resources/js/tinymce.js
ggf. resources/css/app.css, resources/js/app.js, resources/js/guest.js

Tailwind CSS: Componist-Views scannen

Damit Tailwind v4 Utility-Klassen aus Blade-Views aller installierten Componist-Packages erkennt, muss in den veröffentlichten CSS-Dateien folgende @source-Zeile enthalten sein:

@source '../../vendor/componist/**/resources/views/**/*.blade.php';

Diese Zeile ist in den Package-CSS-Dateien (app.css, dashboard.css, guest.css) bereits vorkonfiguriert und wird beim Publish mit übernommen.

12) Typische Integrations-Workflows

A) Schnellstart fuer internes Admin-Panel

Package installieren/autoloaden
vendor:publish --tag=componist.core.install
php artisan migrate
Seeder laufen lassen
npm run build
/dashboard/menu aufrufen und Menue pflegen

B) Sicherheit zuerst (empfohlen in produktiven Projekten)

manage_ability auf eigene Ability setzen
Eigene Gate::define(...)-Regel hinterlegen
componist.auth um zusaetzliche Middleware erweitern (z. B. verified, 2fa)
Optional routes.* auf benoetigte Module reduzieren

Hinweise

Menue-Links erscheinen nicht

Pruefen, ob name oder view_path auf existierende Route zeigt.
Bei type=route/page wird auf benannte Routen geprueft.

Dashboard-Routen geben 403

User hat keine freigegebene Ability (manage_ability).
Gate-Regel und is_admin/Rollenmodell pruefen.

Styles/Skripte fehlen

Nach Publish npm install + npm run build ausfuehren.
Bei lokaler Entwicklung npm run dev starten.

Ueberschriebene Build-Dateien

componist.core.install schreibt package.json, vite.config.js, tailwind.config.js.
Vorher bestehende Dateien sichern oder gezielt einzelne Publish-Tags verwenden.

Commands

Keine Artisan-Commands in diesem Package.

Tests

php artisan test --compact --testsuite="Componist Core"

14) Lizenz

MIT

componist / core

Package info

Security

Statistics