ESTANDARES PHP ZEND FRAMEWORK y PHPDOC DOCBLOCK

Contenido
Formato de archivos PHP................................................................................ 5
Convenciones de Nombres............................................................................. 5
1. Clases................................................................................................ 5
2. Clases Abstractas.............................................................................. 5
3. Interfaces........................................................................................... 5
4. Nombres de Archivo..........................................................................5
5. Funciones y Mtodos.........................................................................5
6. Variables............................................................................................ 6
7. Constantes......................................................................................... 6
Estilo de cdigo.............................................................................................. 7
1. Demarcacin de cdigo PHP..............................................................7
2. Cadenas de Caracteres......................................................................7
Arrays.......................................................................................................... 7
1. Arrays Indexados Numricamente.....................................................7
2. Arrays Asociativos............................................................................. 8
Clases.......................................................................................................... 8
1. Declaracin de clases........................................................................8
2. Variables de miembros de clase.....................................................9
Funciones y Mtodos................................................................................... 9
1. Declaracin de Funciones y Mtodos.................................................9
2. Uso de Funciones y Mtodos............................................................10
3. Sentencias de Control......................................................................10
4. Switch........................................................................................... 10
Documentacin integrada.........................................................................11
1. Formato de documentacin..................................................................11
2. Archivos............................................................................................ 11
3. Clases........................................................................................... 12
4. Funciones......................................................................................... 12
RECOMENDACIN DE LA ESTRUCTURA DE DIRECTORIO DEL PROYECTO....12
PHP DOCUMENTATION DOCBOCK.................................................................13
1. API................................................................................................... 13
2. Autor................................................................................................ 14
3. Copyright......................................................................................... 14
Formato de archivos PHP
1. General: Para archivos que contengan nicamente cdigo PHP, la etiqueta de
cierre ("?>") no est permitida. No es requerida por PHP, y omitirla evita la
inyeccin de espacios en blanco en la respuesta.
2. Identacin: La identacin suele estar compuesta por 4 espacios. Las
tabulaciones no estn permitidas.
3. Tamao mximo de lnea: La longitud recomendable para una lnea de cdigo
es de 80 caracteres. No obstante, lneas ms largas pueden ser aceptables en
algunas situaciones. El tamao mximo de cualquier lnea de cdigo PHP es
de 120 caracteres.
4. Final de lnea: Las lneas deben acabar con un carcter linefeed (LF)
echo "Ruta: $ruta", PHP_EOL;

Convenciones de Nombres
1. Clases: Los nombres de clases pueden contener slo caracteres
alfanumricos. Los nmeros estn permitidos en los nombres de clase, pero
desaconsejados en la mayora de casos. Las barras bajas (_) estn permitidas
solo como separador de ruta.

Si el nombre de una clase, est compuesto por ms de una palabra, la primera

letra de cada palabra debe aparecer en maysculas. Poner en maysculas las
letras siguientes no est permitido, ej: "Zend_PDF" no est permitido, mientras
que " Zend_Pdf " es admisible.

2. Clases Abstractas: Las clases abstractas siguen las mismas convenciones

que las clases , con una regla adicional: Los nombres de las clases abstractas
deben acabar con el trmino, "Abstract", y ese trmino no debe ser precedida
por un guion bajo. Ejemplo, Zend_Controller_Plugin_Abstract es considerado
un nombre no vlido, pero Zend_Controller_PluginAbstract o
Zend_Controller_Plugin_PluginAbstract seran nombres vlidos.

3. Interfaces: En general, las clases abstractas siguen las mismas

convenciones que las classes , con una regla adicional: Los nombres de las
interfaces opcionalmente pueden acabar con el trmino, "Interface",pero
trmino no debe ser precedida por un guion bajo. Ejemplo,
Zend_Controller_Plugin_Interface es considerado un nombre no vlido, pero
Zend_Controller_PluginInterface o Zend_Controller_Plugin_PluginInterface
seran nombres vlidos.

4. Nombres de Archivo: Para cualquier otro archivo, slo caracteres

alfanumricos, barras bajas (_) y guiones (-) estn permitidos. Los espacios en
blanco estn estrictamente prohibidos. Cualquier archivo que contenga cdigo
PHP debe terminar con la extensin " .php ", con la excepcin de los scripts de
la vista.

5. Funciones y Mtodos: Los nombres de funciones pueden contener

