Blueprint Macro Laravel Package

Getting Started

cleaniquecoders/blueprint-macro extends Laravel's schema Blueprint with reusable column macros, so day-to-day you use it inside migrations rather than in application code.

1. Install into require (not require-dev — see Gotchas):

   composer require cleaniquecoders/blueprint-macro
   

   No manual provider registration is needed; package discovery boots the service provider that registers the macros on Illuminate\Database\Schema\Blueprint.

2. First place to look is the package's service provider and its macro registrations — that is the authoritative list of available macros for the version you installed. Skim it once, then keep the README handy as a cheat sheet.

3. First use case: replace a block of repeated boilerplate columns in a new migration with a single macro call, then run php artisan migrate:fresh against SQLite and against your real driver to confirm the generated DDL matches what you previously wrote by hand.

4. Verify registration quickly:

   php artisan tinker
   >>> array_keys(\Illuminate\Database\Schema\Blueprint::getMacros())
   

   If the list is empty, discovery is disabled or the provider failed to boot.

Version note (5.4.0): this release is about platform compatibility — Laravel 13 (^13.0 added to the illuminate constraints), PHPUnit 12, and Pest 4. There are no new macros, no deprecations, and no behavioural changes to existing ones, so upgrading from 5.3.x is a dependency bump rather than a migration task.

Implementation Patterns

Shorthand columns in Schema::create. The primary pattern is composing macros inside table definitions to keep migrations readable:

Schema::create('posts', function (Blueprint $table) {
    $table->id();
    $table->string('title');
    // macro-provided columns below — confirm names against the provider
    $table->publishDates();     // e.g. published_at / drafted_at pair
    $table->author();           // e.g. nullable morph or FK + index
    $table->timestamps();
    $table->softDeletes();
});

Wrap them in your own domain macros. If a three-column block repeats across migrations, register an app-level macro in a SchemaServiceProvider that calls the package macros plus your own columns. This keeps the package as a dependency of your conventions rather than spreading raw macro calls everywhere:

Blueprint::macro('auditable', function () {
    $this->timestamp('reviewed_at')->nullable();
    $this->foreignId('reviewed_by')->nullable()->constrained('users');
});

Use them as the single source of truth for column sets. Where a macro emits a matched pair (timestamp + flag, or FK + index), never hand-write half of it in a later migration — add a follow-up migration that uses the same macro or drop/re-add the set, otherwise schema drift creeps in silently.

Roll forward, not back. Treat macro output as an immutable schema decision. Once a migration using a macro has shipped, a future package version changing that macro's output will not retroactively alter production. Pin the package version in composer.json for any project where migrations are long-lived, and review the provider diff before a minor bump.

Testing. With 5.4.0 you can run the app's suite on PHPUnit 12 or Pest 4. The most valuable test is a DDL assertion: run migrations against a fresh in-memory SQLite database in setUp and assert Schema::hasColumns('posts', [...]) for anything a macro produces. That catches a macro rename or removal at CI time instead of at deploy time.

Integration with factories/seeders. Because macros only affect DDL, factories are unaffected — but if a macro creates a non-nullable column with no default, your existing factories will start failing on create(). Add the new attribute to the factory in the same commit as the migration.

Gotchas and Tips

• Install location matters. Migrations execute during deployment, so the package must be in require. A require-dev install passes locally and blows up on the production php artisan migrate.
• Macros are class-level static state. They live on the Blueprint class for the life of the PHP process. In long-running workers or test suites that boot multiple app instances, a macro registered by one provider is visible to another. If you need isolation, call Blueprint::flushMacros() in test teardown and re-boot, and be aware that flushing also removes macros registered by other packages.
• Debugging "Call to undefined method". This almost always means the provider did not boot: check php artisan about / bootstrap/cache/packages.php for the discovered provider, and remember that a stale bootstrap/cache/services.php after a deploy can hide a newly required package — run php artisan package:discover or composer dump-autoload.
• Config caching. Anything configurable is read at boot; after editing a published config file run php artisan config:clear. Under config:cache in production, a config change without a cache rebuild silently has no effect.
• Cross-database portability. Macros that emit raw SQL or driver-specific column types can behave differently on SQLite vs MySQL vs Postgres. Test migrate:fresh on SQLite for speed, but run at least one migration test on your production driver before relying on a macro.
• Column ordering. Macros append columns in the order they are called; there is no supported "insert after" for arbitrary positions on all drivers. Order your macro calls deliberately, or accept the column ends up at the end of the table.
• change() and macro columns. Modifying a macro-generated column later means naming it explicitly in ->change(). Keep a comment in the original migration noting which macro produced which columns so future-you can find them.
• Extension points. The cleanest way to adapt behaviour is your own Blueprint::macro wrappers in an app service provider that calls the package macros — do not edit vendor files or monkey-patch the package provider, since both are lost on the next composer update.
• Version pinning. Given 5.4.0 only touched constraints, CI, and dev dependencies (larastan, phpstan plugins, collision, phpunit.xml.dist), there is no runtime upgrade risk from 5.3.x. The risk is in your own toolchain: PHPUnit 12 and Pest 4 have their own breaking changes, so bump those in your app deliberately rather than letting a transitive constraint drag them in.
• Composer constraint conflicts. If your app is still on Laravel 10/11 and PHP 8.1, check the package's php and illuminate/* constraints before upgrading — 5.4.0 widened the illuminate range to include ^13.0, but that widening does not guarantee support for versions older than the package's stated floor.
• PHP version alignment. The 5.4.0 CI targets Laravel 12 on PHP 8.4 and 8.3. If you are on PHP 8.2 you are likely still fine, but that combination is not covered by the maintainer's matrix, so treat it as unsupported-by-CI and validate your own migration tests there.