Sub- área

CPC

Estándar de
Programación de PHP y
SIU - Toba

Año 2014 - Versión 2.1

Acceso Norte Ruta Nacional Nº3 Caleta Olivia (9011) Santa Cruz TEL. +54 297 4854888 Int 114
e-mail: [email protected]
 P A S
P l a n d e A c c i ó n
d e S i s t e m a s

Este documento cumple con las pautas establecidas por el Plan de Acción de Sistemas para la
generación de documentación.

La información contenida en este documento está sujeta a modificaciones.

Autores
Diaz, Miriam Rosana
Farias, Roberto Adrián
Miranda, María Gabriela
Molina, Sonia Elizabeth

® Impreso en el PAS

2/23 EST_PROGRAMACION PHP_SIU-TOBA_V2.1.odt

 P A S
P l a n d e A c c i ó n
d e S i s t e m a s

Contenido
1. INTRODUCCIÓN..........................................................................................................................................4
1.1. Alcance del documento............................................................................................................................4
1.2 Referencias...............................................................................................................................................4
1.3 Definiciones..............................................................................................................................................4
2. LINEAMIENTOS PARA LA CODIFICACIÓN EN EL FRAMEWORK SIU - TOBA.............................5
2.1 Formato del Archivo.................................................................................................................................5
2.2 Organización del Proyecto.......................................................................................................................5
2.3 Convención de Nombres...........................................................................................................................6
2.4 Estilos de Codificación.............................................................................................................................7
3.LINEAMIENTOS PARA LA CODIFICACIÓN EN PHP..........................................................................13
3.1 Formato del Archivo ..............................................................................................................................13
3.2 Organización del Proyecto.....................................................................................................................13
3.3 Convención de Nombres ........................................................................................................................14
3.4 Estilos de Codificación...........................................................................................................................15
4. RECOMENDACIONES PARA EL PROGRAMADOR.............................................................................19
4.1 Manejo de Excepciones..........................................................................................................................19
4.2 Seguridad en el Código..........................................................................................................................20
4.3 Depuración del Código Fuente..............................................................................................................22
4.4 Formularios y Validaciones...................................................................................................................22
4.5 Documentación Automática del Código.................................................................................................23
4.6 En cuanto a la organización de archivos .............................................................................................23

EST_PROGRAMACION PHP_SIU-TOBA_V2.1.odt 3/23

 P A S
P l a n d e A c c i ó n
d e S i s t e m a s

1. Introducción
En el presente documento se describe el estándar definido desde el PAS a utilizar en el
desarrollo de cualquier aplicación, blog, sistema y/o sitio de la UNPA que se implemente bajo el
lenguaje de script PHP y/o el framework SIU - toba.

1.1. Alcance del documento

El documento esta dirigido a todos los integrantes del PAS y equipos subcontratados
que desarrollen sitios y aplicaciones bajo el lenguaje de desarrollo PHP o framework SIU – Toba.

1.2 Referencias
 EST_DESARROLLO DE SITIOS Y APLICACIONES WEB_UNPA_V1.0.
 pear.php.net/manual/en/standards.php
 toba.siu.edu.ar/trac/toba/wiki/Convenciones/Codigo
 www.w3.org/TR/WCAG20-TECHS/

1.3 Definiciones
 Accesibilidad Web (Web Accessibility Initiative – WAI) 1: se refiere a la capacidad de acceso
a la Web y a sus contenidos por todas las personas independientemente de la discapacidad
(física, intelectual o técnica) que presenten o de las que se deriven del contexto de uso
(tecnológicas o ambientales). Esta cualidad está íntimamente relacionada con la usabilidad.
 Aplicación web: las aplicaciones web pueden considerarse como un sitio web al que se accede
a través de un navegador, pero dotado de interactividad para la gestión, una base de datos,
comunicaciones encriptadas y contraseñas de acceso.
 CSS (Cascading Style Sheets) 2: es un lenguaje para la definición de hojas de estilo que
describe la representación semántica (apariencia/ formato) de un documento escrito bajo algún
lenguaje de marcado. Su aplicación más común es páginas web desarrolladas bajo HTML y
XHTML, pero el lenguaje también se puede aplicar a cualquier tipo de documento XML, incluida
XML plano, SVG y XUL.
 IDE (Integrated Development Environment): es una aplicación software que provee la
facilidades al programador para el desarrollo del software. El IDE generalmente se compone de:
Editor de código fuente, herramientas automáticas para la generación de código, y un depurador
de código.
 HTML: siglas de HyperText Markup Language (Lenguaje de Marcado de Hipertexto), es el
lenguaje de marcado predominante para la elaboración de páginas web. Es usado para describir
la estructura y el contenido en forma de texto, así como para complementar el texto con objetos
tales como imágenes.
 Sitio web: es una colección de páginas web relacionadas y comunes a un dominio web o sub-
dominio en la World Wide Web en Internet.

