phpDocumentor – organiza tu documentación PHP y expórtala a HTML

Existen algunas herramientas que permiten generar documentación de forma automática a partir del código fuente. Javadoc es la herramienta estándar en Java. Para PHP una de las herramientas más utilizadas es phpDocumentor.
La documentación de un proyecto de software es tan importante como su código. Una buena documentación nos facilita en gran medida el mantenimiento futuro de la aplicación. Si además estamos trabajando en equipo es muy útil saber lo que hacen las partes que desarrollan otras personas, sobretodo si tenemos que utilizarlas en nuestra parte.
Para ayudarnos existe la aplicación PhpDocumentor, que nos permite generar automáticamente una buena documentación de nuestro código, de una forma parecida a como lo hace JavaDoc. Mediante comentarios y unas etiquetas especiales podemos definir de forma sencilla que hace cada clase, cada método y cada función de nuestro código.

Los elementos que pueden ser documentados son:

• define
• function
• class
• class vars
• include/require/include_once/require_once
• global variables

/** * Descripción breve (una línea) * * Descripción extensa. Todas las líneas que * sean necesarias * Todas las líneas comienzan con * <- Esta línea es ignorada * * Este DocBlock documenta la función suma() */ function suma() { ... }

1 2 3 4 5 6 7 8 9 10 11 12 13 14

/** * Descripción breve (una línea) * * Descripción extensa. Todas las líneas que * sean necesarias * Todas las líneas comienzan con * <- Esta línea es ignorada * * Este DocBlock documenta la función suma() */ function suma() { ... }

Además se puede incluir documentación global a nivel de fichero y clase mediante la marca @package

Documentación para classes y archivos

