README

Clarinet是一个基于JPA/Hibernate语法的PHP ORM。然而，Clarinet的功能远不如Hibernate丰富。它旨在简单快速地构建，因此非常适合小型网站和原型设计。

在本指南和代码中，您将看到术语“模型”和“实体”。模型用于指代可以持久化的东西的定义，而实体用于指代模型的一个实例。

注意：尽管正在更新文档以提高这些术语使用的统一性，但仍可能存在一些地方它们被交替使用。

安装

Composer: zeptech/clarinet

模型类

持久化信息是从模型类中提取的。通常，您的数据库中的每个表都将由一个模型类表示。一个例外是多对多关系中的连接表，它们将由Clarinet透明处理。

用于定义模型类的所有注解都将根据php-annotations库的规则进行解析。

模型类必须遵循一些简单的约定，使其看起来很像Java Bean。

每个模型类必须用@Entity注解

<?php
/** @Entity(table = simple_entity) */
class SimpleEntity {
  // ...
}

目前，实体注解必须定义一个'table'参数，它包含实体持久化的数据库表名。将来这将被更改，如果未提供表名，将选择一个合理的默认值。最可能的是，类的名称以驼峰式命名改为下划线分隔的小写。

标识属性

每个模型类必须定义一个id列。id列通过类似于以下方式的getter/setter对定义

<?php
class SimpleEntity {

  private $id;

  /** @Id */
  public function getId() {
    return $this->id;
  }

  public function setId($id) {
    $this->id = $id;
  }
}

注意：如果getXXX方法被Clarinet理解的注解标注，但没有匹配的setXXX方法，Clarinet将失败。

前面的代码将假设数据库表中包含id的列名为'id'。要指定不同的列，可以添加一个@Column注解

<?php
  // ...

  /**
   * @Id
   * @Column(name = id)
   */

列属性

@Column注解也用于表示由Clarinet处理的表中的其他列的getter/setter对。所以如果simple_entity表有一个列'name'，可以定义一个类似于以下方式的getter/setter对

<?php
class SimpleEntity {

  private $id;
  private $name;

  // Id getter/setter ...

  /** @Column(name = name) */
  public function getName() {
    return $this->name;
  }

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

column注解的name参数是可选的。如果不存在，则假设列名是getXXX()中的XXX部分的下划线分隔的小写版本。因此，前面的示例可以写成

<?php
  // ...

  /**
   * @Column
   */
  public function getName() {
    return $this->name;
  }

其他支持的列注解

• @Type：属性中包含的数据类型。除了标准数据库类型外，Clarinet还支持一些类型（如email），这些类型为标准数据库类型提供额外的抽象。这些类型由运行时Validator角色强制执行。
• @Enumerated：如果列只支持有限值的列表，可以使用@enumerated注解的values参数定义这些值，例如@enumerated( values = { ... } )。

关系

Clarinet 还支持使用注解的 getter/setter 对定义关系。支持的关系类型有三种：多对一、一对多和多对多。关系通过一个注解为 @ManyToOne、@OneToMany 或 @ManyToMany 的 getter 来指定。与 id 和列 getter 一样，它们必须与一个 setter 一起使用。每个关系注解都需要一个 'entity' 参数，它是关系右侧实体名称。所有关系都有左右两侧。左侧是声明关系的实体。在两侧都声明的关系称为 镜像。

<?php
  // ...

  /** @OneToMany( entity = Category ) */
  public function getCategories() {
    return $this->categories;
  }

一对多关系

一对多关系会导致在模型中填充一个相关的模型数组。这是通过将相关模型表中的一列与实体的 id 相连接来实现的。可以使用 @OneToMany 注解的 'column' 参数指定列。SimpleEntity 示例中的列将是 'simple_entity_id'。要指定列，请执行以下操作

<?php

  // ...

  /**
   * @OneToMany( entity = Category, column = simple_entity_id )
   */
  public function getCategories() {
    return $this->_categories;
  }

注意 对于单向一对多映射，为了避免错误，必须满足以下两个条件之一。要么 多 表中的 一 方 ID 列必须是可空的，要么必须在保存之前以编程方式在 多 实体中填充 id。这是因为没有双向多对一映射，ORM 没有办法知道多侧的哪个属性映射到一侧的 ID。

排序

对于一对多和多对多关系，默认情况下返回相关实体的顺序是未定义的。如果顺序很重要，可以在注解中指定一个顺序参数。参数的值是列的名称。可以使用 'dir' 参数指定方向。默认方向是 ASC。

<?php

  // ...

  /** @OneToMany( entity = Category, order = name, dir = asc ) */
  public function getCategories() {
    return $this->_categories;
  }

Clarinet 采用 3 条款 BSD 许可证，其文本可以在与该文件相同的目录中的 LICENSE.txt 文件中找到。

集合

Clarinet 支持集合关系来存储数组属性。支持三种集合类型：@Set、@List 和 @Map

用法

Clarinet 使用 PHP Code Templates 库为给定的模型类生成持久化器、验证器和转换器演员。为了使用 clarinet*Generator 类，必须提供该库的类。

初始化

待办事项

生成演员

待办事项

演员

实例化

待办事项

用法

待办事项