Convenciones

El documento estándares describe las normas de codificación de los proyectos Symfony2 y los paquetes internos de terceros. Este documento describe los estándares de codificación y convenciones utilizadas en la plataforma básica para que sea más consistente y predecible. Las puedes seguir en tu propio código, pero no es necesario.

Nombres de método

Cuando un objeto tiene una relación «principal» con muchas «cosas» relacionadas (objetos, parámetros, ...), los nombres de los métodos están normalizados:

• get()
• set()
• has()
• all()
• replace()
• remove()
• clear()
• isEmpty()
• add()
• register()
• count()
• keys()

El uso de estos métodos sólo se permite cuando es evidente que existe una relación principal:

• un CookieJar tiene muchos objetos Cookie;
• un Contenedor de servicios tiene muchos servicios y muchos parámetros (dado que los servicios son la relación principal, utilizamos la convención de nomenclatura para esta relación);
• una Consola Input tiene muchos argumentos y muchas opciones. No hay una relación «principal», por lo tanto no aplica la convención de nomenclatura.

Para muchas relaciones cuando la convención no aplica, en su lugar se deben utilizar los siguientes métodos (donde XXX es el nombre de aquello relacionado):

Relación principal	Otras relaciones
get()	getXXX()
set()	setXXX()
n/a	replaceXXX()
has()	hasXXX()
all()	getXXXs()
replace()	setXXXs()
remove()	removeXXX()
clear()	clearXXX()
isEmpty()	isEmptyXXX()
add()	addXXX()
register()	registerXXX()
count()	countXXX()
keys()	n/a

Nota

Si bien «setXXX» y «replaceXXX» son muy similares, hay una notable diferencia: «setXXX» puede sustituir o agregar nuevos elementos a la relación. «replaceXXX», por otro lado, no puede añadir nuevos elementos. Si se pasa una clave no reconocida a «replaceXXX», lanzará una excepción.

Depreciaciones

De vez en cuando, algunas clases y/o métodos son depreciados en la plataforma; esto sucede cuando la implementación de una característica no se puede cambiar debido a cuestiones de compatibilidad hacia atrás, pero todavía queremos proponer una mejor «alternativa». En este caso, la antigua implementación sencillamente se puede depreciar.

Una característica es marcada como depreciada añadiendo una anotación @deprecated de phpdoc a las clases, métodos, propiedades, ... pertinentes:

/**
 * @deprecated Depreciada a partir de la versión 2.X, será removida en 2.Y. En su lugar usa XXX.
 */

El mensaje de la depreciación debería indicar la versión cuándo el método/clase fue depreciado, la versión cuándo será removido, y siempre que sea posible, cómo sustituir la característica.

Un error E_USER_DEPRECATED de PHP también será provocado para ayudar a las personas con la migración empezando una o dos versiones menores antes de la versión donde la característica será removida (dependiendo de lo delicado de la extracción):

trigger_error(
    'XXX() está depreciada a partir de la versión 2.X, será removida en 2.Y. En su lugar usa XXX.',
    E_USER_DEPRECATED
);