Marca	Significado
@access	Si @access es ‘private’ no se genera documentación para el elemento (a menos que se indique explícitamente). Muy interesante si sólo se desea generar documentación sobre la interfaz (métodos públicos) pero no sobre la implementación (métodos privados).
@author	Autor del código
@copyright	Información sobre derechos
@deprecated	Para indicar que el elemento no debería utilizarse, ya que en futuras versiones podría no estar disponible.
@example	Permite especificar la ruta hasta un fichero con código PHP. phpDocumentor se encarga de mostrar el código resaltado (syntax-highlighted).
@ignore	Evita que phpDocumentor documente un determinado elemento.
@internal inline {@internal}}	Para incluir información que no debería aparecer en la documentación pública, pero sí puede estar disponible como documentación interna para desarrolladores.
@link inline {@link}	Para incluir un enlace (http://…) a un determinado recurso.
@see	Se utiliza para crear enlaces internos (enlaces a la documentación de un elemento).
@since	Permite indicar que el elemento está disponible desde una determinada versión del paquete o distribución.
@version	Versión actual del elemento

Dejo aquí un ejemplo

1

2 3 4 5 6 7 8 9 10 11 12 13 14 15

/** * Debug *  Gestión de los errores de php, logs de informacion etc... * * @package debug * @author Garretus * @copyright Garretus * @version 2.1 * @access public */ class Debug{ . . . }//END CLASS

Documentación para funciones y métodos

Marca	Significado
@global	Permite especificar el uso de variables globales dentro de la función.
@param	Parámetros que recibe la función. Formato: * @param tipo $nombre_var comentario
@return	Valor devuelto por la función. Formato: * @return tipo comentario

Ejemplo :

1

2 3 4 5 6 7 8 9 10 11 12 13 14

/**      * test to see if valid cache exists for this template      *      * @param string $tpl_file name of template file      * @param string $cache_id      * @param string $compile_id      * @return string|false results of {@link _read_cache_file()}      */     function is_cached($tpl_file, $cache_id = null, $compile_id = null)     {      .      .      .      }//END FUNCTION

Para terminar este post decir que mi IDE favorito PHPDesigner está perfectamente integrado con PHPDocumentor tanto para documentar como para compilar la documentación. Esta es una de las razones por las que es mi IDE favorito.

Generar archivos PDF dinámicamente con PHP

Los documentos PDF han demostrado ser un medio muy importante dentro de la ofimática actual. Crear, administrar y exportar archivos PDF suele ser un requerimiento esencial dentro de cualquier proyecto web. Necesitamos una herramienta para

1. Insertar imágenes y gráficas.
2. Establecer la fuente del PDF.
3. Tener dinámicamente control sobre el diseño del mismo.
4. Realizar una maquetación decente para esta clase de documentos es esencial.

De nuestra habilidad para crear estos documentos dependerá la calidad del archivo finalmente exportado. Es por esto que desde este blog os quiero presentar mi herramienta preferida la clase FPDF de PHP.
FPDF es una clase escrita en PHP que permite generar documentos PDF directamente desde PHP, es decir, sin usar la biblioteca PDFlib. La F de FPDF significa Free (gratis y libre): puede usted usarla para cualquier propósito y modificarla a su gusto para satisfacer sus necesidades.
La clase genera documentos en muchos otros idiomas aparte de los europeos occidentales: europeo central, ciríloco, griego, báltico y tailandés, si se dispone de fuentes TrueType o Type1 con el conjunto de caracteres adecuado. El chino y el japonés también están admitidos. UTF-8 también está disponible.
Como es lógico, la velocidad de generación de un documento es menor que con PDFlib. Sin embargo, la desventaja en cuanto a rendimiento es muy razonable y se adecúa a la mayoría de los casos, a no ser que sus documentos vayan a ser especialmente complejos o extensos.
He aquí un ejemplo de uso de la clase simple. El desarrollador tiene en su página muchos más ejemplos más aparte de documentación: http://www.fpdf.org/
1

2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38

require('fpdf.php'); class PDF extends FPDF { //Cabecera de página function Header() {     //Logo     $this->Image('logo_pb.png',10,8,33);     //Arial bold 15     $this->SetFont('Arial','B',15);     //Movernos a la derecha     $this->Cell(80);     //Título     $this->Cell(30,10,'Title',1,0,'C');     //Salto de línea     $this->Ln(20); } //Pie de página function Footer() {     //Posición: a 1,5 cm del final     $this->SetY(-15);     //Arial italic 8     $this->SetFont('Arial','I',8);     //Número de página     $this->Cell(0,10,'Page '.$this->PageNo().'/{nb}',0,0,'C'); } } //Creación del objeto de la clase heredada $pdf=new PDF(); $pdf->AliasNbPages(); $pdf->AddPage(); $pdf->SetFont('Times','',12); for($i=1;$i<=40;$i++)     $pdf->Cell(0,10,'Imprimiendo línea número '.$i,0,1); $pdf->Output();

PHPMailer I – gestiona todos los correos de tu site con esta librería

Es posible enviar email con la funcion mail() de php, pero dicha función no permite algunas de las más populares características que proporcionan los clientes de correo usados actualmente. PHPMailer hace fácil la difícil tarea de enviar correos con características especiales y puedes incluso utilizar tu propio servidor smtp aunque éste requiera autenticación (un nombre de usuario y contraseña), con lo que se podrá usar una cuenta gratuita de correo que permita este tipo de conexión.
Características principales:

• Capacidad de uso de uno o varios servidores SMTP externos
• Uso de html en el envío
• Adjuntar imágenes y/o archivos en el mail
• Embeber imágenes dentro del correo electrónico
• Buena descripción de errores

Descargas:
http://sourceforge.net/projects/phpmailer/files/phpmailer%20for%20php4/0.90/
Ejemplos de uso:
http://phpmailer.worxware.com/index.php?pg=examples
Página de los desarrolladores:
http://phpmailer.worxware.com/

Patrones de Diseño II – Singleton en PHP

Una breve entrada para describir el patrón de diseño denominado Singleton y para contaros cómo podríamos implementarlo en PHP.
Intención del patrón

Garantiza que una clase sólo tenga una instancia y proporciona un punto de acceso global a ella.
Problema a resolver

Varios clientes distintos precisan referenciar a un mismo elemento y queremos asegurarnos de que no hay más de una instancia de ese elemento.
Solución -> Singleton

Garantizaremos una única instancia.

1

2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34

class MiSingleton{     // Contenedor de la instancia del singleton     private static $instance;     // Un constructor privado evita la creación de un nuevo objeto     private function __construct()     {         echo 'Construido!';     }     // método singleton     public static function singleton()     {         if (!isset(self::$instance)) {             $c = __CLASS__;             self::$instance = new $c;         }         return self::$instance;     }     // método de ejemplo     public function ladrar()     {         echo 'Woof!';     }     // Evita que el objeto se pueda clonar     public function __clone()     {         trigger_error('Clone is not allowed.', E_USER_ERROR);     } }

¿Cómo obtengo una instancia de la clase y cómo uso sus métodos?

$objMiSingleton = MiSingleton::singleton(); $objMiSingleton->ladrar();

1 2	$objMiSingleton = MiSingleton::singleton(); $objMiSingleton->ladrar();

.

Patrones de Diseño I : introducción

1.- ¿Qué son los patrones de diseño?

Voy a hacer un copy-paste de la wikipedia porque creo que yo mismo no encontraré mejores palabras para definirlo :
“Los patrones de diseño son la base para la búsqueda de soluciones a problemas comunes en el desarrollo de software y otros ámbitos referentes al diseño de interacción o interfaces.
Un patrón de diseño es una solución a un problema de diseño. Para que una solución sea considerada un patrón debe poseer ciertas características. Una de ellas es que debe haber comprobado su efectividad resolviendo problemas similares en ocasiones anteriores. Otra es que debe ser reusable, lo que significa que es aplicable a diferentes problemas de diseño en distintas circunstancias.”
2.- ¿Para que sirven los patrones de diseño?
Seguro que casi todos vosotros habéis usado el MVC (Modelo Vista Controlador) en más de una ocasión usando algún Framework o librería. ¿Os habéis dado cuenta de los fácil que es programar con este método una web? ¿Habéis observado lo límpio que queda el código y lo rápido que se programa? Pues bien el MVC no es más que un patrón de diseño que se adapta perfectamente a la programación web.
En general los objetivos de cualquier patrón de diseño los podemos resumir en los siguientes puntos:

1. Aportar elementos reutilizables en el diseño de sistemas software.
2. Evitar la repetición de búsqueda de soluciones a problemas ya conocidos y ya solucionados anteriormente.
3. Definir un vocabulario común entre Analistas-Programadores.
4. Estandarizar el modo en que se realiza el Análisis estructural de la aplicación.
5. Facilitar el aprendizaje de las nuevas generaciones de programadores condensando conocimiento ya existente.

3.-  ¿Que importancia tienen?
Saber de patrones de diseño te ayuda a tener un lenguaje común con otros programadores. Cuando te toque modificar un programa, el autor del código seguramente tendrá que explicarte qué fue lo que hizo, cómo funciona su código y por qué hizo cualquier cambio. Se puede demorar horas. Pero esa conversación puede acortarse si te dice, aquí estoy utilizando tal o cual patrón (por ejemplo: el patrón Factory). Serás tú el que ya conozcas los conceptos detrás de esa palabra y sabrás cómo fue diseñado el programa.