sirix / cycle-orm-factory
Cycle ORM Factories for Mezzio
Requires
- php: ~8.1.0 || ~8.2.0 || ~8.3.0 || ~8.4.0
- composer/package-versions-deprecated: ^1.11.99
- cycle/annotated: ^4.2
- cycle/database: ^2.11
- cycle/entity-behavior: ^1.3
- cycle/entity-behavior-uuid: ^1.2
- cycle/migrations: ^4.2.5
- cycle/orm: ^2.9
- cycle/schema-migrations-generator: ^2.3
- laminas/laminas-cli: ^1.11.0
- psr/cache: ~1.0.0 || ~2.0.0. || ~3.0.0
Requires (Dev)
- ergebnis/composer-normalize: ^2.39
- mockery/mockery: ^1.6
- phpstan/extension-installer: ^1.3
- phpstan/phpstan: ^1.10
- phpstan/phpstan-mockery: ^1.1
- phpunit/phpunit: ^10.5 || ^11.5
- roave/security-advisories: dev-master
- symfony/cache: ^6.3 || ^7.2
- symfony/filesystem: ^6.3 || ^7.2
README
Migration Guide: Cycle ORM Factory v1 to v2
This package provides factories for integrating Cycle ORM into the Mezzio framework, providing seamless setup and configuration.
Installation
composer require sirix/cycle-orm-factory
Configuration
Create a configuration file, for example, config/autoload/cycle-orm.global.php:
<?php declare(strict_types=1); use Cycle\Database\Config; use Psr\Cache\CacheItemPoolInterface; use Sirix\Cycle\Enum\SchemaProperty; return [ 'cycle' => [ 'db-config' => [ 'default' => 'default', 'databases' => [ 'default' => [ 'connection' => 'mysql', ] ], 'connections' => [ 'mysql' => new Config\MySQLDriverConfig( connection: new Config\MySQL\TcpConnectionConfig( database: 'cycle-orm', host: '127.0.0.1', port: 3306, user: 'cycle', password: 'password' ), reconnect: true, timezone: 'UTC', queryCache: true, ), ] ], 'migrator' => [ 'directory' => 'db/migrations', 'table' => 'migrations' ], 'entities' => [ 'src/App/src/Entity', // The 'entities' configuration must always be present and point to an existing directory, even when working with manual entities. ], 'schema' => [ 'property' => SchemaProperty::GenerateMigrations, 'cache' => [ 'enabled' => true, 'key' => 'cycle_cached_schema', // optional parameter 'service' => CacheItemPoolInterface::class, // optional parameter if psr container have 'cache' CacheItemPoolInterface service ] ], ], ];
Migrator Configuration
'migrator' => [ 'directory' => 'db/migrations', 'table' => 'migrations', ],
directory: Specifies the directory where the migration files will be stored.table: Specifies the name of the table used to store migration information.
Entities Configuration
'entities' => [ 'src/App/src/Entity', ],
- Specifies the directory in which your entity classes are located.
Manual mapping schema definitions
You can define manual mapping schema definitions for your entities. This is useful when you need to customize the schema for a specific entity. For example, you can define the table name, primary key, columns, typecast handlers, typecasts, and relations for an entity.
<?php /** * Example of a Cycle ORM schema configuration. * Use this template to define your entities, relationships, and database mappings. * Note: This configuration must be placed within the 'schema' => ['manual_mapping_schema_definitions'] array. */ use Cycle\ORM\Relation; use Cycle\ORM\SchemaInterface; return [ 'cycle' => [ 'schema' => [ 'manual_mapping_schema_definitions' => [ 'example_entity' => [ // Entity class for mapping SchemaInterface::ENTITY => YourEntity::class, // Database and table name for the entity SchemaInterface::DATABASE => 'your-database', SchemaInterface::TABLE => 'your_table_name', // Primary key column SchemaInterface::PRIMARY_KEY => 'id', // Column mappings: database columns to entity properties SchemaInterface::COLUMNS => [ 'id' => 'id', 'name' => 'name', 'createdAt' => 'created_at', 'updatedAt' => 'updated_at', ], // Typecasting for fields SchemaInterface::TYPECAST => [ 'id' => 'int', 'createdAt' => 'datetime', 'updatedAt' => 'datetime', ], // Optional: Custom typecast handlers SchemaInterface::TYPECAST_HANDLER => YourTypecastHandler::class, // Relationships definition SchemaInterface::RELATIONS => [ 'relatedEntities' => [ Relation::TYPE => Relation::HAS_MANY, // Relation type Relation::TARGET => RelatedEntity::class, // Target entity class Relation::SCHEMA => [ Relation::CASCADE => true, // Cascade updates/deletes Relation::INNER_KEY => 'id', // Local key in this entity Relation::OUTER_KEY => 'related_entity_id', // Foreign key in the related entity Relation::WHERE => [ 'status' => 'active', // Optional filter for the relation ], ], ], 'anotherEntity' => [ Relation::TYPE => Relation::BELONGS_TO, Relation::TARGET => AnotherEntity::class, Relation::SCHEMA => [ Relation::CASCADE => true, Relation::INNER_KEY => 'another_entity_id', Relation::OUTER_KEY => 'id', ], ], ], ], ], ], ], ];
See the Cycle ORM documentation for more information on manual mapping schema definitions.
Schema Configuration
'schema' => [ 'property' => SchemaProperty::GenerateMigrations, 'cache' => [ 'enabled' => true, 'key' => 'cycle_orm_cached_schema', 'service' => CacheItemPoolInterface::class, ], ],
property: Configures the schema property, options includenull,SchemaProperty::SyncTables, orSchemaProperty::GenerateMigrations.cache.enabled: Enables or disables caching of the generated schema.cache.key: Specifies the key used for storing the schema cache. This is optional and can be left empty if not needed.cache.service: Defines the PSR-6CacheItemPoolInterfaceservice to be used for schema caching. This allows integration with various caching mechanisms supported in your application. If left out, the default service (with name 'cache') from the container will be utilized if configured.
Schema Property Options
SchemaProperty::SyncTables
The SyncTables option synchronizes the database tables based on the provided entity classes. It ensures that the tables match the structure defined in the entity classes. This can be useful during development when the database schema evolves along with your application.
SchemaProperty::GenerateMigrations
The GenerateMigrations option is used to automatically generate migration files based on changes detected in your entity classes. When enabled, the ORM analyzes the differences between the current database schema and the defined entities. It then generates migration files to apply these changes, making it easier to version and manage your database schema changes.
Select the appropriate SchemaProperty option based on the requirements of your project. Customize the configuration to your needs and enjoy the seamless integration of Cycle ORM with Mezzio.
- Note: The schema properties (e.g., SyncTables, GenerateMigrations) work only with annotated entities.
- Ensure that your entity classes are properly annotated to leverage these features.
Use in your project
$container->get('orm'); // Cycle\ORM\ORM $container->get('dbal'); // Cycle\Database\DatabaseInterface $container->get('migrator'); // Cycle\Migrations\Migrator
These factories provide the necessary components to work seamlessly with Cycle ORM within the Mezzio Framework. Customize the configuration to meet the needs of your project.
For more information about Cycle ORM, see the Cycle ORM documentation.
Migrator Commands
The Sirix\Cycle\Command\Migrator namespace provides three commands for managing database migrations using Cycle ORM. These commands are intended for use with the laminas-cli tool.
1. cycle:migrator:run Command
Description
The cycle:migrator:run command performs the necessary database migration steps, applying changes specified in migration files to synchronize your database schema.
Usage
php vendor/bin/laminas cycle:migrator:run
Options
This command has no additional options.
2. cycle:migrator:rollback Command
Description
The cycle:migrator:rollback command undoes the changes made by the last migration, reverting your database schema to its previous state.
Usage
php vendor/bin/laminas cycle:migrator:rollback
Options
This command does not have any additional options.
3. cycle:migrator:generate Command
Description
The cycle:migrator:generate command generates a new empty migration file in the migration directory.
Usage
php vendor/bin/laminas cycle:migrator:generate PascalCaseMigrationName
Options
migrationName: The name of the migration file to be created. This should be in PascalCase format.
Note: Make sure that you have correctly configured the database connection and migrations settings in your project's configuration file.
For more information about using migrations with Cycle ORM, see the Cycle ORM Documentation.
4. cycle:cache:clear Command
Description
The cycle:schema:cache:clear command clears the cached Cycle ORM schema configuration, forcing the ORM to
regenerate it on the next application run. This can be useful during development when changes to entity definitions or
configurations have been made, and you want to ensure fresh schema generation.
Usage
php vendor/bin/laminas cycle:cache:clear
Options
This command does not have any additional options.
Cache Configuration Example
You can create a Symfony Cache Filesystem Adapter for your application like this:
<?php declare(strict_types=1); use Symfony\Component\Cache\Adapter\FilesystemAdapter; return [ 'dependencies' => [ 'factories' => [ 'Cache\Symfony\Filesystem' => function () { // Create a Symfony Cache File Adapter instance return new FilesystemAdapter( 'cycle', // Namespace prefix for cache keys 0, // Default TTL of items in seconds (0 means infinite) 'data/cycle/cache' // Absolute or relative directory for cache files storage ); }, ], ], ];
This configuration creates a Filesystem Cache Adapter with the following parameters:
'cycle': A namespace prefix for cache keys, helping to avoid key collisions0: Default Time-To-Live (TTL) set to infinite, meaning cached items won't expire automatically'data/cycle/cache': Directory where cache files will be stored
The cache configuration will look like this:
'cache' => [ 'enabled' => true, 'key' => 'cycle_orm_cached_schema', 'service' => 'Cache\Symfony\Filesystem'; }, ],