A free and open-source book on ZF3 for beginners

12.5. About Doctrine Entities

An entity is a PHP class that is designed for storing data. For example, below you can find several often used examples of entities:

In terms of Domain Driven Design pattern, entities are a kind of models designed for storing data. For additional examples of entities and other types of models, please refer to Model-View-Controller.

In Doctrine ORM, an entity class is mapped on a certain database table. For example, the User entity is usually mapped on the user table (if needed, the table name may be arbitrary).

For our Blog example application, we will create three entity classes:

12.5.1. Annotations

An annotation is a special kind of a PHP comment that is preprocessed by Doctrine ORM. In other words, annotations is metadata attached to an entity class that can be read by the Doctrine ORM at run-time. Annotations provide verbose information about an entity. Annotations describe an entity and tell Doctrine ORM how to map it on a database table.

A Docblock annotation is a C++ style comment starting with slash (/) and two asterisks (*). This "starter" characters are required, otherwise Doctrine won't recognize the annotation. An example of annotation can be found below:

 * This is Docblock annotation comment.

Doctrine reads Docblock annotations with the help of its Doctrine\Annotations component.

You might have already seen Docblock annotations if you've used phpDocumentor or Doxygen documentation generation tools. In those tools, annotation comments are serving the same goal: to describe a PHP class and its properties and methods. Then the tool goes through your code and builds HTML documentation automatically based entirely on code and annotations analysis.

For example, below, we provide the basic example of a Doctrine entity class. You can see that the class and its properties are marked with Docblock annotations with special tags (a tag starts with '@' character).

namespace Application\Entity;

use Doctrine\ORM\Mapping as ORM;

 * @ORM\Entity
 * @ORM\Table(name="post")
class Post 
   * @ORM\Id
   * @ORM\GeneratedValue
   * @ORM\Column(name="id")   
  protected $id;

   * @ORM\Column(name="title")  
  protected $title;

   * @ORM\Column(name="content")  
  protected $content;

   * @ORM\Column(name="status")  
  protected $status;

   * @ORM\Column(name="date_created")  
  protected $dateCreated;   

Let's review the code above:

In line 2, we declared the Application\Entity namespace in which entity classes for the Application module live.

In line 4, you may notice that we use the Doctrine\ORM\Mapping class and its short ORM alias for Doctrine annotations 48.

48) Doctrine-provided annotation tags are implemented as classes living inside of Doctrine\ORM\Mapping namespace. This is to avoid annotation naming collisions (assume the case when some other component has an annotation named Entity or Table, the collision would happen).

In lines 6-9, you can see a Docblock annotation for the Post class. Each annotation tag begins with the @ character, has the name and (optional) parameters enclosed into the round braces.

Doctrine-provided tags used in annotations may be of two types: class-level and property-level. In the code above, we use the following class-level tags (describing the whole entity class):

Entity's properties are described with the following property-level tags:

The complete list of Doctrine-provided tags used in annotations can be found by the following link.