draftsmaninc / draftsman

0.2.0 2026-07-27 23:17 UTC

Requires

• php: ^8.3
• illuminate/contracts: ^12.0||^13.0
• spatie/laravel-package-tools: ^1.16

Requires (Dev)

• laravel/pint: ^1.14
• nunomaduro/collision: ^8.1.1
• orchestra/testbench: ^11.0||^10.0
• pestphp/pest: ^4.0
• pestphp/pest-plugin-arch: ^4.0
• pestphp/pest-plugin-laravel: ^4.0

Suggests

• spatie/browsershot: Enables png, jpeg and pdf output from draftsman:render (also needs Puppeteer/Chrome)

proprietary

• Ron Northrip

• laravel
• draftsman

Published on Packagist.org on 2026-11-07 15:06 UTC

README

A graphical tool that diagrams and edits Laravel eloquent models.

Requirements

• PHP 8.3+
• Laravel 12 or 13

Installation

You can install the package via composer:

composer require draftsmaninc/draftsman

You can publish the config file with:

php artisan vendor:publish --tag="draftsman-config"

This is the contents of the published config file:

return [

    /*
    |--------------------------------------------------------------------------
    | Package Settings
    |--------------------------------------------------------------------------
    |
    | Where Draftsman finds and keeps things in the host app. Every key here
    | has a consumer — runtime capabilities (like which render formats work)
    | are reported by the config API endpoint, not configured.
    |
    */
    'package' => [
        // Path (relative to project root) where models live.
        'models_path' => env('DRAFTSMAN_MODELS_PATH', app_path('Models')),
        // Path (relative to project storage) where snapshots are saved.
        'snapshot_path' => env('DRAFTSMAN_SNAPSHOT_PATH', storage_path('draftsman/snapshots/')),
        // Path where graph documents are saved. Lives in the project root
        // (not storage/) so graphs are version-controlled with the code,
        // mirroring Laravel Blueprint's draft-in-repo pattern.
        'graphs_path' => env('DRAFTSMAN_GRAPHS_PATH', base_path('draftsman')),
        // Explicit node/npm binaries for Browsershot renders. Web servers
        // often run with a minimal PATH that misses version-managed node
        // (nvm, Herd, volta) — set these when render/{slug}?format=… works
        // from the CLI but 500s over HTTP. Null = Browsershot's defaults.
        'node_binary' => env('DRAFTSMAN_NODE_BINARY'),
        'npm_binary' => env('DRAFTSMAN_NPM_BINARY'),
    ],
];

Usage

Open /draftsman in your app (e.g. http://your-app.test/draftsman). The bundled frontend reads your Eloquent models — including vendor models and pivot tables your relations reach — and lays them out as an interactive diagram. Graphs you save land as JSON documents in graphs_path (draftsman/ by default), so they are version-controlled with your code.

Rendering graphs

Any graph saved from the Draftsman UI (stored as <graphs_path>/<slug>.json, draftsman/ by default) can be rendered to a self-contained file:

php artisan draftsman:render teams                 # draftsman/teams.html
php artisan draftsman:render teams --format=png    # needs Browsershot, see below
php artisan draftsman:render teams --path=docs/erd.html

Format	Needs	Notes
html	nothing	Static, no JavaScript — safe to commit or serve anywhere
png / jpeg / pdf	Browsershot	Headless-Chrome capture of the same page
svg	—	Not available yet

The html format works everywhere with zero extra dependencies. For image and PDF output, opt in to Browsershot in the host app:

composer require spatie/browsershot
npm install puppeteer
npx puppeteer browsers install chrome-headless-shell   # the browser it drives

Keeping a rendered diagram in CI

Rendering the committed graph document on every push keeps a diagram in your repo (or build artifacts) that never drifts from the saved graph:

# .github/workflows/erd.yml
name: Render ERD
on:
  push:
    paths: ['draftsman/*.json']

jobs:
  render:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: shivammathur/setup-php@v2
        with: { php-version: '8.3' }
      - run: composer install --no-interaction --prefer-dist
      - run: php artisan draftsman:render teams --path=docs/erd.html
      - uses: stefanzweifel/git-auto-commit-action@v5
        with: { commit_message: 'Update rendered ERD' }

For png/pdf in CI, add Browsershot and Puppeteer before the render step:

      - run: composer require spatie/browsershot
      - run: npm install puppeteer
      - run: npx puppeteer browsers install chrome-headless-shell
      - run: php artisan draftsman:render teams --format=png --path=docs/erd.png

Support

If you're having problems with draftsman please feel free to reach out to use at [e-mail].

We might ask you to include a snapshot of your draftsman data using the snapshot tool.

php artisan draftsman:snapshot            # writes to snapshot_path
php artisan draftsman:snapshot --path=... # or a specific file/directory

Local Dev

Keep both the draftsman repo and the dev site in the same directory. Then install draftsman normally in the dev site. Then rename or delete the 'vendor/draftsmaninc/draftsman' directory. Then use a symlink to replace it with a connection to your local repo.

cd vendor/draftsmaninc
mv draftsman xxxdraftsman
ln -s ../../../draftsman
cd ../..

Testing

The test suite runs on Pest 4 against Laravel 12 and 13.

composer test

Built With

• Spatie's Package Skeleton
• Spatie's Package Tools
• AlpineFlow

Changelog

Please see CHANGELOG for more information on what has changed recently.

Contributing

Please see CONTRIBUTING for details.

Security Vulnerabilities

Please review our security policy on how to report security vulnerabilities.

Credits

• Ron Northrip
• Zac Hiller
• All Contributors

License

The Draftsman Package is Copyright (c) 2025 by Draftsman Incorporated. Please see the License File for more information.