1
www.w3.org/WAI/
2
www.w3.org/Style/CSS/Overview.en.html

4/23 EST_PROGRAMACION PHP_SIU-TOBA_V2.1.odt

 P A S
P l a n d e A c c i ó n
d e S i s t e m a s

2. Lineamientos para la Codificación en el framework SIU - Toba

La codificación de los desarrollos de aplicaciones o sistemas web transaccionales,
realizados desde el PAS, se realizará utilizando el entorno de desarrollo Web SIU- Toba. Esta
herramienta de desarrollo rápido posee una arquitectura basada en componentes y una IDE de
edición propia. Creado por SIU y con licencia de software libre. A continuación se presenta el
estándar a utilizar dentro de este framework:

2.1 Formato del Archivo

 Codificación
Los sistemas web desarrollados bajo el framework SIU - Toba requieren usar la
codificación ISO-8859-1 o también llamada LATIN1, con lo cual es preciso que todos los
archivos .php del proyecto tengan esa codificación.

 Legibilidad

La indentación debe ser a 4 (cuatro) espacios sin caracteres de tabulación. Esto es

debido a que ciertos IDE’s (Integrated Development Environment - Entorno integrado de
desarrollo) de desarrollo introducen caracteres de tabulación cuando indentan un texto
automáticamente.

 Ancho de Línea

• Evitar líneas de más de 80 caracteres de largo.

2.2 Organización del Proyecto

A continuación se presenta la organización interna que deberá seguir los desarrollos
(proyectos) bajo el framework SIU- Toba. Dentro del directorio SIU – Toba, uno de los directorios
principales donde se alojan los proyectos creados bajo el framework SIU – Toba corresponde a:

 proyectos: Este directorio contiene los proyectos propios del ambiente y deberá alojar además
los nuevos proyectos creados por el programador. La organización interna mínima que se deberá
utilizar para cada proyecto es la siguiente:
• ...
• mi_proyecto :
✔ metadatos: Contiene la última exportación de metadatos del proyecto.
✔ php: Directorio que será parte del include_path de PHP, se asume que el proyecto
almacenará aquí sus extensiones y demás código.
 login: En este directorio se alojarán los archivos php relacionados al login.
 operaciones: Este directorio contendrá los Controladores de Interfaz (CI)
agrupados por menú a utilizar.
 Modelo: en este directorio se ubicarán las clases del modelo de dominio.
✔ Sql: ubicar en este directorio las consultas sql utilizadas por el proyecto.
✔ temp: Directorio temporal no-navegable propio del proyecto
✔ www: Directorio navegable que contiene los puntos de acceso a la aplicación.
 css: Plantillas de estilos CSS del proyecto.
 img: Imágenes propias del proyecto.
 temp: Directorio temporal navegable del proyecto.

EST_PROGRAMACION PHP_SIU-TOBA_V2.1.odt 5/23

 P A S
P l a n d e A c c i ó n
d e S i s t e m a s

• otro_proyecto:

2.3 Convención de Nombres

 Clases
• Los nombres de las clases son sustantivos y se definirán en singular. La inicial del
nombre se escribirá en mayúscula. En caso de componerse de más de una palabra, la
primera letra de cada palabra se escribirá en mayúscula, ejemplo:
CuentaBancaria
• Para el caso de subclases de componentes toba, los primeros caracteres del nombre del
archivo identificarán el tipo de archivo:

Tabla 1: Abreviaturas de Componentes

Componente Abreviatura
Controlador de Interface ci
Controlador de Negocio cn
Datos Tabla dt
Formulario Común form
Formulario Multilinea ml
Filtro filtro
Métodos de Consultas y dao
recuperación de datos

• El nombre de la clase debe coincidir con el nombre del archivo (sin la extensión .php).

 Constantes
• Las constantes deberán siempre definirse toda en mayúscula, con guión bajo si se
compone de más de una palabra para separarlas si fuese necesario. Ejemplos:
DB_DATASOURCENAME

 Funciones
• Las funciones globales deberán definirse anteponiendo el nombre del paquete y/o sub-
paquete que lo contiene en mayúscula con el fin de evitar la colisión de nombres entre
paquetes. La inicial del nombre (después del prefijo) deberá definirse en minúscula y cada
letra que inicie una nueva palabra deberá escribirse en mayúscula . Ejemplo:
XML_RPC_serializeData()

 Atributos y Métodos
• Los atributos se deberán definir en minúscula y en caso de componerse de más de una
palabra, a partir de la segunda palabra, la inicial de cada palabra deberá escribirse en
mayúscula. Ejemplo:
$colegioSecundario
• Los métodos son verbos o frases verbales. El nombre del método deberá escribirse en
minúscula. Si el nombre se compone de más de una palabra, la inicial de la palabras
consecutivas deberá indicarse en mayúscula. Ejemplo:
buscarPersona()

6/23 EST_PROGRAMACION PHP_SIU-TOBA_V2.1.odt

 P A S
