File: README.md

Recommend this page to a friend!

README.md

File:	`README.md`
Role:	Documentation
Content type:	`text/markdown`
Description:	Documentation
Class:	Laravel Truss View a diagram of a Laravel application models
Author:	By Alberto Arena
Last change:	docs: link the theme builder from the README Point readers to the new visual theme builder on trussphp.com from both the intro demo line and the Theming section, so the config-driven theming feature has a low-friction, no-install way to try it and copy a config block. feat: theming and custom palettes (#22) Let a host redefine the dashboard's colours and fonts from config to match the app Truss is embedded in. A new truss.theme block exposes a small set of semantic knobs (accent, background, surface, text, border, and more) plus two font-family knobs; a ThemeStylesheet service maps each onto the internal design tokens and emits only the ones set, so a handful of values re-skins the whole dashboard, chrome and diagram, in both light and dark, while everything else stays on the shipped default. The overrides are delivered as a gated, same-origin stylesheet, so a strict Content-Security-Policy still needs only style-src 'self' and a default install makes no extra request. Values are validated against a strict allow-list before they are written into the CSS response, so a malformed or hostile value is dropped and degrades to the default rather than breaking or injecting the sheet. Fonts are family names only. The unused truss.diagram.theme key is removed in favour of truss.theme. feat: schema export command for CI and tooling (#20) Add `php artisan truss:export`, the command-line counterpart to the dashboard export button, so a CI job, script, or tool can pull the database structure without a human opening the diagram. It writes DBML, JSON, CSV, a Markdown data dictionary, or Mermaid to stdout by default or to a file with --output. The output is deterministic (tables, foreign keys, and indexes are given a canonical order, and nothing time-, version-, or host-dependent enters it), so the same schema always produces the same bytes. That makes the headline CI use case reliable: --check regenerates the export, compares it against --output, writes nothing, and exits non-zero on drift, failing a build when a committed schema file has gone stale. A new src/Export/ layer holds one Generator per format plus a SchemaExporter service that filters and orders the tables and dispatches to the generator. The generators are ported from the browser versions in resources/js; while both coexist they are pinned byte-for-byte to the same golden fixtures, checked from both Pest and Vitest, so the CLI and the dashboard download cannot drift. The export reuses the managed- connection allow-list and the excluded_tables merge, and config exclusions always win over --tables, so it never widens the structure surface the dashboard already exposes. Structure only, no row data, no network call, proven by a canary test that seeds a real row and asserts it appears in no format.
Date:	6 days ago
Size:	`13,330 bytes`

Download

Laravel Truss

Laravel Truss is a live database structure viewer. It scans your live schema and renders it as a scrollable, zoomable ER diagram right inside your app, so you can see how the tables actually connect without opening a DB client. It reads structure only (tables, columns, keys, indexes); row data is never queried or exposed.

Try the live demo to pan, zoom, focus, and export a sample schema in your browser, no install needed, then build a palette in the theme builder and copy the config. See what has shipped and what is next on the roadmap.

> Stay updated: click Watch > Custom > Releases to hear about new features, or follow along in Discussions.

Features

Live ER diagram of your database, rendered with Mermaid.
Focus mode: a table and its foreign-key neighbours, centred and highlighted.
Filter by table name, and toggle native types against Laravel-style labels.
Map-style pan and zoom, with auto-fit and a Fit button.
Export the diagram as PNG or SVG, or its structure as JSON, CSV, a Markdown data dictionary, or DBML, from the browser or, for CI and tooling, from the command line with `php artisan truss:export`. Structure-only and deterministic.
Schema diff: see what changed since your last migration, in a dashboard "Changes" panel and via `php artisan truss:diff`. Structure-only, added / removed / changed tables, columns, indexes, and foreign keys.
Schema doctor: review your structure for problems (missing primary keys, unindexed foreign keys, duplicate indexes, risky types) in the terminal or in CI with `php artisan truss:doctor`, and in a dashboard "Health" panel that flags the same problems on the diagram. Deterministic and structure-only, no AI.
Multiple connections: list them in config and switch between their diagrams with a toolbar picker, each scoped to its own database.
Light and dark "blueprint" theme, or bring your own: define custom colours and fonts from config to match your app. Config driven, CSP-safe, no build step.
Self-contained: Mermaid and fonts are vendored and served from the package, so it works offline and under a strict Content-Security-Policy (no CDN).
Cached snapshot, rebuilt automatically after migrations.

Documentation

Full documentation is at trussphp.com.

Installation

For local use, install Truss as a dev dependency:

composer require albertoarena/laravel-truss --dev

To run Truss gated on staging or production, install it as a regular dependency instead. Dev dependencies are excluded from composer install --no-dev builds, so a --dev install never reaches a production deploy and /truss returns 404 there:

composer require albertoarena/laravel-truss

Requires PHP 8.3+ and Laravel 12+. The service provider is auto-discovered, so there is nothing to publish to get started.

Quick start

By default Truss is enabled in the local environment only. Start your app and visit:

/truss

To use Truss in a non-local environment you must both enable it and authorize the viewers. See Authorization.

Multiple connections

Out of the box Truss visualizes your application's default database connection. If your app spans more than one connection, for example a main database alongside a separate module database, list the connections you want to visualize under truss.connections:

// config/truss.php
'connections' => [
    'mysql' => [],
    'modules' => ['excluded_tables' => ['module_jobs']],
],

When two or more connections are configured, a connection picker appears in the dashboard toolbar. Switching it re-renders that connection's schema, and the selection is kept in the URL so a given view can be shared or bookmarked. Each connection is introspected against its own database only, so a shared server never shows tables that belong to another database.

The keys are Laravel connection names from config/database.php. Per-connection options mirror the global ones (such as excluded_tables), so you can hide different tables on each connection.

Schema doctor

php artisan truss:doctor (aliased truss:check) reviews your database structure for problems visible from structure alone: a table with no primary key, a foreign key with no index, duplicate indexes, money stored as a float, and more. It is deterministic and structure-only, with no AI and no network call, so it is safe to run in CI.

php artisan truss:doctor
php artisan truss:doctor --connection=mysql --format=json
php artisan truss:doctor --preset=strict --fail-on=warning

It exits 0 when clean, 1 when a finding is at or above the --fail-on level (default error), and 2 on a bad option or a snapshot error, so a migration that introduces a problem can fail the build. Presets (recommended, strict, none), per-rule severity and enable / disable, ignore patterns, and the fail level are all configurable under truss.doctor. See the configuration reference.

Every finding carries a stable code (e.g. TRUSS-IDX-001) shown in both the command and the panel; the schema doctor guide lists all the rule codes and what each checks.

Structure only: it reads the same cached snapshot the diagram uses and never queries row data.

In the dashboard

The same findings show in the dashboard, under the name Health: the command is truss:doctor, and the dashboard front end for it is the heart icon in the toolbar labelled "Health". Same feature, same findings. The Health panel lists them grouped by table, and every table with a problem carries a small severity badge on the diagram, so you can see what needs attention at a glance. Open the panel to read the findings, click a table to focus it, or click the marked column to see the finding for that field. Heuristic (lower-confidence) findings are marked as such.

It rides the schema endpoint the diagram already loads, so there is no extra request. Two switches control it under truss.doctor:

`dashboard` (env `TRUSS_DOCTOR_DASHBOARD`, default on): show the Health panel at all. When off, the dashboard never receives any findings and the CLI is untouched.
`flag_tables` (env `TRUSS_DOCTOR_FLAG_TABLES`, default on): always badge tables with findings on the diagram, even with the panel closed. Turn it off to keep the diagram clean and surface findings only when the panel is open.

Schema export

php artisan truss:export writes your database structure to a standard format for CI, tooling, and version control. It is the command-line counterpart to the dashboard's export button, generated from PHP so it does not need a human with the diagram open. Deterministic and structure-only, with no network call, so it is safe in CI and commit hooks.

php artisan truss:export                                  # DBML to stdout
php artisan truss:export --format=json                    # dbml, json, csv, markdown, or mermaid
php artisan truss:export --format=dbml --output=docs/schema.dbml
php artisan truss:export --tables=orders,order_lines      # only these (config exclusions still apply)
php artisan truss:export --connection=mysql --exclude=telemetry

Output goes to stdout by default so it pipes cleanly; --output writes a file. The output is deterministic: the same schema always produces the same bytes, whatever order the database reports its tables in. That is what makes the CI drift-check reliable:

# Fail the build if the committed schema file is out of date
php artisan truss:export --format=dbml --output=docs/schema.dbml --check

--check regenerates the export, compares it against --output, writes nothing, and exits non-zero when they differ, so a migration that changes the schema without refreshing the committed file fails the build. Exit codes: 0 written or up to date, 1 --check found drift, 2 a usage or runtime error (unknown format, unwritable path, an unmanaged connection, --check without --output, or no tables matched the filters). Add --fresh to rebuild the cached snapshot before exporting.

Config excluded_tables always wins over --tables, so the export never exposes a table the dashboard hides. Structure only: it reads the same cached snapshot the diagram uses and never queries row data.

Theming

Truss ships a light and dark "blueprint" theme. To match the app it is embedded in, redefine its colours and fonts from config under truss.theme. Everything is optional: you set a few semantic knobs and the rest stay on the default, so a handful of values re-skins the whole dashboard (chrome and diagram) in both light and dark.

Prefer to design it visually? The theme builder lets you dial in colours and fonts against a live dashboard preview and copy the config block straight into config/truss.php.

If you have not published the config yet (Truss works fine without it), publish it first with php artisan vendor:publish --tag=truss-config, then edit the theme block:

// config/truss.php
'theme' => [
    'fonts' => [
        'sans' => 'Inter, system-ui, sans-serif',
    ],
    'colors' => [
        'light' => [
            'accent' => '#3730a3',
            'background' => '#ffffff',
        ],
        'dark' => [
            'accent' => '#a5b4fc',
            'background' => '#0b1020',
        ],
    ],
],

The colour knobs are accent, accent-secondary, background, surface, surface-alt, text, muted, and border; each maps onto the tokens it paints (accent, for instance, covers headings, primary-key badges, entity borders, and the focus ring). Set a knob under both light and dark to theme both modes, or omit dark to theme light only. Colours accept hex, rgb() / hsl(), or a CSS colour keyword; fonts are family names only, so name a font your app already loads or a system font (Truss serves no font files here).

The overrides are delivered as a same-origin stylesheet, so a strict Content-Security-Policy still needs only style-src 'self' (no inline styles), and a default install with no custom theme makes no extra request. Each value is validated before it is emitted, so an invalid value is ignored and falls back to the default rather than breaking the sheet. Contrast is yours to check: a custom palette can fail accessibility, so verify both modes against WCAG AA.

Storage

Truss keeps its schema snapshot in the cache, which is derived and disposable. The one thing it writes to disk is the schema-diff baseline: a structure-only JSON file (never row data) recorded after each migration so the diff can show what changed. It lives at truss/baselines/{connection}.json on the disk set by truss.diff.disk (the default disk otherwise), is safe to delete, and is worth gitignoring alongside storage/. To turn the feature off entirely so nothing is written to disk, set TRUSS_DIFF_ENABLED=false (or truss.diff.enabled to false).

Security

Truss exposes structure only and never queries row data. Access is protected by the fixed viewTruss gate. If you discover a security issue, please email me@albertoarena.it rather than opening a public issue.