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:
La entidad User
está diseñada para guardar información sobre el visitante del
sitio web. Esta puede contener propiedades como: nombre de usuario, contraseña,
nombre, apellido.
La entidad License
está diseñada para guardar información sobre la licencia
del software. Esta contiene datos como la llave única de la licencia, referencia
al usuario que compro la licencia, fecha de creación de la licencia, etc.
La entidad Payment
puede contener propiedades relacionadas a la compra de
algún bien. Las propiedades son: identificador de la transacción, cantidad de
dinero, tipo de moneda, etc.
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:
La entidad Post
contendrá datos relacionados a las publicaciones del blog.
Sus propiedades son exactamente las mismas que se usaron cuando definimos la
tabla post
en el esquema de base de datos blog. Además, la clase entidad
tendrá métodos getter y setter públicos diseñados para recuperar y colocar
datos.
Por analogía, la entidad Comment
contendrá datos relacionados a los comentarios
de una publicación del blog.
Y la entidad Tag
contendrá datos relacionados con la etiqueta.
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):
La etiqueta @ORM\Entity
(línea 7) declara que esta clase es una entidad de
Doctrine ORM.
La etiqueta @ORM\Table(name="post")
(línea 8) le dice a Doctrine ORM que esta
clase de tipo entidad debe ser asociada a la tabla post
.
Las propiedades de la entidad se describen con las etiquetas de nivel de propiedad:
La etiqueta @ORM\Id
dice que esta propiedad es un identificador único de la
entidad (línea 13).
La etiqueta @ORM\GeneratedValue
se usa para decirle a Doctrine ORM que esta
propiedad usa determinada secuencia autogenerada para inicializarse ella misma.
(línea 14). En MySQL, esto significa que la columna de la tabla correspondiente
usa el atributo AUTO_INCREMENT
para generar un identificador único para cada
fila.
La etiqueta @ORM\Column(name="<column_name>")
se usa para decirle a Doctrine
ORM a que columna en la tabla asociar cada propiedad en particular (líneas 15,
20, 25, 30, 35).
La lista completa de las etiquetas que Doctrine provee usadas en las anotaciones se pueden encontrar en el siguiente enlace link.