nicamente caracteres alfanumricos. Los guiones bajos (_) no estn
permitidos. Los nmeros estn permitidos en los nombres de funcin pero no
se aconseja en la mayora de los casos.
 Los nombres de funciones deben empezar siempre con una letra minscula.
Cuando un nombre de funcin consiste en ms de una palabra, la primera letra
de cada nueva palabra debe estar en maysculas. Esto es llamado
comnmente como formato "camelCase".

Por norma general, se recomienda la elocuencia. Los nombres de funcin

deben ser lo suficientemente elocuentes como para describir su propsito y
comportamiento.

Para la programacin orientada a objetos, los mtodos de acceso para las

instancias o variables estticas deben ir antepuestos con un "get" o un "set". Al
implementar el patrn de diseo, tales como el patrn singleton o el patrn
factory, el nombre del mtodo deben contener en la prctica el nombre del
patrn para describir su comportamiento de forma ms completa.

Para el caso en que los mtodos son declarados con el modificador "private" o
"protected", el primer carcter del nombre de la variable debe ser una barra
baja (_). Este es el nico uso admisible de una barra baja en un nombre de
mtodo. Los mtodos declarados como pblicos no deberan contener nunca
una barra baja.

6. Variables: Los nombres de variables pueden contener caracteres

alfanumricos. Las barras bajas (_) no estn permitidas. Los nmeros estn
permitidos en los nombres de variable pero no se aconseja en la mayora de
los casos.

Para las variables de instancia que son declaradas con el modificador "private"
o "protected", el primer carcter de la variable debe ser una nica barra baja
(_). Este es el nico caso admisible de una barra baja en el nombre de una
variable. Las variables declaradas como "public" no pueden empezar nunca por
barra baja.

Al igual que los nombres de funciones (ver seccin 3.3), los nombres de
variables deben empezar siempre con una letra en minscula y seguir la
convencin "camelCaps".

Por norma general, se recomienda la elocuencia. Las variables debera ser

siempre tan elocuentes como prcticas para describir los datos que el
desarrollador pretende almacenar en ellas. Variables escuetas como " $i " y "
$n " estn desaconsejadas, salvo para el contexto de los bucles ms
pequeos. Si un bucle contiene ms de 20 lneas de cdigo, las variables de
ndice deberan tener nombres ms descriptivos.

7. Constantes: Las constantes pueden contener tanto caracteres alfanumricos

como barras bajas (_). Los nmeros estn permitidos.

Todas las letras pertenecientes al nombre de una constante deben aparecer en

maysculas.

Las palabras dentro del nombre de una constante deben separarse por barras
bajas (_). Por ejemplo, EMBED_SUPPRESS_EMBED_EXCEPTION est
permitido, pero EMBED_SUPPRESSEMBEDEXCEPTION no.
Estilo de cdigo
1. Demarcacin de cdigo PHP: El cdigo PHP debe estar delimitado
siempre por la forma completa de las etiquetas PHP estndar: <?php >.
2. Cadenas de Caracteres:
a. Cadenas Literales de Caracteres: Cuando una cadena es literal (no
contiene sustitucin de variables), el apstrofo o "comilla" debera ser
usado siempre para delimitar la cadena:

$a= 'Example String';

b. Cadenas Literales de Caracteres que Contengan Apstrofos:

Cuando una cadena literal de caracteres contega apstrofos, es
permitido delimitar la cadena de caracteres con "comillas dobles". Esto
es especialmente til para sentencias SQL :

$sql= "SELECT `id`, `name` from `people` WHERE `name`='Fred' OR

`name`='Susan'";

c. Sustitucin de Variables: La sustitucin de variables est permitida

en cualquiera de estas formas:

$greeting = "Hello $name, welcome back!";

$greeting = "Hello {$name}, welcome back!";

d. Concatenacin de cadenas: Las cadenas deben ser concatenadas

usando el operador punto ("."). Un espacio debe aadirse siempre antes
y despus del operador "." para mejorar la legibilidad:

$company = 'Zend' . ' ' . 'Technologies';

Al concatenar cadenas con el operador ".", se recomienda partir la

sentencia en mltiples lneas para mejorar la legibilidad. En estos
casos, cada linea sucesiva debe llevar un margen de espacios en
blanco de forma que el operador "." est alineado bajo el operador "=":
$sql = "SELECT `id`, `name` FROM `people` "
. "WHERE `name` = 'Susan' "
. "ORDER BY `name` ASC ";

Arrays
1. Arrays Indexados Numricamente: No estn permitidos nmeros
negativos como ndices.

