Weave Code
Annotated Laravel Package
cycle/annotated
Define Cycle ORM entity schemas using PHP attributes instead of annotations or config. Map columns, primary keys, and HasOne, HasMany, and BelongsTo relations directly in your entity classes.
Cycle ORM Annotated Entities generator
Frequently asked questions about Annotated
- How do I install cycle/annotated in a Laravel project?
- Install cycle/annotated with Composer, but it is not a drop-in Laravel package. You must also install and bootstrap Cycle ORM and configure its service provider in your Laravel application. The package then lets you define Cycle ORM schemas with PHP attributes instead of annotations or config files.
- Does cycle/annotated work with Laravel's Eloquent ORM?
- No. cycle/annotated is built for Cycle ORM, not Laravel's Eloquent ORM, and Eloquent models are not compatible with its attribute schema. Using it in Laravel means replacing Eloquent persistence or adding a facade/repository layer, and you should also adapt Laravel query builder usage.
- What PHP version does cycle/annotated require?
- cycle/annotated requires PHP 8.1 or newer because it relies on PHP attributes. That requirement can block legacy Laravel projects running older PHP versions. Confirm your Laravel version and deployment runtime support PHP 8.1+ before adopting it.
- How do I define HasMany and BelongsTo relations with PHP attributes?
- Use attributes such as #[HasOne(target: Address::class)], #[HasMany(target: Post::class)], and #[BelongsTo(target: User::class)] on entity properties. Cycle ORM reads those attributes during schema compilation to map the relations. You still need to model the owning and inverse sides correctly and test relation configuration.
- Can cycle/annotated handle STI, JTI, embedded entities, and polymorphic relations?
- Yes, the package supports advanced Cycle ORM schema features such as STI/JTI inheritance, polymorphic relations, embedded entities, and generated fields. Those features are useful for complex domain models but can be over-engineering for simple Laravel applications. Validate that your team actually needs them before replacing Eloquent.
- How do I test Cycle ORM annotated entities in Laravel with PHPUnit or Pest?
- cycle/annotated works with PHPUnit or Pest, but Laravel's Eloquent-specific helpers such as create() and factory() will not apply to Cycle ORM entities. You will need to test through Cycle ORM repositories, schema compilation, and your own fixtures. Plan for adjustments to Laravel's default testing patterns.
- What are the production risks of using cycle/annotated in Laravel?
- Production risks include tight coupling to Cycle ORM, debugging deeply nested relation attributes, and schema errors that may surface only at runtime or during compilation. The package also does not provide Laravel-specific features like timestamps, softDeletes, or observer events out of the box. You will need custom annotations or workarounds and a rollback plan.
- Is cycle/annotated a good alternative to Doctrine ORM annotations?
- cycle/annotated is not a drop-in alternative to Doctrine ORM annotations; it is the attribute-based schema layer for Cycle ORM. It reduces boilerplate compared with annotation-based approaches, but only if you are already using or evaluating Cycle ORM. For teams committed to Eloquent or Doctrine, it is usually not the right fit.
- How do I migrate from Eloquent models to Cycle ORM annotated entities?
- Migrate gradually per module: replace Eloquent models with Cycle ORM annotated entities, then replace Laravel query builder calls with Cycle ORM queries or a repository abstraction. Update schema generation and migrations to match the annotated entities, and validate third-party packages that depend on Eloquent. Keep a rollback plan because the migration can be disruptive.
- How is cycle/annotated maintained, and does it support Laravel long-term?
- cycle/annotated is maintained as part of the Cycle ORM ecosystem and evolves independently of Laravel. Its compatibility depends mainly on Cycle ORM and PHP versions rather than Laravel release cycles, so check release cadence and open issues before committing. Teams should assign ownership for upgrades and have a fallback if Cycle ORM compatibility stalls.
Weaver
How can I help you explore Laravel packages today?