README

此包提供 Laravel 与 Cycle ORM 的集成。我们支持 ORM 两个版本的集成。内部，它使用桥梁包，可以与几乎任何框架一起使用。

要求

PHP >= 8.0
Laravel 7, 8, 9

此包使用 Cycle ORM 1 或 2（分别对应分支 v1.x 和 v2.x）。

安装

通过 composer 安装包

composer require wakebit/laravel-cycle

发布配置 cycle.php

php artisan vendor:publish --provider="Wakebit\LaravelCycle\ServiceProvider" --tag=config

使用

在 database 配置部分配置数据库连接。如果你已经使用任何 Laravel 兼容的数据库驱动程序，则无需进行任何更改。它使用相同的 DB_* 环境变量。键的内容应返回一个 \Cycle\Database\Config\DatabaseConfig 实例。更多信息请查看这里。
在 tokenizer 部分配置实体所在路径。默认情况下，类定位器在 app 文件夹中查找它们。

定义实体

<?php

declare(strict_types=1);

namespace App\Entity;

use Cycle\Annotated\Annotation\Entity;
use Cycle\Annotated\Annotation\Column;

#[Entity]
class User
{
    #[Column(type: 'primary')]
    protected int $id;

    #[Column(type: 'string')]
    protected string $name;

    public function getId(): int
    {
        return $this->id;
    }

    public function getName(): string
    {
        return $this->name;
    }

    public function setName(string $name): void
    {
        $this->name = $name;
    }
}

你可以从容器中获取 DBAL、ORM 和实体管理器。使用示例

<?php

declare(strict_types=1);

namespace App\Http\Controllers;

use Cycle\Database\DatabaseProviderInterface;
use Cycle\ORM\EntityManagerInterface;
use Cycle\ORM\ORMInterface;
use Illuminate\Http\Response;

final class HomeController
{    
    public function __construct(
        private DatabaseProviderInterface $dbal,
        private EntityManagerInterface $em,
        private ORMInterface $orm,
    ) {
    }
    
    public function __invoke()
    {
        // DBAL
        $tables = $this->dbal->database()->getTables();
        $tableNames = array_map(fn (\Cycle\Database\TableInterface $table): string => $table->getName(), $tables);
        dump($tableNames);
        
        // Create, modify, delete entities using Transaction
        $user = new \App\Entity\User();
        $user->setName("Hello World");
        $this->em->persist($user);
        $this->em->run();
        dump($user);
        
        // ORM
        $repository = $this->orm->getRepository(\App\Entity\User::class);
        $users = $repository->findAll();
        dump($users);
        
        $user = $repository->findByPK(1);
        dump($user);
    }
}

更多内容请参阅官方 Cycle ORM 文档。

与 ORM 模式工作

模式可以编译并存储在缓存中（推荐用于生产使用）。你可以在 cycle.orm.schema 配置键中指定缓存驱动程序。

use Wakebit\CycleBridge\Schema\Config\SchemaConfig;

return [
    // ...
    'orm' => [
        'schema' => new SchemaConfig([
            'cache' => [
                'store' => env('CACHE_DRIVER', 'file'),           
            ],
        ]),
    ],
    // ...
]

命令

数据库迁移

你可以在 cycle.migrations 配置键中指定迁移表名称以及迁移将创建的路径。

命令

数据库命令

编写测试

如果你使用内存数据库（SQLite），你只需在测试的 setUp 方法中运行迁移。

public function setUp(): void
{
    parent::setUp();
    
    $this->artisan('cycle:migrate');
}

对于其他数据库，请按照此说明进行操作，并在 tearDown 方法中删除所有表。

高级

手动定义 ORM 模式

如果你想使用手动定义的 ORM 模式，你可以在 cycle.orm.schema 的 SchemaConfig 的 map 配置键中定义它（此键默认不存在）

use Wakebit\CycleBridge\Schema\Config\SchemaConfig;

return [
    // ...
    'orm' => [
        'schema' => new SchemaConfig([
            'map' => require __DIR__ . '/../orm_schema.php',
            // ... 
        ]),
    ]
    // ...
]

手动定义的方案应表示为数组。它将被传递给 \Cycle\ORM\Schema 构造函数。更多信息请查看这里。

自定义方案编译管道

你可以在 cycle.orm.schema 的 SchemaConfig 的 generators 配置键中重新定义 ORM 方案编译生成器（此键默认不存在）

use Wakebit\CycleBridge\Schema\Config\SchemaConfig;

return [
    // ...
    'orm' => [
        'schema' => new SchemaConfig([
            'generators' => [
                'index' => [],
                'render' => [
                    \Cycle\Schema\Generator\ResetTables::class,         // re-declared table schemas (remove columns)
                    \Cycle\Schema\Generator\GenerateRelations::class,   // generate entity relations
                    \Cycle\Schema\Generator\GenerateModifiers::class,   // generate changes from schema modifiers
                    \Cycle\Schema\Generator\ValidateEntities::class,    // make sure all entity schemas are correct
                    \Cycle\Schema\Generator\RenderTables::class,        // declare table schemas
                    \Cycle\Schema\Generator\RenderRelations::class,     // declare relation keys and indexes
                    \Cycle\Schema\Generator\RenderModifiers::class,     // render all schema modifiers
                ],
                'postprocess' => [
                    \Cycle\Schema\Generator\GenerateTypecast::class,    // typecast non string columns
                ],
            ]
        ]),
    ]
    // ...
]

类将通过 DI 容器解析。默认管道可以在桥梁包中的这里查看。

使用自定义集合

默认情况下，ORM 使用数组作为项的集合。如果你想使用 Laravel 集合而不是其他集合，你可以在配置的 orm 部分添加以下键

return [
    // ...
    'orm' => [
        'default_collection_factory_class' => \Cycle\ORM\Collection\IlluminateCollectionFactory::class,
        // ...
    ],
    // ...
]

工厂类将通过容器解析。它应该实现 \Cycle\ORM\Collection\CollectionFactoryInterface 接口。

备注

我们没有计划创建 Laravel Facades、魔法助手等。如果你需要，你可以自己创建它们。

致谢

Cycle ORM，由 SpiralScout 开发的 PHP 数据映射 ORM 和数据建模引擎。
Spiral Scout，Cycle ORM的作者。
Spiral 框架 Cycle 桥接器，代码示例和使用示例。

wakebit / laravel-cycle

维护者

详细信息