Cornerstone Laravel Package

Getting Started

• Install the package: composer require shipwelldev/cornerstone.
• Publish configuration and migrations: php artisan vendor:publish --tag=cornerstone-config and php artisan vendor:publish --tag=cornerstone-migrations.
• Run migrations to add snowflake ID columns where needed.
• Update your App\Models\User model to use the snowflake ID trait (e.g., HasSnowflakeIds) and ensure its primary key is a bigInteger (not auto-increment). v0.5.0 makes this mandatory for the default User model.
• Generate your first model: php artisan cornerstone:model Post. The generated model will include snowflake ID support and comply with architecture coverage.
• Run the architecture coverage test suite: php artisan test --group=architecture (or the package’s dedicated command) to verify all models use snowflake identifiers.

First use case: scaffold a new domain model with a snowflake primary key and immediately validate that your entire application (including User) passes the architecture rules.

Implementation Patterns

• Always use the Cornerstone generator for new models to ensure snowflake IDs and architecture rules are applied consistently.
• For existing models, manually add the snowflake trait and change the primary key column type to unsignedBigInteger (or bigInteger if signed). Then run architecture tests to catch any misses.
• When defining relationships, use unsignedBigInteger for foreign keys that reference snowflake IDs. Update migrations accordingly.
• Publish and customize stubs (php artisan vendor:publish --tag=cornerstone-stubs) to inject project-specific base classes, traits, or naming conventions into generated models.
• Include architecture coverage tests in CI to enforce snowflake ID usage on every model, including the default User model.
• The dependency updates in v0.5.0 (Livewire, Pest, Pest Browser, Mockery, Laravel Pint, Vite plugin, concurrently) are internal to the package. You can safely upgrade your application’s versions of these tools; the package is tested against the latest compatible releases.
• Integrate with existing authentication scaffolding by ensuring the User model uses snowflakes; if you rely on Laravel’s default migrations, replace the id() column with $table->bigInteger('id')->primary() and configure the model accordingly.

Gotchas and Tips

• v0.5.0 is a breaking change: any existing model (including User) that does not use snowflake identifiers will fail architecture coverage. Audit all models before upgrading.
• Converting an existing auto-increment User table to snowflakes is non-trivial. For production data, plan a migration that maps old IDs to new snowflake IDs, or start with a fresh database in development.
• Snowflake ID generation typically requires configuration (worker ID, datacenter ID, epoch). Check config/cornerstone.php and set environment-specific values to avoid collisions across multiple app instances.
• Architecture coverage is strict: it checks every generated model and the default User model. Use the test output to identify non-compliant models, then add the trait and adjust the migration.
• If you see errors referencing “Cornerstone support 0.3”, ensure the underlying support package is at the required version. v0.5.0 expects support 0.3.
• Extension point: bind a custom model generator implementation in a service provider if you need to change generation logic beyond what stubs allow.
• Debugging: run the architecture test suite with verbose output (php artisan test --group=architecture -v) to see exactly which models violate the snowflake requirement. Also verify that your User model’s $keyType and $incrementing properties are set correctly ('int' and false).