Un array indexado puede empezar por cualquier valor no negativo, sin

embargo, no se recomiendan ndices base distintos a 0.

Al declarar arrays indexados con la funcin array , un espacio de separacin

deben aadirse despus de cada coma, para mejorar la legibilidad:
 $sampleArray = array(1, 2, 3, 'Zend', 'Studio');

Se permite declarar arrays indexados multilnea usando la construccin "array".

En este caso, cada lnea sucesiva debe ser tabulada con cuatro espacios de
forma que el principio de cada lnea est alineado:
$sampleArray = array(1, 2, 3, 'Zend', 'Studio',
$a, $b, $c,
56.44, $d, 500);

Alternativamente, el elemento inicial del array puede comenzar en la siguiente

lnea. Si es as, debe ser alineado en un nivel de sangra superior a la lnea que
contiene la declaracin del array, y todas las sucesivas lneas deben tener la
mismo indentacin, el parntesis de cierre debe ser en una nueva lnea al
mismo nivel de indentacin que la lnea que contiene la declaracin del array:

$sampleArray = array(
1, 2, 3, 'Zend', 'Studio',
$a, $b, $c,
56.44, $d, 500,
);

2. Arrays Asociativos: Al declarar arrays asociativos con la construccin

array , se recomienda partir la declaracin en mltiples lneas. En este caso,
cada lnea sucesiva debe ser tabuladas con cuatro espacios de forma que
tanto las llaves como los valores estn alineados:

$sampleArray = array('firstKey' => 'firstValue',

'secondKey' => 'secondValue');

Alternativamente, el elemento inicial del array puede comenzar en la siguiente

lnea. Si es as, debe ser alineado en un nivel de sangra superior a la lnea que
contiene la declaracin del array, y todas las sucesivas lneas deben tener la
mismo identacin, el parntesis de cierre debe ser en una nueva lnea al mismo
nivel de identacin que la lnea que contiene la declaracin del array: Para
mejor legibilidad, los diversos operadores de asigancin "=>" deben ser
rellenados con espacios en blanco hasta que se alinien.

$sampleArray = array(
'firstKey' => 'firstValue',
'secondKey' => 'secondValue',
);

Clases
1. Declaracin de clases: Las Clases deben ser nombradas de acuerdo
a las convencin de nombres de Zend Framework.

La llave "{" deber escribirse siempre en la lnea debajo del nombre

de la clase ("one true brace").

Cada clase debe contener un bloque de documentacin acorde con el

estndar de PHPDocumentor.
nicamente una clase est permitida por archivo PHP .
/**
 * Bloque de Documentacin aqu
*/
class SampleClass
{
// el contenido de la clase
// debe separarse con cuatro espacios
}

Las clases que extiendan otras clases o interfaces deberan declarar sus
dependencias en la misma lnea siempre que sea posible.

class SampleClass extends FooAbstract implements BarInterface

{
}

2. Variables de miembros de clase : Cualquier variable declarada en una

clase debe ser listada en la parte superior de la clase, por encima de las
declaraciones de cualquier mtodo.

La construccin var no est permitido. Las variables de miembro siempre

declaran su visibilidad usando uno los modificadores private , protected , o
public. Dar acceso a las variables de miembro declarndolas directamente
como public est permitido pero no se aconseja en favor de accesor methods.

Funciones y Mtodos

1. Declaracin de Funciones y Mtodos : Los mtodos dentro de

clases deben declarar siempre su visibilidad usando un modificador private ,
protected , o public .

Como en las clases, la llave "{" debe ser escrita en la lnea siguiente al
nombre de la funcin ("one true brace" form). No est permitido un espacio
entre el nombre de la funcin y el parntesis de apertura para los
argumentos.

Las funciones de alcance global no estn permitidas.

El paso por referencia es el nico mecanismo de paso de parmetros

permitido en una declaracin de mtodo.

La llamada por referencia est estrictamente prohibida.

El valor de retorno no debe estar indicado entre parntesis. Esto podra

afectar a la legibilidad, adems de romper el cdigo si un mtodo se
modifica posteriormente para que devuelva por referencia.

2. Uso de Funciones y Mtodos : Los argumentos de la funcin tendran

que estar separados por un nico espacio posterior despus del delimitador
coma.

funcion1(1, 2, 3);

Al pasar arrays como argumentos a una funcin, la llamada a la funcin

puede incluir el indicador "hint" y puede separarse en mltiples lneas para
 aumentar la legibilidad. En esos casos, se aplican las pautas normales para
