A free and open-source book on ZF3 for beginners

Translation into this language is not yet finished. You can help this project by translating the chapters and contributing your changes.

12.5. Sobre las Entidades de Doctrine

Una entidad es una clase PHP que esta diseñada para guardar datos. Por ejemplo, abajo podemos encontrar varias entidades de ejemplo usadas a menudo:

En términos del patrón de diseño guiado por dominio, las entidades son un tipo modelos diseñados para guardar datos. Para ejemplos adicionales de entidades y otros tipos de modelos podemos revisar Modelo-Vista-Controlador.

Con Doctrine ORM una clase entidad se asocia a determinada tabla en la base de datos. Por ejemplo, la entidad User está usualmente asociada a la tabla user (de hecho el nombre de la tabla puede ser arbitraria).

Para nuestra aplicación de ejemplo Blog crearemos tres clases entidades:

12.5.1. Anotaciones

Una anotación es un tipo especial de comentario PHP que preprocesa Doctrine ORM. En otras palabras, las anotaciones son metadatos que se añaden a una clase entidad que pueden ser leídos en tiempo de ejecución por Doctrine ORM. Las anotaciones proveen información detallada sobre una entidad. Las anotaciones describen una entidad y le dicen a Doctrine ORM como asociarla a una tabla en base de datos.

Las anotaciones Docblock son comentarios estilo C++ que comienzan con una barra (/) y dos asteriscos (*). Estos caracteres de "entrada" son obligatorios, de lo contrario Doctrine no reconocerá las anotaciones. Un ejemplo de anotaciones se encuentra mas abajo:

/**
 * This is Docblock annotation comment.
 */

Doctrine lee las anotaciones Docblock con la ayuda del componente Doctrine\Annotations.

Podríamos haber visto las anotaciones de Docblock si ya hemos usado herramientas de generación de documentación como phpDocumentor o Doxygen. En estas herramientas las anotaciones de comentarios cumplen el mismo objetivo: describir una clase PHP, sus propiedades y sus métodos. Luego la aplicación explora nuestro código y construye documentación en HTML automáticamente basada completamente en el código y análisis de las anotaciones.

Por ejemplo, abajo mostramos un ejemplo básico de una clase entidad de Doctrine. Podemos ver que la clase y sus propiedades se marcan con las anotaciones de Docblock usando la etiqueta especial tags (una etiqueta que comienza con el carácter '@').

<?php
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;
}

Revisemos el código de arriba:

En la línea 2 declaramos el namespace Application\Entity donde las clases de tipo entidad para el módulo Application se encuentran.

En la línea 4 podemos observar que usamos la clase Doctrine\ORM\Mapping y su alias ORM para las anotaciones de Doctrine 48.

48) Las etiquetas para Doctrine se implementan como clases dentro del namespace Doctrine\ORM\Mapping. Con esto se evita la colisión de nombres (si asumimos que algún otro componente tiene un nombre de anotación Entity o Table la colisión ocurrirá).

En las líneas 6-9 podemos ver la anotación Docblock para la clase Post. Cada etiqueta de anotación comienza con el carácter @, tiene nombre y parámetros (opcionales) dentro de paréntesis.

Las etiquetas de Doctrine que se usan en las anotaciones pueden ser de dos tipos: de nivel de clase y de nivel de propiedades. En el código de arriba usamos las siguientes etiquetas de nivel de clase (describen a toda la clase de tipo entidad):

Las propiedades de la entidad se describen con las etiquetas de nivel de propiedad:

La lista completa de las etiquetas que Doctrine provee usadas en las anotaciones se pueden encontrar en el siguiente enlace link.


Top