P l a n d e A c c i ó n
d e S i s t e m a s

 Variables globales
• Si dentro de un paquete se tienen que definir variables globales, sus nombres deben
comenzar con un solo guión bajo seguido del nombre del paquete y otro guión bajo. Por
ejemplo, para el paquete PEAR una variable global se podría definir como:
$_PEAR_destructor_object_list

2.4 Estilos de Codificación

 Comentarios
• General
El estilo de los comentarios debe ser ( // ). 
• Archivos
✔ Todo archivo deberá incluir un Bloque de Documentación en la parte superior con los
siguientes tags como mínimo:
//**
// * Fecha de creación: dd/mm/aaaa
// * Descripción extendida del archivo: corresponde a la 
//funcionalidad del Código. 
// * Copyright: [Ej. 2013 Plan de Acción de Sistemas]
// * Autor/es:
// * Versión:
// * Desde: archivo disponible desde la versión x.x.x 
//* Archivos Asociados: indicar archivos que son necesarios para la 
//compilación del programa
//  (ej. ficheros .h)
//**

• Clases
✔ Las clases deberán incluir un Bloque de Documentación en la parte superior con los
siguientes tags como mínimo:
//**
// * Descripción corta de la clase
// * copyright  2014 Plan de Acción de Sistemas
// * 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
// **

• Funciones
✔ Todas las funciones y los métodos deberán tener un Bloque de Documentación conteniendo
como mínimo:
//*
//* Descripción de la función
//* Parámetros: Descripción de los parámetros que se le pasan y que 
//devuelve. Si es relevante, también se indicará la siguiente 
//información:

EST_PROGRAMACION PHP_SIU-TOBA_V2.1.odt 7/23

 P A S
P l a n d e A c c i ó n
d e S i s t e m a s

//Condiciones de entrada
//Condiciones de salida:
//Enumeración de otras funciones que utiliza
//Enumeración de las funciones que le utilizan
//* Modificaciones: Si es relevante, también se indicará una 
//breve //historia de todas las modificaciones realizadas, 
//indicando el //programador que las realizó y el motivo que las 
//causó.
//*

 Variables
• Para contadores usar nombre cortos y sin significado especial como:
$i, $j, $k
• En general evitar usar nombres como $temp o $parametro, al menos indicar el rol dentro de
este bloque de código, por ejemplo:
$nombre_temp
• Inicializar las variables al comienzo del método. Para las variables de clase es preferible darles
un valor por defecto en su definición en lugar de hacerlo en el constructor. Ejemplo:

<?php

    class mi_clase
    {
        protected $es_inicial = false;
    }

?>
✔ Usar type hinting para tipos de variable que son de una clase conocida, aunque a
veces quita flexibilidad y tiempo de ejecución, aumenta mucho la legibilidad y permite a los
editores de código hacer autocomplete. Ejemplo:
   <?php

    function conf__form(toba_ei_formulario $form)
    {

    }

?>

 Clases
• Archivo
✔ Definir una única clase por archivo .
✔ El nombre de la clase debe coincidir con el nombre del archivo (sin la extensión .php) .

• Declaración
✔ Las llaves de inicio y fin deberán estar en una línea propia. Ejemplo:
<?php

8/23 EST_PROGRAMACION PHP_SIU-TOBA_V2.1.odt

 P A S
P l a n d e A c c i ó n
d e S i s t e m a s

class ci_navegacion
{
    /*   .. propiedades

        métodos
    */

?> 

• Tipos de Clases
✔ Representan una instancia particular (singleton): Tiene servicios para manipular a una sola
unidad se nombran en singular. Es la forma recomendada de POO (programación orientada
a objetos), aunque a veces puede ser ineficiente (requiere crear N objetos) .

$novedad = new novedad();
$novedad­>set_fecha($fecha);
$novedad­>eliminar();

✔ Representan el conjunto: Tiene servicios para manipular todas las unidades que
representan, se nombran en plural.
$novedades = new novedades();
$novedades­>set_fecha($cod_novedad, $fecha)
$novedades­>eliminar($cod_novedad);

 Funciones Y Métodos
• Declaración
✔ Las llaves de inicio y fin de la función y/o método están en una línea propia
✔ Luego de cada coma que separa un parámetro, va un espacio de separación.
✔ Los parámetros que tienen valores por defecto van al final de la lista de parámetros.
✔ Si los argumentos dentro de una función exceden los 80 caracteres, los parámetros que se
ubiquen en la siguiente linea deberán indentarse con cuatro espacios simples. El paréntesis
de cierre y la llave de apertura deberán ubicarse en la siguiente linea.
Function   someFunctionWithAVeryLongName($firstParameter   = 
'something', $secondParameter = 'other', $thirdParameter = 'etc'
){
}
✔ Los métodos de obtención y seteo de atributos se deberían denominar con el prefijo get y
set respectivamente. Lo que sigue al get o set va en singular o plural según el contenido sea
uno o un conjunto. Por ejemplo get_persona devuelve una persona y get_personas devuelve
un array de personas (cero o más). Ejemplo:

<?php

class nombre_clase
{
    protected function set_nombre($param1, $param2=null)
    {
    

EST_PROGRAMACION PHP_SIU-TOBA_V2.1.odt 9/23

 P A S
P l a n d e A c c i ó n
d e S i s t e m a s

    }

    function get_nombre()
    {
    
    }
}

?> 

• Invocación
✔ La función debe ser invocada sin espacios entre el nombre de la misma, el paréntesis de
apertura y el primer parámetro.
✔ Luego de cada coma que separa un parámetro va un espacio. No deberá dejarse espacio
entre el último parámetros, el paréntesis de cierre y el punto y coma.
<?php
$var= foo($bar, $baz, $bat);
?>

• Alineación de asignaciones
✔ Para mejorar la legibilidad, si tengo más de una asignación en una misma porción de código,
se deberán alinear los signos igual (=) como se muestra a continuación:

<?php
$short  = foo($bar);
$longer = foo($baz);
?>

• Complejidad: una forma de medir la complejidad de un método es el número de niveles

(scopes) en su implementación:
✔ Se recomienda no superar los 5 niveles. A partir de allí el validador de convenciones de
Toba lanzará una advertencia
✔ Luego de 10 niveles el validador recomendará refactorizar el método.

 Estructuras de Control
• Sintaxis
✔ Las estructuras if, for, foreach, while y do while deben tener un espacio entre la palabra
reservada y el paréntesis que abre, para poder distinguirlos de las llamadas a funciones:

<?php

if ((condicion1) || (condicion2)) {
    accion1;
} elseif ((condicion3) && (condicion4)) {
    accion2;
} else {
    accionPorDefecto;
}

10/23 EST_PROGRAMACION PHP_SIU-TOBA_V2.1.odt

 P A S
P l a n d e A c c i ó n
d e S i s t e m a s

?>

✔ Siempre se usan llaves, incluso cuando son técnicamente opcionales (Ej. una única
sentencia dentro del if).
✔ Sentencias if con demasiadas condiciones. La primera condición alinea a las otras
condiciones.

<?php
if (   $condicion1
  || $condicion2
  || $condicion3
 ) {
//acá va el código
 }
?>

✔ Para las sentencias switch:

<?php

      switch (condicion) {
     case 1:
          accion1;
          break;

   case 2:
         accion2;
         break;

 default:
           accion_por_defecto;
           break;
}

?>

• Complejidad Ciclomática
La cantidad de caminos independientes dentro de un fragmento de código se recomienda que
no supere una complejidad de 10. Si un método excede la complejidad de 20 el compilador
propio del framework lanzará un error.

 Arreglos
• Acceso
✔ No usar espacios entre los corchetes. Ejemplo:
<?php

//Correcto
$valor = $arreglo[$indice];

EST_PROGRAMACION PHP_SIU-TOBA_V2.1.odt 11/23

 P A S
P l a n d e A c c i ó n
d e S i s t e m a s

//Incorrecto
$valor = $arreglo[ $indice ];

?>

✔ Las asignaciones en los arreglos deben estar alineadas. Ejemplo:

<?php
$some_array = array(
     'foo' => 'bar',
    'spam' => 'ham',
);
?> 

 Consultas y Comandos SQL

La idea es que sea legible y fácil de mantener (nuevos campos, nuevos joins, etc.). Un
ejemplo:
<?php

$sql = "SELECT
            t1.fecha_baja,
            t1.campo            as campo_1,
            t2.campo_con_nombre_largo   as campo_2,
            t2.campo_sin_alias
        FROM
            tabla1 t1,
            tabla2 t2 
                LEFT OUTER JOIN tabla3 t3 ON (t2.nombre = 
t3.nombre)
                LEFT OUTER JOIN tabla3 t4 ON (t2.nombre = 
t4.nombre)
        WHERE
                t1.condicion = t2.condicion
            AND t1.activo = 1
            AND (t1.activo = 1 OR t1.activo IS NULL)
        ORDER BY fecha_baja
";
$rs = toba::db()­>consultar($sql);
?>

• Generales
✔ Se usan mayúsculas para las palabras reservadas y funciones SQL. El resto es todo
minúsculas.
✔ Siempre definir la consulta/comando en una variable propia, así es más fácil depurarla.
✔ Termina la cadena en una línea nueva, así es posible seguir agregando cosas fácilmente al
final.
✔ En caso de usarse alias para campos o tablas, alinearlos usando tabs.

• Campos en el SELECT
✔ Siempre explicitar el alias de la tabla usada, por ejemplo: t1.campo
✔ Preferir usar el nombre original del campo, sólo usar alias de campos para eliminar la
ambigüedad o aclarar situaciones. En caso de tener dos campos con igual nombre en el

12/23 EST_PROGRAMACION PHP_SIU-TOBA_V2.1.odt

 P A S
P l a n d e A c c i ó n
d e S i s t e m a s

select (por ejemplo llamados descripción) tanto el motor, pdo y toba no dan error. Lo que se
hace es reemplazar el valor en el arreglo asociativo, creando bugs difíciles de rastrear.

• Tablas FROM
✔ Siempre incluir un alias para la tabla, ser consistente con el alias usado para el resto de las
consultas.
✔ Para poder usar el esquema de perfiles de datos de toba, los inner joins se deben declarar
de la forma 'clásica' separando las tablas por coma, no reconoce las cláusulas 'INNER JOIN'
en el from.

• Condiciones WHERE
✔ Siempre usar quote para las partes dinámicas de la consulta.

3.Lineamientos para la Codificación en PHP

3.1 Formato del Archivo
 Codificación
• Los sistemas web PHP preferentemente deberían usar la codificación UTF8, para lo cual es
preciso que todos los archivos .php del proyecto tengan esa codificación.

 Legibilidad
• El código deberá estar debidamente identado.

 Ancho de linea

• Evitar líneas de más de 80 caracteres de largo.

3.2 Organización del Proyecto

En proyectos web o aplicaciones, se tendrán las siguientes carpetas:
• / [Carpeta raíz]: Corresponde al directorio que contiene la aplicación o sitio web.]. Este
nombre deberá ser reemplazada por el nombre de la aplicación a desarrollar.
• files: Aquí irán los archivos .php a los que accede el usuario directamente, interfaz, etc.
• clases: Una carpeta conteniendo exclusivamente las clases usadas en el proyecto
• includes: Todos los archivos que sean llamados por otros .php en forma de módulos o de
librerías de funciones.
• db: En caso de tener la posibilidad de usar varias bases de datos, aquí colocaremos los .php
que manejen esas características multicapa para cada sistema de datos soportado.
• images: Aqui se ubicarán las imágenes que se utilicen desde el proyecto (por ejemplo jpg,
png, etc). En caso de usar un sistema de plantillas (Como smarty o el de phpBB), aquí
guardaremos todos los archivos .tpl
• css: en este directorio se almacenarían las hojas de estilo usadas por en el proyecto de
desarrollo.

EST_PROGRAMACION PHP_SIU-TOBA_V2.1.odt 13/23

 P A S
P l a n d e A c c i ó n
d e S i s t e m a s

3.3 Convención de Nombres

 Archivos
• Las denominaciones de las páginas web deberán expresarse en minúsculas. Si el nombre se
compone de más de una palabra, las mismas deberán separarse por la inicial de la segunda
palabra en mayúsculas.
• Cualquier archivo que contiene código PHP debe terminar con la extensión,”php”. Por
ejemplos:
- inicio.php
- listarPersona.php

 Array
• Para la definición del nombre de los Arrays se seguirá la convención de utilizar la abreviatura
(ver Tabla 2) seguido de un nombre representativo para el array, por ejemplo: arAlumnos 
(representa un arreglo de datos para guardar información de los alumnos).

 Clases
• Los nombres de las clases son sustantivos y se definirán en singular. La inicial del nombre
se escribirá en mayúscula. En caso de componerse de más de una palabra, la primera letra
de cada palabra se escribirá en mayúscula, ejemplo:

HistoriaClinica

 Constantes
• Todas las letras utilizadas en un nombre de constante deben ser mayúsculas.
• Las palabras que forman el nombre de la constante deben estar separados por Underscore
(Guión bajo). Por ejemplo:

EMBED_SUPPRESS_EMBED_EXCEPTION

 Funciones
• Las funciones propias son verbos o frases verbales, y se escribirán en minúscula, si el nombre
consiste en más de una palabra la primera letra de cada una de ella deberá ser mayúscula.
• Las funciones globales deberán definirse anteponiendo el nombre del paquete y/o sub-
paquete que lo contiene en mayúscula con el fin de evitar la colisión de nombres entre
paquetes. La inicial del nombre (después del prefijo) deberá definirse en minúscula y cada
letra que inicie una nueva palabra deberá escribirse en mayúscula . Ejemplo:
XML_RPC_serializeData()

 Atributos y Métodos
• Definir el nombre del atributo en función del tipo de dato a almacenar. Dicho nombre
comenzará siempre con la primera letra minúscula correspondiente a su tipo de dato.
Ejemplo: iEdad
A continuación se detallan las abreviaturas a utilizar para cada tipo de dato:

Tabla 2: Abreviaturas de Tipos de Datos

Tipo de Dato Abreviatura
integer i
float f

14/23 EST_PROGRAMACION PHP_SIU-TOBA_V2.1.odt

 P A S
P l a n d e A c c i ó n
d e S i s t e m a s

Tipo de Dato Abreviatura

double d
arreglo ar
char c
enumeración e
punteros p
string s

• Los métodos son verbos o frases verbales, y se escribirán en minúscula, si el nombre consiste
en más de una palabra la primera letra de cada una de ella deberá ser mayúscula.

 Variables
• El nombre de las variables o atributos debe estar compuesto de caracteres alfanuméricos, el
carácter guión bajo (_) no está permitido.
• Los nombres de variables siempre tiene que comenzar con letra minúscula, si el nombre
consiste en más de una palabra la primera letra de cada una de ella deberá ser mayúscula.
Por ejemplo: sNombreCompleto
• Las variables siempre debe ser lo más detallado posible al describir los datos que se tiene la
intención de almacenar en ellos.
• Definir el nombre la variable/ atributo en función del tipo de dato a almacenar. Dicho nombre
comenzará siempre con la primera letra minúscula correspondiente a su tipo de dato (ver
Tabla 2). Ejemplo: iDomicilio

3.4 Estilos de Codificación

 Comentarios
• Archivos
✔ Todo archivo con Código PHP deberá incluir un Bloque de Documentación en la parte
superior con los siguientes tags como mínimo:
//**
// * Fecha de creación:
// * Descripción extendida del archivo: corresponde a la 
//funcionalidad del Código. 
// * Copyright: [Ej. 2013 Plan de Acción de Sistemas]
// * Autor/es:
// * Versión:
// * Desde: archivo disponible desde la versión x.x.x 
// * Modificaciones: Si es relevante, también se indicará una breve 
//historia de todas las modificaciones realizadas, indicando el 
//programador que las realizó y el motivo que las causó.
//* Archivos Asociados: indicar archivos que son necesarios para la 
//compilación del programa
//  (ej. ficheros .h)
//**

• Clases

EST_PROGRAMACION PHP_SIU-TOBA_V2.1.odt 15/23

 P A S
P l a n d e A c c i ó n
d e S i s t e m a s

Las clases deberán incluir un Bloque de Documentación en la parte superior con los
✔
siguientes tags como mínimo:
//**
// * Descripción corta de la clase
// * copyright  2014 Plan de Acción de Sistemas
// * license http://www.unpa.edu.ar/pas/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
//**
• Funciones
✔ Todas las funciones y los métodos deberán tener un Bloque de Documentación conteniendo
como mínimo:
//**
//* Descripción de la función
//* Parámetros: Descripción de los parámetros que se le pasan y que 
//devuelve.   Si   es   relevante,   también   se   indicará   la   siguiente 
//información:
//Condiciones de entrada
//Condiciones de salida:
//Enumeración de otras funciones que utiliza
//Enumeración de las funciones que le utilizan
//* Modificaciones: Si es relevante, también se indicará una breve 
historia   de   todas   las   modificaciones   realizadas,   indicando   el 
programador que las realizó y el motivo que las causó.
//**

 PHP Código de Delimitación

• Todo código PHP debe estar delimitado por los tags estándares (los cortos no están
permitidos). No utilice el método de etiquetas cortas, por que esto depende de las directivas de
configuración en el archivo PHP.INI y hace que el script no sea tan portable.
<?php      
       
?>

 Inclusión de archivos

• Cuando se incluya un archivo de dependencia incondicionalmente utilice require_once y

cuando sea condicionalmente, utilice include_once.

 String Literales
• Cuando se le asigna un texto literal (sin contenido de variables) se utilizarán comillas simples.
Por ejemplo:
$a = 'Texto de ejemplo';

16/23 EST_PROGRAMACION PHP_SIU-TOBA_V2.1.odt

 P A S
P l a n d e A c c i ó n
d e S i s t e m a s

• Cuando el texto literal contiene apostrofes, estará permitido la utilización de comillas dobles.
Esto es usado comúnmente en las sentencias SQL. Por ejemplo:
$sql = "SELECT id, name from people "
         . "WHERE name='Fred' OR name='Susan'";

 Concatenación
• Para concatenar Strings se utilizará el operador “.” (punto), con un espacio entre medio para
mejorar la lectura. Ejemplo:

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

 Arrays
• En aquellos arrays de índices numéricos estos deberán ser números positivos.
• En la declaración de los valores del array se dejará un espacio en blanco luego de la coma
para mejorar la lectura. Por ejemplo:

$arSampleArray = array(1, 2, 3, 'Zend', 'Studio');

• En caso que se necesiten varias líneas en la construcción del array, se indentará cada una
donde empezó la primera. En el caso de los arrays asociativos, se hace un quiebre de línea
por cada clave y valor.
<?php
$arSsampleArray = array(
   'firstKey'  => 'firstValue',
   'secondKey' => 'secondValue'
);
?>

 Clases

• Declaración de Clases.
✔ La llave debe estar siempre por escrito en la línea debajo del nombre de la clase.
✔ Cada clase debe tener un bloque de documentación inicial que indica la razón de ser de la
clase.
✔ Todo el código de una clase debe tener una sangría de cuatro espacios.
✔ Sólo se permite una clase en cada archivo PHP. Esto permitirá la búsqueda e identificación
de las clases.
✔ Colocar el código adicional en los archivos de clase se permite pero no se recomienda. En
este tipo de archivos, dos líneas en blanco debe separar la clase desde cualquier código
adicional de PHP en el archivo de clase. Ejemplo:

// Documentation Block Here

class SampleClass
{
  // Todo el contenido de la clase aquí
  // identada por cuatro espacios
}

EST_PROGRAMACION PHP_SIU-TOBA_V2.1.odt 17/23

 P A S
P l a n d e A c c i ó n
d e S i s t e m a s

✔ Las clases que se extienden a otras clases o implementan interfaces deben declarar sus
dependencias en la misma línea cuando sea posible. Ejemplo:
class SampleClass extends FooAbstract implements BarInterface
{

✔ Si como resultado de la declaración descripta en el ítem anterior, la longitud de la línea

supera la longitud máxima de 80 caracteres considerando además los espacios, truncar la
línea antes del "extends” y/o " implements " u otras palabras claves usadas, y se debe
respetar la indentacion. Ejemplo:
 class SampleClass
           extends FooAbstract
           implements BarInterface
{

 Métodos y Funciones

• Declaración de Métodos y Funciones

✔ Las funciones deben ser llamadas sin espacios entre el nombre de la función. Siempre tiene
que comenzar con letra minúscula, si el nombre consiste en más de una palabra la primera
letra de cada una de ella deberá ser mayúscula. Por ejemplo:
getElementById(), widgetFactory()
✔ Métodos dentro de las clases siempre se debe declarar su visibilidad mediante uno de los
modificadores private, protected, o public.
✔ El espacio entre el nombre de la función y el paréntesis de apertura de los argumentos no
está permitido.
Ejemplo 1:
// Documentation Block Here
class Foo
{
     //   Documentation Block Here 
      public function bar()
      {
                 // Todo el contenido de la función
                 // indentado por cuatro espacios vacíos
      }
 }

Ejemplo 2:
// Documentation Block Here 
class Foo
{
   //  Documentation Block Here  //

18/23 EST_PROGRAMACION PHP_SIU-TOBA_V2.1.odt

 P A S
P l a n d e A c c i ó n
d e S i s t e m a s

     public function bar($arg1, $arg2, $arg3,
      $arg4, $arg5, $arg6  ) 
      {
              //  Todo el contenido de la función 
              //  identado por cuatro espacios vacíos
      }
}

 Estructura de Control

• If/Else/Elseif
✔ En las declaraciones if/then/else se deberá tener un espacio antes y después del paréntesis
condicional, en la misma línea se abre llave y se cierra en una línea diferente, lo mismo se
aplica al elseif. Por ejemplo:

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

• Switch
✔ Las sentencias de control escritas con la declaración "switch" deben tener un espacio antes
del paréntesis de apertura de la sentencia condicional y después del paréntesis de cierre.
✔ Todo el contenido dentro de la declaración "switch" debe separarse usando cuatro espacios.
✔ El contenido dentro de cada "case" debe separarse con cuatro espacios de indentacion.
Ejemplo:
switch ($numPeople) {
    case 1:
         break;
    case 2:
         break;
    default:
        break;
}

4. Recomendaciones para el Programador

4.1 Manejo de Excepciones
• Utilizar excepciones de manera controlada. Evitar el uso de excepciones dentro de bucles.

EST_PROGRAMACION PHP_SIU-TOBA_V2.1.odt 19/23

 P A S
P l a n d e A c c i ó n
d e S i s t e m a s

4.2 Seguridad en el Código

 Inyección de variables

• Inicializar siempre todas las variables. Las variables no inicializadas pueden causar que se
ejecuten secciones del código no esperadas.

<?php

    if (correct_user($_POST['user'], $_POST['password']) {

        $login = true;

    if($login) {

        forward_to_secure_environment();

?>

Como se visualiza en el código de ejemplo anterior, si no se inicializa una variable, se puede

correr el riesgo que la variable se inicialice maliciosamente desde la url, por ejemplo con la url
http://example.com/form1.php?login=1 se ejecutará el segundo If de manera incorrecta.

• Evitar utilizar variables para la incorporación de archivos y/o código. Facilitan la ejecución de
código externo malicioso. Para ello verificar en la configuración del php.ini el valor de la
variable allow_url_fopen, por defecto esta seteado en On, cambiar al valor Off.

• Si se utilizan variables para incorporar archivos, validar los mismos utilizando listas fijas
implementadas con arreglos o con swtichs, etc.

<?php

    $valid_files = array(

        'show' => 'show.php',

        'list' => 'list.php'.

    );

    if (isset($valid_files[$_GET['action']] ) )    {

       require_once $valid_files[$_GET['action']];

     } else    {

           echo 'not a valid action. ';

    }

?>

 Inyección de comandos en SQL

• Usar funciones de escape o consultas preparadas.

20/23 EST_PROGRAMACION PHP_SIU-TOBA_V2.1.odt

 P A S
P l a n d e A c c i ó n
d e S i s t e m a s

/*ejemplo 1 – funciones de escape */

<?php

    $sql = 'SELECT password FROM user WHERE login = '.

        mysql_real_escape_string(  $_GET['login']  );

?>

/*ejemplo 2 – consultas preparadas*/

<?php

    $db = new PDO( ... );

        $stmt   =   $db­>prepare(   SELECT   password   FROM   user   WHERE   login 

= ?' );

      $stmt­>execute( array($_GET['login'] ) );  

?>

 Validación de datos de entrada

• Usar ext/ filter o ext/ ctype:

<?php

    var_dump(  ctype_alnum(  'una cadena')  );

    var_dump(  ctype_alnum(  'caracteres inválidos $%&/ ')  );

        var_dump(     filter_alnum(     '[email protected]', 

FILTER_VALIDATE_EMAIL )  );

    var_dump(  filter_alnum(  'example.com', 

               FILTER_VALIDATE_URL, FILTER_FLAG_SCHEME_REQUIRED )  );

?>

El resultado de ejecución del código anterior sería:

boolean false

boolean false

string '[email protected]' (length=15)

boolean false

 Procesar datos de salida

• Utilizar hojas de estilo externas garantizando amigabilidad del sitio.

 Seguridad por obscuridad

• Información acerca de las rutas, extensiones, y configuración, hace vulnerable al sistema a

posibles ataques.

EST_PROGRAMACION PHP_SIU-TOBA_V2.1.odt 21/23

 P A S
P l a n d e A c c i ó n
d e S i s t e m a s

 Configuración

• El procesamiento inapropiado de los datos, puede afectar en algunos casos la performance

del sistema, para mitigar este inconveniente se recomienda no utilizar magic_quotes3 en
producción (ni en desarrollo en lo posible), y utilizar las funciones de procesamiento
apropiadas.

 Cookies y sesiones

• Las cookies son fáciles de modificar por el usuario. Para ello se recomienda utilizar sesiones
para almacenar datos importantes.

• No almacenar claves de identificación como texto sencillo, es inseguro incluso en el servidor.

Utilizar una la función como md5(), sha1(), etc. para almacenar un valor que no puede ser
revertido a la cadena original.

• Al usar md5() (o sha1(), etc.), no hacerlo directamente en la clave, pues pueden escribirse
programas que traten de adivinar esta información en forma forzada. Concatenar con otra
información (ej. Nombre del servidor, del usuario, etc.), antes de procesar.

4.3 Depuración del Código Fuente

Utilizar un buen depurador. Algunos recomendados corresponden a:
• Xdebug 4.
• DBG 5.

4.4 Formularios y Validaciones

 Principios generales de codificación de formularios
Gran parte del trabajo que realizaran las aplicaciones web desarrollados en el PAS, será
procesar información que los usuarios ingresen a través de formularios HTML, con esos datos
podemos realizar operaciones en el momento o guardarlos a bases de datos. A partir de ello se
definen los siguientes criterios a aplicar:
• Todos los campos del formulario deberán tener una etiqueta de descripción “Label”.
• Los campos que se definen como obligatorios, deberán tener un asterisco en color
rojo del lado derecho del nombre, ser validados y mostrar mediante un mensaje de
error en caso de su ocurrencia. Esto incluye la validación del e-mail, si correspondiera
este campo.
• Todos los campos deberán tener un color de fondo para indicar la ubicación actual del
cursor.
• Si un campo del formulario no es editable deberá indicarse mediante un color
diferente.
• El formato de fecha siempre será dd/mm/aaaa.

 Formulario de Logueo

3
Magic quotes es un procedimiento que automáticamente limpia los datos de entrada de un script PHP.
4
www.xdebug.org
5
www.dd.cron.ru

22/23 EST_PROGRAMACION PHP_SIU-TOBA_V2.1.odt

 P A S
P l a n d e A c c i ó n
d e S i s t e m a s

El formulario para el logueo de usuarios a sitio y/o aplicaciones web desarrollados desde el PAS,
deberá considerar los aspectos indicados en el procedimiento PRO_GESTION DE
USUARIOS_V1.0.

4.5 Documentación Automática del Código

Se recomienda utilizar alguna herramienta de documentación automática, como por
ejemplo la herramienta PhpDocumentador 6.

4.6 En cuanto a la organización de archivos

Para mejorar organización del código se sugiere que todas las consultas sql que se
realicen, sean agrupadas en un único archivo .php.
Considerar también la creación de un directorio donde se aloje el/los archivos .php que
agruparan las consultas sql.
Por ejemplo para la siguiente operación se organizaron los archivos del siguiente modo:

/php/operaciones/SIU-Mapuche/Generación_de_datos/sql/consultasGeneracionDeDatos.php

6
www.phpdoc.org

EST_PROGRAMACION PHP_SIU-TOBA_V2.1.odt 23/23