Introducción a Zend Framework

 Aprendiendo Zend Framework

Apéndice

 Referencia de Zend Framework


  • Zend_Gdata
  • Zend_Http
  • Zend_InfoCard
  • Zend_Json
  • Zend_Layout
  • Zend_Ldap
  • Zend_Loader
  • Zend_Locale
  • Zend_Log
  • Zend_Mail
  • Zend_Markup
  • Zend_Measure
  • Zend_Memory
  • Zend_Mime
  • Zend_Navigation
  • Zend_Oauth
  • Zend_OpenId
  • Zend_Paginator
  • Zend_Pdf
  • Zend_ProgressBar
  • Zend_Queue
  • Zend_Reflection
  • Zend_Registry
  • Zend_Rest

  • Zend_Search_Lucene
  • Zend_Serializer
  • Zend_Server
  • Zend_Service
  • Zend_Session
  • Zend_Soap
  • Zend_Tag
  • Zend_Test
  • Zend_Text
  • Zend_TimeSync
  • Zend_Tool
  • Zend_Tool_Framework
  • Zend_Tool_Project
  • Zend_Translate
  • Zend_Uri
  • Zend_Validate
  • Zend_Version
  • Zend_View
  • Zend_Wildfire
  • Zend_XmlRpc
  • ZendX_Console_Process_Unix
  • ZendX_JQuery
  • Traducción al 26.9% - Actualizado el 2011-11-16 - Revisión 24249 - Versión ZF 1.11.x

    C.4. Estilo de código

    C.4.1. Demarcación de código PHP

    El código PHP debe estar delimitado siempre por la forma completa de las etiquetas PHP estándar:

    <?php

    ?>

    Las etiquetas cortas (short tags) no se permiten nunca. Para archivos que contengan únicamente código PHP , la etiqueta de cierrre debe omitirse siempre (Ver Sección C.2.1, “General” ).

    C.4.2. Cadenas de Caracteres

    C.4.2.1. Cadenas Literales de Caracteres

    Cuando una cadena es literal (no contiene sustitución de variables), el apóstrofo o "comilla" debería ser usado siempre para delimitar la cadena:

    $a 'Example String';

    C.4.2.2. Cadenas Literales de Caracteres que Contengan Apóstrofos

    Cuando una cadena literal de caracteres contega apóstrofos, 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'";

    En esta sintáxis es preferible escapar apóstrofes, ya que es mucho más fácil de leer.

    C.4.2.3. Sustitución de Variables

    La sustitución de variables está permitida en cualquiera de estas formas:

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

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

    Por consistencia, esta forma no está permitida:

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

    C.4.2.4. Concatenación de cadenas

    Las cadenas deben ser concatenadas usando el operador punto ("."). Un espacio debe añadirse siempre antes y después del operador "." para mejorar la legibilidad:

    $company 'Zend' ' ' 'Technologies';

    Al concatenar cadenas con el operador ".", se recomienda partir la sentencia en múltiples líneas 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 ";

    C.4.3. Arrays

    C.4.3.1. Arrays Indexados Numéricamente

    No están permitidos números 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 función array , un espacio de separación deben añadirse después de cada coma, para mejorar la legibilidad:

    $sampleArray = array(123'Zend''Studio');

    Se permite declarar arrays indexados multilínea usando la construcción "array". En este caso, cada línea sucesiva debe ser tabulada con cuatro espacios de forma que el principio de cada línea está alineado:

    $sampleArray = array(123'Zend''Studio',
                         
    $a$b$c,
                         
    56.44$d500);

    Alternativamente, el elemento inicial del array puede comenzar en la siguiente línea. Si es así, debe ser alineado en un nivel de sangría superior a la línea que contiene la declaración del array, y todas las sucesivas líneas deben tener la mismo indentación, el paréntesis de cierre debe ser en una nueva línea al mismo nivel de indentación que la línea que contiene la declaración del array:

    $sampleArray = array(
        
    123'Zend''Studio',
        
    $a$b$c,
        
    56.44$d500,
    );

    Al utilizar esta última declaración, recomendamos la utilización de una coma detrás de el último elemento de la matriz, lo que minimizará el impacto de añadir nuevos elementos en las siguientes líneas, y ayuda a garantizar que no se produzcan errores debido a la falta de una coma.

    C.4.3.2. Arrays Asociativos

    Al declarar arrays asociativos con la construcción array , se recomienda partir la declaración en múltiples líneas. En este caso, cada línea sucesiva debe ser tabuladas con cuatro espacios de forma que tanto las llaves como los valores están alineados:

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

    Alternativamente, el elemento inicial del array puede comenzar en la siguiente línea. Si es así, debe ser alineado en un nivel de sangría superior a la línea que contiene la declaración del array, y todas las sucesivas líneas deben tener la mismo indentación, el paréntesis de cierre debe ser en una nueva línea al mismo nivel de indentación que la línea que contiene la declaración del array: Para mejor legibilidad, los diversos operadores de asiganción "=>" deben ser rellenados con espacios en blanco hasta que se alinien.

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

    Al utilizar esta última declaración, recomendamos la utilización de una coma detrás de el último elemento de la matriz, lo que minimizará el impacto de añadir nuevos elementos en las siguientes líneas, y ayuda a garantizar que no se produzcan errores debido a la falta de una coma.

    C.4.4. Clases

    C.4.4.1. Declaración de clases

    Las Clases deben ser nombradas de acuerdo a las convencion de nombres de Zend Framework.

    La llave "{" deberá escribirse siempre en la línea debajo del nombre de la clase ("one true brace").

    Cada clase debe contener un bloque de documentación acorde con el estándar de PHPDocumentor.

    Todo el código contenido en una clase debe ser separado con cuatro espacios.

    Únicamente una clase está permitida por archivo PHP .

    Incluir código adicional en archivos de clase está permitido pero esta desaconsejado. En archivos de ese tipo, dos líneas en blanco deben separar la clase de cualquier código PHP adicional en el archivo de clase.

    A continuación se muestra un ejemplo de una declaración de clase que es permitida:

    /**
     * Bloque de Documentación aquí
     */
    class SampleClass
    {
        
    // el contenido de la clase
        // debe separarse con cuatro espacios
    }

    Las clases que extiendan otras clases o interfaces deberían declarar sus dependencias en la misma línea siempre que sea posible.

    class SampleClass extends FooAbstract implements BarInterface
    {
    }

    Si como resultado de esas declaraciones, la longitud de la línea excede la longitud del Tamaño máximo de línea , se debe romper la línea antes de la palabra clave "extends" y / o "implements" e indentarlo con un nivel de indentación (4 espacios).

    class SampleClass
        
    extends FooAbstract
        
    implements BarInterface
    {
    }

    If the class implements multiple interfaces and the declaration exceeds the maximum line length, break after each comma separating the interfaces, and indent the interface names such that they align.

    class SampleClass
        
    implements BarInterface,
                   
    BazInterface
    {
    }

    C.4.4.2. Variables de miembros de clase

    Las variables de miembros de clase deben ser nombradas de acuerdo con las conveciones de nombrado de variables de Zend Framework.

    Cualquier variable declarada en una clase debe ser listada en la parte superior de la clase, por encima de las declaraciones de cualquier método.

    La construcción 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 declarándolas directamente como public está permitido pero no se aconseja en favor de accesor methods (set & get).

    C.4.5. Funciones y Métodos

    C.4.5.1. Declaración de Funciones y Métodos

    Las Funciones deben ser nombradas de acuerdo a las convenciones de nombrado de Zend Framework.

    Los métodos 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 línea siguiente al nombre de la función ("one true brace" form). No está permitido un espacio entre el nombre de la función y el paróntesis de apertura para los argumentos.

    Las funciones de alcance global no están permitidas.

    Lo siguiente es un ejemplo de una declaración admisible de una función en una clase:

    /**
     * Bloque de Documentación aquí
     */
    class Foo
    {
        
    /**
         * Bloque de Documentación aquí
         */
        
    public function bar()
        {
            
    // el contenido de la función
            // debe separarse con cuatro espacios
        
    }
    }

    In cases where the argument list exceeds the maximum line length , you may introduce line breaks. Additional arguments to the function or method must be indented one additional level beyond the function or method declaration. A line break should then occur before the closing argument paren, which should then be placed on the same line as the opening brace of the function or method with one space separating the two, and at the same indentation level as the function or method declaration. The following is an example of one such situation:

    /**
     * Documentation Block Here
     */
    class Foo
    {
        
    /**
         * Documentation Block Here
         */
        
    public function bar($arg1$arg2$arg3,
            
    $arg4$arg5$arg6
        
    ) {
            
    // all contents of function
            // must be indented four spaces
        
    }
    }
    [Nota] Nota

    NOTA: El paso por referencia es el único mecanismo de paso de parámetros permitido en una declaración de método.

    /**
     * Bloque de Documentación aquí
     */
    class Foo
    {
        
    /**
         * Bloque de Documentación aquí
         */
        
    public function bar(&amp;$baz)
        {}
    }

    La llamada por referencia está estrictamente prohibida.

    El valor de retorno no debe estar indicado entre paréntesis. Esto podría afectar a la legibilidad, además de romper el código si un método se modifica posteriormente para que devuelva por referencia.

    /**
     * Bloque de Documentación aquí
     */
    class Foo
    {
        
    /**
         * INCORRECTO
         */
        
    public function bar()
        {
            return(
    $this->bar);
        }

        
    /**
         * CORRECTO
         */
        
    public function bar()
        {
            return 
    $this->bar;
        }
    }

    C.4.5.2. Uso de Funciones y Métodos

    Los argumentos de la función tendrían que estar separados por un único espacio posterior después del delimitador coma. A continuación se muestra un ejemplo de una invocación admisible de una función que recibe tres argumentos:

    threeArguments(123);

    La llamada por referencia está estrictamente prohibida. Vea la sección de declaraciones de funciones para el método correcto de pasar argumentos por referencia.

    Al pasar arrays como argumentos a una función, la llamada a la función puede incluir el indicador "hint" y puede separarse en múltiples líneas para aumentar la legibilidad. En esos casos, se aplican las pautas normales para escribir arrays:

    threeArguments(array(123), 23);

    threeArguments(array(123'Zend''Studio',
                         
    $a$b$c,
                         
    56.44$d500), 23);

    threeArguments(array(
        
    123'Zend''Studio',
        
    $a$b$c,
        
    56.44$d500
    ), 23);

    C.4.6. Sentencias de Control

    C.4.6.1. If/Else/Elseif

    Las sentencias de control basadas en las construcciones if y elseif deben tener un solo espacio en blanco antes del paréntesis de apertura del condicional y un solo espacio en blanco después del paréntesis de cierre.

    Dentro de las sentencias condicionales entre paréntesis, los operadores deben separarse con espacios, por legibilidad. Se aconseja el uso de paréntesis internos para mejorar la agrupación lógica en expresiones condicionales más largas.

    La llave de apertura "{" se escribe en la misma línea que la sentencia condicional. La llave de cierre "}" se escribe siempre en su propia línea. Cualquier contenido dentro de las llaves debe separarse con cuatro espacios en blanco.

    if ($a != 2) {
        
    $a 2;
    }

    If the conditional statement causes the line length to exceed the maximum line length and has several clauses, you may break the conditional into multiple lines. In such a case, break the line prior to a logic operator, and pad the line such that it aligns under the first character of the conditional clause. The closing paren in the conditional will then be placed on a line with the opening brace, with one space separating the two, at an indentation level equivalent to the opening control statement.

    if (($a == $b)
        &
    amp;&amp; ($b == $c)
        || (
    Foo::CONST == $d)
    ) {
        
    $a $d;
    }

    The intention of this latter declaration format is to prevent issues when adding or removing clauses from the conditional during later revisions.

    Para las declaraciones "if" que incluyan "elseif" o "else", las convenciones de formato son similares a la construcción "if". Los ejemplos siguientes demuestran el formato correcto para declaraciones "if" con construcciones "else" y/o "elseif":

    if ($a != 2) {
        
    $a 2;
    } else {
        
    $a 7;
    }

    if (
    $a != 2) {
        
    $a 2;
    } elseif (
    $a == 3) {
        
    $a 4;
    } else {
        
    $a 7;
    }

    if ((
    $a == $b)
        &
    amp;&amp; ($b == $c)
        || (
    Foo::CONST == $d)
    ) {
        
    $a $d;
    } elseif ((
    $a != $b)
              || (
    $b != $c)
    ) {
        
    $a $c;
    } else {
        
    $a $b;
    }

    PHP permite escribir sentencias sin llaves -{}- en algunas circunstancias. Este estándar de código no hace ninguna diferenciación- toda sentencia "if", "elseif" o "else" debe usar llaves.

    El uso de la construcción "elseif" está permitido pero no se aconseja, en favor de la combinación "else if".

    C.4.6.2. Switch

    Las declaraciones de control escritas con la declaración "switch" deben tener un único espacio en blanco antes del paréntesis de apertura del condicional y después del paréntesis de cierre.

    Todo contenido dentro de una declaración "switch" debe separarse usando cuatro espacios. El contenido dentro de cada declaración "case" debe separarse usando cuatro espacios adicionales.

    switch ($numPeople) {
        case 
    1:
            break;

        case 
    2:
            break;

        default:
            break;
    }

    La construcción default no debe omitirse nunca en una declaración switch .

    [Nota] Nota

    NOTA: En ocasiones, resulta útil escribir una declaración 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 declaración donde break o return sean omitidos deberán contener un comentario indicando que se omitieron intencionadamente.

    C.4.7. Documentación integrada

    C.4.7.1. Formato de documentación

    Todos los bloques de documentación ("docblocks") deben ser compatibles con el formato de phpDocumentor. Describir el formato de phpDocumentor está fuera del alcance de este documento. Para más información, visite: http://phpdoc.org/

    Todos los archivos de clase deben contener un bloque de documentación "a nivel de archivo" al principio de cada archivo y un bloque de documentación "a nivel de clase" inmediatamente antes de cada clase. Ejemplo de estos bloques de documentación pueden encontrarse debajo.

    C.4.7.2. Archivos

    Cada archivo que contenga código PHP debe tener un bloque de documentación al principio del archivo que contenga como mínimo las siguientes etiquetas phpDocumentor:

    /**
     * Descripción corta del fichero
     *
     * Descripción larga del fichero (si la hubiera)...
     *
     * LICENSE: Some license information
     *
     * @category   Zend
     * @package    Zend_Magic
     * @subpackage Wand
     * @copyright  Copyright (c) 2005-2011 Zend Technologies USA Inc. (http://www.zend.com)
     * @license    http://framework.zend.com/license   BSD License
     * @version    $Id:$
     * @link       http://framework.zend.com/package/PackageName
     * @since      File available since Release 1.5.0
    */

    The @category annotation must have a value of "Zend".

    The @package annotation must be assigned, and should be equivalent to the component name of the class contained in the file; typically, this will only have two segments, the "Zend" prefix, and the component name.

    The @subpackage annotation is optional. If provided, it should be the subcomponent name, minus the class prefix. In the example above, the assumption is that the class in the file is either " Zend_Magic_Wand ", or uses that classname as part of its prefix.

    C.4.7.3. Clases

    Cada clase debe contener un bloque de documentación que contenga como mínimo las siguientes etiquetas phpDocumentor:

    /**
     * Descripción corta de la clase
     *
     * Descripcion larga de la clase (si la hubiera)...
     *
     * @category   Zend
     * @package    Zend_Magic
     * @subpackage Wand
     * @copyright  Copyright (c) 2005-2011 Zend Technologies USA Inc. (http://www.zend.com)
     * @license    http://framework.zend.com/license   BSD License
     * @version    Release: @package_version@
     * @link       http://framework.zend.com/package/PackageName
     * @since      Class available since Release 1.5.0
     * @deprecated Class deprecated in Release 2.0.0
     */

    The @category annotation must have a value of "Zend".

    The @package annotation must be assigned, and should be equivalent to the component to which the class belongs; typically, this will only have two segments, the "Zend" prefix, and the component name.

    The @subpackage annotation is optional. If provided, it should be the subcomponent name, minus the class prefix. In the example above, the assumption is that the class described is either " Zend_Magic_Wand ", or uses that classname as part of its prefix.

    C.4.7.4. Funciones

    Cada función, incluyendo métodos de objeto, debe contener un bloque de documentación que contenga como mínimo:

    • Una descripción de la función

    • 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 función.

    Si una función/método puede lanzar una excepción, utilice @throws para todos los tipos de excepciones conocidas:

    @throws exceptionclass [description]
    digg delicious meneame google twitter technorati facebook

    Comentarios

    Loading...