escribir arrays:

threeArguments(array(1, 2, 3), 2, 3);

threeArguments(array(1, 2, 3, 'Zend', 'Studio',

$a, $b, $c,
56.44, $d, 500), 2, 3);

threeArguments(array(
1, 2, 3, 'Zend', 'Studio',
$a, $b, $c,
56.44, $d, 500
), 2, 3);

3. Sentencias de Control: Las sentencias de control basadas en las

construcciones if y elseif deben tener un solo espacio en blanco antes del
parntesis de apertura del condicional y un solo espacio en blanco despus
del parntesis de cierre.

Dentro de las sentencias condicionales entre parntesis, los operadores

deben separarse con espacios, por legibilidad. Se aconseja el uso de
parntesis internos para mejorar la agrupacin lgica en expresiones
condicionales ms largas.

La llave de apertura "{" se escribe en la misma lnea que la sentencia

condicional. La llave de cierre "}" se escribe siempre en su propia lnea.
Cualquier contenido dentro de las llaves debe separarse con cuatro
espacios en blanco.
if ($a != 2) {
$a = 2;
}
if ($a != 2) {
$a = 2;
} elseif ($a == 3) {
$a = 4;
} else {
$a = 7;
}
4. Switch: Las declaraciones de control escritas con la declaracin
"switch" deben tener un nico espacio en blanco antes del parntesis
de apertura del condicional y despus del parntesis de cierre.

Todo contenido dentro de una declaracin "switch" debe separarse

usando cuatro espacios. El contenido dentro de cada declaracin
"case" debe separarse usando cuatro espacios adicionales.

switch ($numPeople) {
case 1:
break;

case 2:
break;

default:
 break;
}

La construccin default no debe omitirse nunca en una declaracin switch.

NOTA: En ocasiones, resulta til escribir una declaracin case que salta al
siguiente case al no incluir un break o return dentro de ese case. Para
distinguir estos casos de posibles errores, cualquier declaracin donde
break o return sean omitidos deber contener un comentario indicando que
se omitieron intencionadamente.

Documentacin integrada

1. Formato de documentacin: Todos los bloques de documentacin ("docblocks")

deben ser compatibles con el formato de phpDocumentor.

Todos los archivos de clase deben contener un bloque de documentacin "a

nivel de archivo" al principio de cada archivo y un bloque de documentacin "a
nivel de clase" inmediatamente antes de cada clase.

2. Archivos: Cada archivo que contenga cdigo PHP debe tener un bloque de
documentacin al principio del archivo que contenga como mnimo las
siguientes etiquetas phpDocumentor:

/**
* Descripcin corta del fichero
*
* Descripcin larga del fichero (si la hubiera)...
*
* LICENSE: Some license information
*
* @category Zend
* @package Zend_Magic
* @subpackage Wand
* @copyright Copyright (c) 2005-2010 Zend Technologies USA
Inc. ()
* @license BSD License
* @version $Id:$
* @link
* @since File available since Release 1.5.0
*/

3. Clases: Cada clase debe contener un bloque de documentacin que contenga

como mnimo las siguientes etiquetas phpDocumentor:
/**
* Descripcin corta de la clase
*
* Descripcion larga de la clase (si la hubiera)...
*
* @category Zend
* @package Zend_Magic
* @subpackage Wand
* @copyright Copyright (c) 2005-2010 Zend Technologies USA
Inc. ()
 * @license BSD License
* @version Release: @package_version@
* @link
* @since Class available since Release 1.5.0
* @deprecated Class deprecated in Release 2.0.0
*/

4. Funciones: Cada funcin, incluyendo mtodos de objeto, debe contener un

bloque de documentacin que contenga como mnimo:
Una descripcin de la funcin
Todos los argumentos
Todos los posibles valores de retorno
No es necesario incluir la etiqueta "@access" si el nivel de acceso es conocido
de antemano por el modificador "public", "private", o "protected" usado para
declarar la funcin.

Si una funcin/mtodo puede lanzar una excepcin, utilice @throws para todos
los tipos de excepciones conocidas:

RECOMENDACIN DE LA ESTRUCTURA DE
DIRECTORIO DEL PROYECTO
<project name="">/
application/
configs/
application.ini
controllers/
helpers/
forms/
layouts/
filters/
helpers/
scripts/
models/
modules/
services/
views/
filters/
helpers/
scripts/
Bootstrap.php
data/
cache/
indexes/
locales/
logs/
sessions/
uploads/
docs/
library/
public/
css/
images/
js/
.htaccess
index.php
scripts/
 jobs/
