README

gboquizosanchez/hew

Schema as source of truth for Laravel migrations

Where is the avatar column defined? In migration number 47. hew makes that a one-line answer.

Why hew?

Laravel migrations are append-only by design — great for versioning, painful for understanding the current state.

Problem	Without hew	With hew
"Does users have an avatar column?"	❌ Read through N migrations	✅ One glance at schema.php
Adding a column to an existing table	❌ Write migration by hand	✅ Add it to the schema, run hew:sync
Reviewing the full database structure	❌ Mental model from git history	✅ Single file, fluent API
CI check for uncommitted schema drift	❌ No built-in mechanism	✅ hew:diff exits 1 when changes pending
Accidental destructive migration	❌ Easy to do	✅ Impossible — hew never emits DROP

🚀 Features

• Single source of truth: database/schema.php is the canonical description of your database.
• Additive-only: hew never emits DROP COLUMN, RENAME COLUMN, or DROP TABLE. Removed columns produce warnings, not data loss.
• Fluent column API: Chainable modifiers — ->nullable(), ->unique(), ->default(), ->references() and more.
• Relation metadata: Declare hasMany, belongsTo, belongsToMany directly on the table definition. belongsToMany auto-generates the pivot table.
• CI-friendly: hew:diff exits 1 when changes are pending, making it trivially embeddable in pipelines.
• Zero runtime footprint: --dev only. No production dependency.

📦 Installation

composer require --dev gboquizosanchez/hew
php artisan vendor:publish --provider="Boquizo\Hew\HewServiceProvider"
cp vendor/gboquizosanchez/hew/database/schema.example.php database/schema.php

🔧 Usage

Define your schema

<?php
// database/schema.php

use Boquizo\Hew\Schema\Column;
use Boquizo\Hew\Schema\Schema;
use Boquizo\Hew\Schema\Table;

return Schema::define([

    Table::make('users')
        ->columns([
            Column::id(),
            Column::string('name'),
            Column::string('email')->unique(),
            Column::string('password')->hidden(),
            Column::timestamps(),
        ])
        ->hasMany('posts')
        ->belongsToMany('roles'),        // auto-generates role_user pivot

    Table::make('posts')
        ->columns([
            Column::id(),
            Column::foreignId('user_id')->references('users'),
            Column::string('title'),
            Column::text('body'),
            Column::boolean('is_published')->default(false),
            Column::decimal('reading_fee', 10, 2)->nullable(),
            Column::timestamps(),
        ])
        ->belongsTo('users'),

]);

Check what would change

php artisan hew:diff

  New table: posts
  + id
  + user_id, foreignId, -> users
  + title, string
  + body, text
  + is_published, boolean
  + reading_fee, decimal, 10,2, nullable
  + created_at, updated_at

  No destructive changes will be applied automatically.

Generate the migrations

php artisan hew:sync

📋 Commands

hew:diff

Shows pending changes without writing any files. Exit code 0 if clean, 1 if changes are pending — useful in CI to detect uncommitted schema drift.

Flag	Description
--path	Path to a non-default schema.php

hew:sync

Runs the diff and generates migration files.

Flag	Description
--force	Skip the [Y/n] confirmation prompt
--dry-run	Alias for hew:diff — show diff only, generate nothing
--path	Path to a non-default schema.php

🗂️ Column reference

Types

Method	Blueprint equivalent
Column::id()	$table->id()
Column::string('name')	$table->string('name')
Column::text('body')	$table->text('body')
Column::integer('count')	$table->integer('count')
Column::bigInteger('amount')	$table->bigInteger('amount')
Column::decimal('total', 10, 2)	$table->decimal('total', 10, 2) — precision and scale required
Column::boolean('active')	$table->boolean('active')
Column::json('settings')	$table->json('settings')
Column::timestamp('paid_at')	$table->timestamp('paid_at')
Column::timestamps()	$table->timestamps() — shortcut for created_at + updated_at
Column::foreignId('user_id')	$table->foreignId('user_id')

Note: Column::enum() is not supported and throws UnsupportedColumnTypeException. Use Column::string()->cast(YourEnum::class) instead — hew stores it as VARCHAR in the database.

Modifiers

Modifier	Blueprint effect	Notes
->nullable()	->nullable()
->default($value)	->default($value)
->unique()	->unique()
->unsigned()	->unsigned()
->index()	->index()
->references('table')	->constrained('table')	Use on foreignId columns

🔗 Table reference

Table::make('users')
    ->columns([...])               // required — array of Column instances
    ->hasMany('posts')             // metadata only
    ->hasOne('profile')            // metadata only
    ->belongsTo('companies')       // warns if 'company_id' foreignId column is missing
    ->belongsToMany('roles')       // auto-generates pivot table role_user if absent

All relation methods are metadata only — they don't generate columns or migrations by themselves.

belongsToMany('roles') on users automatically generates a role_user pivot table (alphabetical) with the two foreignId columns when none exists.

🔒 Safety guarantees

hew never emits DROP COLUMN, RENAME COLUMN, or DROP TABLE.

Situation	What hew does
Column in schema, not in migrations	Generates migration to add it
Column in migrations, not in schema	Warning only — no migration
Column type changed	Warning only — no migration
Table in schema, not in migrations	Generates create_table migration

When you see a warning, write that migration by hand. The cost is one extra file. The benefit is hew:sync can never destroy your data.

🧪 Testing

composer test

This package uses Pest v4 with the Laravel plugin. Static analysis runs via PHPStan at level 10.

Troubleshooting

If you encounter issues:

1. Check the logs — Laravel logs may contain helpful error messages.
2. Verify requirements — Ensure PHP ^8.1 and Laravel 10–13 are met.
3. Clear cache — Run php artisan config:clear and php artisan cache:clear.
4. Open an issue — Report bugs or request features.

Contributing

Contributions are welcome! Please feel free to:

• 🐛 Report bugs via GitHub Issues
• 💡 Suggest features or improvements
• 🔧 Submit pull requests with bug fixes or enhancements
• 📖 Improve documentation or examples

Please make sure all tests pass and the code follows PSR-12 before submitting a PR.

Credits

• Author: Germán Boquizo Sánchez
• Contributors: View all contributors

📄 License

This package is open-source software licensed under the MIT License.

Made with ❤️ for the PHP · Laravel community