Annotated Entities

The annotated entities extension is capable of indexing any domain entity in your project. To indicate that the class must be treated as a domain entity make sure to add the @Entity annotation to the DocComment.

use Cycle\Annotated\Annotation\Entity;

/** @Entity */
class User
{
}

Annotations are based on the Doctrine/Lexer package and support syntax similar to the Doctrine one.

#Entity

Usually, the single annotation @Entity is enough to describe your model. In this case, Cycle will automatically assign the generated table name and role based on the class name. In the case of User the role will be user, database null (default) and table users.

You can tweak all of these values by setting entity options:

use Cycle\Annotated\Annotation\Entity;

/**
 * @Entity(
 *     role     = "user",
 *     database = "database",
 *     table    = "user_table"
 * )
 */
class User
{
}

You must manually set role and table for your classes if you use models that share the same name.

Some options can be used to overwrite default entity behaviour, for example to assign a custom entity repository:

use Cycle\Annotated\Annotation\Entity;

/**
 * @Entity(repository = "Repository\UserRepository")
 */
class User
{
}

Cycle can locate repository class names automatically, using current entity namespace as the base path.

Following entity options are available for customization:

For example, a typical entity description might look like:

use Cycle\Annotated\Annotation\Entity;

/**
 * @Entity(
 *    table      = "users",
 *    repository = "Repository\UserRepository",
 *    scope      = "Scope/SortByID"
 * )
 */
class User
{
}

#Columns

No entity can operate without some properties mapped to table columns. To map your property to the column add the annotation @Column to it. It's mandatory to specify the column type. You must always specify one primary (auto incremental) column for your entity.

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

/** @Entity */
class User
{
    /** @Column(type = "primary") */
    protected $id;
}

Read how to use non-incremental primary keys (for example UUID) in the Advanced section.

You can use multiple annotations at the same time:

use Cycle\Annotated\Annotation as Cycle;

/** @Cycle\Entity */
class User
{
    /** @Cycle\Column(type = "primary") */
    protected $id;
}

Annotation import is omitted in the following sections.

By default, the entity property will be mapped to the column with the same name as the property. You can change it as follows:

/** @Entity */
class User
{
    /** @Column(type = "primary") */
    protected $id;

    /** @Column(type = "string", name = "username") */
    protected $login;
}

Some column types support additional arguments, such as length, values, etc.

/** @Entity */
class User
{
    /** @Column(type = "primary") */
    protected $id;

    /** @Column(type = "string(32)") */
    protected $login;

    /** @Column(type = "enum(active,disabled)") */
    protected $status;

    /** @Column(type = "decimal(5,5)") */
    protected $balance;
}

Use the default option to specify the default value of the column:

/** @Entity */
class User
{
    /** @Column(type = "primary") */
    protected $id;

    /** @Column(type = "enum(active,disabled)", default = "active") */
    protected $status;
}

While adding new columns to entities associated with non-empty tables you are required to either specify a default value or mark the column as nullable:

/** @Entity */
class User
{
    /** @Column(type = "primary") */
    protected $id;

    /** @Column(type = "string(64)", nullable = true) */
    protected $password;
}

Following options are available for configuration:

Following column types are available:

#Enums

The ORM supports the enum type for all available drivers. You must define enum options using comma separator:

/** @Column(type = "enum(active,disabled)", default = "active") */
protected $status;

#Table Extension

In some cases you might want to specify additional table columns and indexes without the link to the entity properties. This can be achieved using @Table annotation:

/**
 * @Entity
 * @Table(
 *      columns={"created_at": @Column(type = "datetime"), "deleted_at": @Column(type = "datetime")},
 *      indexes={
 *             @Index(columns = {"username"}, unique = true),
 *             @Index(columns = {"status"})
 *      }
 * )
 */
class User
{
    /** @Column(type = "primary") */
    protected $id;

    /** @Column(type ="string(32)") */
    protected $username;

    /** @Column(type = "enum(active,disabled)", default = "active") */
    protected $status;
}

The column definition is identical to the one used for the property.

#Merging annotations

The Annotated Entities extension supports the ability to merge table definitions provided by linked Mapper, Source, Repository and Scope classes. This approach can be useful in cases when you want to implement domain functionality like auto timestamps or soft deletes.

/**
 * @Entity(repository = "Repository/UserRepository")
 */
class User
{
}

You can also use short annotation declaration:

/**
 * @Table(
 *     columns={"created_at": @Column("datetime")},
 *     indexes={@Index(columns = {"created_at"})}
 * )
 */
class UserRepository extends \Cycle\ORM\Select\Repository
{

}