build/
temp/
tests/</project>

application: Contiene la aplicacin, con el Sistema MVC , con sus diferentes

archivos.
Data: Contiene los archivos de los scripts de la base de datos.
Docs: Contiene la documentacin
Script: Contiene el mantenimiento, lneas de comando, cron
Test: contiene las pruebas unitarias phpunit, selenium-RC.

PHP DOCUMENTATION DOCBOCK

1. API:
Sintaxis: @api
Descripcion: Elementos Estructurales con una visibilidad pblica que estn
destinados a ser los componentes, biblioteca o un marco. Se los utiliza en
mtodos.
Ejempo:

/**
* This method will not change until a major release.
*
* @api
*
* @return void
*/
function showVersion()
{
<...>
}

2. Autor:
Sintaxis: @author [name] [<email address>]
Descripcin: Puede ser usado para indicar quien creo la estructura o quien
realizo cambios significativos.
Ejemplo:
/**
* @author My Name
* @author My Name <my.name@example.com>
*/

3. Copyright:
Sintaxis: @copyright [description]
 Descripcin: Define quin tiene la propiedad intelectual sobre los elementos
estructurales.
Ejemplo:
/**
* @copyright 1997-2005 The PHP Group
*/

4. Deprecated:
Sintaxis: @deprecated [<version>] [<description>]
Descripcin: Es declarado para todos las asociaciones de estructura de
elementos. Se eliminar en una versin futura, ya que ha quedado obsoleta o
de otro modo no se recomienda su uso.
Ejemplo:
/**
* @deprecated
* @deprecated 1.0.0
* @deprecated No longer used by internal code and not recommended.
* @deprecated 1.0.0 No longer used by internal code and not recommended.
*/
function count()
{
<...>
}

5. Example: d
Sintaxis: @example [location] [<start-line> [<number-of-lines>] ]
[<description>]
Descripcin: Usada para demostrar el uso de la estructura de elementos.
/**

* @example example1.php Counting in action.

* @example http://example.com/example2.phps Counting in action by a 3rd party.

* @example "My Own Example.php" My counting.

*/

function count()

<...>

6. internal:

Sintaxis: @internal [description]

Descripcin: indica que los elementos estructurales asociados se utilizan

exclusivamente para el funcionamiento interno de esta pieza de software .
Ejemplo:
/**
* @internal

* @return integer Indicates the number of items.

*/

function count()

<...>

7. License
Sintaxis: @license [<url>] [name]
Descripcin: Proporciona el nombre y la direccin URL de la
licencia que se aplica a los elementos estructurales y cualquiera
de sus elementos derivados.
Ejemplo:
/**

* @license GPL

* @license http://opensource.org/licenses/gpl-license.php GNU Public License

*/

8. Method:
Sintaxis: @method [return type] [name]([[type]
[parameter]<, ...>]) [<description>]
Descripcin: Es usado donde la clase contiene el llamado a la funcin
__call() y define algunos definidos por el usuarios.
Ejemplo:
class Parent

public function __call()

<...>

}
/**

* @method string getString()

* @method void setInteger(integer $integer)

* @method setString(integer $integer)

*/

class Child extends Parent

<...>

9. Property:
Sintaxis: @property [Type] [name] [<description>]
Descripcin: Es usuada cuando una clase contiene los metodos __get()
y __set()
class Parent

public function __get()

<...>

/**

* @property string $myProperty

*/

class Child extends Parent

<...>

10. Return:
 Sintaxis: @return [Type] [<description>]
Descripcin: Es posible la documentacin del retorno del tipo de una
funcion o metodo.
Ejemplo: /**

* @return integer Indicates the number of items.

*/

function count()

<...>

11. trhows
Sintaxis: @throws [Type] [<description>]
Descripcin: Mostrar si tiene excepciones y de tipo son y su descripcin.
/**

* Counts the number of items in the provided array.

* @param mixed[] $array Array structure to count the elements of.

* @throws InvalidArgumentException if the provided argument is not of type

* 'array'.

* @return int Returns the number of elements.

*/

function count($items)

<...>

12. version
Sintaxis: @version [<vector>] [<description>]
Descripcin: Indicar la version de la funcion, metodo, clase
 Ejemplo:
/**

* @version 1.0.1

*/

class Counter

<...>

/**

* @version GIT: $Id$ In development. Very unstable.

*/

class NeoCounter

<...>