Weave Code
Schema Builder Laravel Package
cycle/schema-builder
Cycle ORM Schema Builder lets you define and configure your ORM and database schema programmatically using annotations or custom generators. Register entities, map fields and columns, link tables, then compile the schema for Cycle ORM.
Declarative schema generation for Cycle ORM
Frequently asked questions about Schema Builder
- How do I install cycle/schema-builder in a Laravel application?
- Install it with composer require cycle/schema-builder; this also pulls in the Cycle ORM and Cycle Database requirements. The package is framework-agnostic and does not appear to ship a Laravel service provider, so you typically bind the DatabaseManager, Registry, and Compiler in your own Laravel service provider. You then register entities and link tables before compiling the schema. Check PHP 8.1+ compatibility with your Laravel version first.
- Does cycle/schema-builder work with Laravel and Eloquent?
- It works inside a Laravel application, but it is built for Cycle ORM, not Eloquent. You use Cycle Database connections, Cycle Schema Registry, and Cycle ORM's Schema object; Eloquent models and Laravel's schema builder are separate. You can run both in one app, but you must keep the two ORMs' mappings and connections consistent. If your app is Eloquent-first, adopting this package means adopting Cycle ORM for that domain.
- What PHP and Laravel versions does cycle/schema-builder support?
- The package requires PHP 8.1 or newer according to the assessment, and recent releases address PHP 8.4 deprecations. Laravel version support is not declared by the package because it is framework-agnostic; compatibility depends on your Laravel version running on PHP 8.1+. Test on your exact Laravel and PHP combination, especially if you use PHP 8.4.
- How do I define an entity and its fields with cycle/schema-builder?
- Create a Cycle\Schema\Definition\Entity, set its role and class, then add Definition\Field objects through getFields()->set(). Each field can specify a type such as primary or string(32), a column name, and primary-key status. Register the entity with the Registry and link it to a database table. The Compiler then turns those definitions into the ORM schema.
- How do I link a table and compile the schema with cycle/schema-builder?
- After registering entities in Cycle\Schema\Registry, call linkTable($entity, 'default', 'users') to associate an entity with a database and table. Then run (new Cycle\Schema\Compiler())->compile($registry) to produce the schema array. Inject that array into Cycle ORM via new Cycle\ORM\Schema($schema) and with(schema: ...). The Registry must be backed by a configured Cycle Database DatabaseManager.
- Can I use PHP attributes or annotations instead of writing definitions manually?
- Yes. The README says Schema Builder can configure your ORM and database schema via annotations (attributes) or custom generators. The programmatic Definition and Field API is the lower-level path; the cycle/annotated package provides attribute-based workflows. Custom generators let you adapt definitions for conventions or edge cases. Use annotations for developer ergonomics and generators when you need reusable logic.
- Is cycle/schema-builder a replacement for Laravel migrations?
- It can replace migration-driven schema management for the Cycle ORM portion of your app, because schema is defined in PHP and compiled into an ORM schema. It is not a drop-in replacement for Laravel migrations across an Eloquent application. The assessment notes it complements Cycle Migrations or can replace them entirely. Keep Laravel migrations for tables and features outside Cycle ORM's declarative model.
- How should I test cycle/schema-builder schema changes before production?
- Compile the schema in CI and compare the generated DDL or schema diff before applying changes. This is especially important for patch upgrades such as 2.12.2, which can change foreign-key nullability for relations sharing a generated FK. Use an in-memory SQLite connection or a disposable test database to validate registration, field mapping, and compilation. Add assertions for expected columns, keys, and nullability.
- What changed in cycle/schema-builder 2.12.2 for shared foreign keys?
- Version 2.12.2 fixes foreign-key nullability when multiple relations share a single generated foreign-key column. The compiler now uses the most permissive nullability across all sharing relations, so a nullable relation no longer produces a NOT NULL constraint. There are no API or config changes, but the generated DDL can differ from 2.12.1. Run a schema diff before upgrading if your relations share generated FKs.
- Is cycle/schema-builder production-ready and actively maintained?
- It is an official Cycle ORM package with a focused feature set, but adoption is narrow: the assessment reports around 15 GitHub stars and no dependents. Activity has continued beyond the previously recorded June 2026 release, with v2.12.2 shipped on 2026-10-05, so the line is patched rather than dormant. For production, validate maintenance cadence, test PHP 8.4 compatibility, and weigh Cycle ORM lock-in. Alternatives include Doctrine Migrations, Laravel Schema Builder, and Cycle Migrations depending on your ORM strategy.
Weaver
How can I help you explore Laravel packages today?