README

Generate Laravel Eloquent models and migration files directly from your DBML (Database Markup Language) diagrams, accelerating Laravel development and streamlining your schema-to-code workflow.

📰 Featured on Laravel News — the official community blog for Laravel developers!

🚀 Motivation

Tired of manually writing Laravel Eloquent models and migration files from your database diagrams? This package automates the process, letting you focus on building features rather than repetitive boilerplate code. Say goodbye to manual schema-to-code conversion and embrace a faster, more efficient Laravel development workflow.

✨ Features

DBML to Laravel Models: Automatically generate Eloquent models with fillable properties, hidden attributes, and defined relationships (one-to-one, one-to-many, many-to-many).
DBML to Migration Files: Generate clean and accurate migration files with proper data types, nullability, default values, and foreign key constraints, directly from your DBML schema.
Customizable Stubs: Easily modify the default model and migration stubs to align with your project's coding style and specific requirements.
Relationship Parsing: Intelligently parses DBML relationships to create correct Eloquent relationship methods (e.g., hasMany, belongsTo, belongsToMany).
Casts Support: Automatically adds common Eloquent casts (e.g., JSON to arrays, timestamps to datetime objects) based on DBML column types.
Incremental Sync: Run dbml:sync to generate alter migrations and patch models based on schema changes — no need to regenerate everything from scratch.

📦 Installation

To get started with the DBML to Laravel Eloquent Generator, follow these simple steps:

Require the package via Composer:

composer require egyjs/dbml-to-laravel --dev

Publish the customizable stubs (optional, but recommended):

php artisan vendor:publish --tag=dbml-to-laravel-stubs

This command will publish the stub files to stubs/dbml-to-laravel/, allowing you to customize the generated code.

Requirements

Laravel 8.x+
PHP 8.0+
Node.js 18+ runtime (the DBML parser is pre-bundled, so you never need to run npm install in your project)

💡 Usage

Once installed, you can generate your Laravel models and migrations from a DBML file using the dbml:generate Artisan command. (generate:dbml also works as a legacy alias.)

Create your DBML schema file (e.g., database/schema.dbml).
Example database/schema.dbml:

   Table users {  
     id int [pk, increment]  
     name varchar  
     email varchar [unique]  
     password varchar  
     created_at datetime  
     updated_at datetime  
   }

   Table posts {  
     id int [pk, increment]  
     user_id int [ref: > users.id]  
     title varchar  
     content text  
     created_at datetime  
     updated_at datetime  
   }

   Ref: posts.user_id > users.id

Run the Artisan command:

php artisan dbml:generate database/schema.dbml

Replace database/schema.dbml with the actual path to your DBML file.

Expected Output

After running the command, the package will generate:

Eloquent Models: In your app/Models directory (e.g., app/Models/User.php).
Migration Files: In your database/migrations directory (e.g., 2023_01_01_000000_create_posts_table.php).

Example Generated app/Models/Post.php:

<?php

namespace App\Models;

use Illuminate\Database\Eloquent\Factories\HasFactory;
use Illuminate\Database\Eloquent\Model;
use Illuminate\Database\Eloquent\Relations\BelongsTo;

class Post extends Model
{
    use HasFactory;

    /**
     * The attributes that are mass assignable.
     *
     * @var array<int, string>
     */
    protected $fillable = [
        'user_id',
        'title',
        'content',
    ];

    /**
     * Get the user that owns the Post.
     */
    public function user(): BelongsTo
    {
        return $this->belongsTo(User::class);
    }
}

Example Generated database/migrations/2023_01_01_000000_create_posts_table.php:

<?php

use Illuminate\Database\Migrations\Migration;
use Illuminate\Database\Schema\Blueprint;
use Illuminate\Support\Facades\Schema;

return new class extends Migration
{
    /**
     * Run the migrations.
     */
    public function up(): void
    {
        Schema::create('posts', function (Blueprint $table) {
            $table->increments('id');
            $table->integer('user_id');
            $table->string('title');
            $table->text('content');
            $table->timestamps();

            $table->foreign('user_id')->references('id')->on('users')->onDelete('cascade');
        });
    }

    /**
     * Reverse the migrations.
     */
    public function down(): void
    {
        Schema::dropIfExists('posts');
    }
}

Incremental Sync

After your initial generate:dbml, you can iterate on your DBML schema and generate only the changes:

php artisan dbml:sync database/schema.dbml

This command:

Reads the snapshot (.dbml-sync.json) created by generate:dbml
Compares it against the current DBML file
Generates alter migrations for added/modified/dropped columns, indexes, and foreign keys
Generates create migrations for new tables and drop migrations for removed tables
Patches existing Eloquent models within @dbml-sync markers (fillable, casts, relations, table property)

Use --force to skip confirmation prompts:

php artisan dbml:sync database/schema.dbml --force

Workflow example:

# Initial generation — creates models, migrations, and snapshot
php artisan dbml:generate database/schema.dbml

# ... edit schema.dbml (add columns, new tables, etc.)

# Incremental sync — only the changes
php artisan dbml:sync database/schema.dbml

Model markers. Generated models include @dbml-sync markers that the patcher targets:

class User extends Model
{
    // @dbml-sync:fillable
    protected $fillable = ['name', 'email'];
    // @enddbml-sync:fillable

    // @dbml-sync:casts
    protected $casts = ['email_verified_at' => 'datetime'];
    // @enddbml-sync:casts

    // @dbml-sync:relations
    public function posts() { return $this->hasMany(Post::class); }
    // @enddbml-sync:relations
}

Code outside these markers is never touched by dbml:sync.

⚙️ Customization

You can modify the generated model and migration templates by editing the stub files located in stubs/dbml-to-laravel/ after publishing them. This allows you to tailor the output to your specific project needs, including adding custom traits, interfaces, or modifying default property definitions.

Updating the bundled DBML parser (contributors only)

The published package already includes a fully bundled parser, so consumers never have to install Node dependencies. If you change bin/parse-dbml.js, run the following before opening a PR:

npm install
npm run build-parser

Commit both the updated source file and the generated bin/parse-dbml.runtime.cjs artifact so downstream users continue to benefit from the prepackaged parser.

🤝 Contributing

We welcome contributions! Please see our CONTRIBUTING.md for details on how you can help improve this project. Whether it's bug fixes, new features, or documentation improvements, your input is valuable.

Contributor Documentation

Detailed contributor guides live in the docs/ directory:

Document	Description
Getting Started	Clone to first green test
Architecture	3-stage pipeline, component map, data flow
Adding Features	Recipe-style "how do I add X" guides
Stubs	Stub placeholders, override paths, customization
Parser Bundle	Node parser, esbuild bundle, JSON payload
Testing	Pest patterns, fixtures, adding test cases
Gotchas	Compatibility matrix, silent edge cases, traps

❓ Support

For questions, bug reports, or feature requests, please open an issue on the GitHub Issues page. We'll do our best to respond promptly.

🎉 This package was featured by Laravel News. If you find it useful, give it a ⭐ on GitHub and share it with your Laravel team!

📄 License

This project is open-sourced software licensed under the MIT License.

egyjs / dbml-to-laravel

Maintainers

Package info

Fund package maintenance!

Statistics

Security