El otro día, por necesidad de probar cosas nuevas y también para ver como sería su funcionamiento en un proyecto que estoy desarrollando, me decidí a probar phpDocumentor.
La verdad que no sé por qué, pero instalarlo a través de composer me fue imposible. Así que decidí instalar el archivo “.phar” directamente y por eso ahora, creo conveniente compartirlo por si alguien lo pueda necesitar.
¿Qué es phpDocumentor?
Sencillamente es un programa que permite generar documentación para nuestro código PHP.
Nosotros debemos de documentar nuestro código siguiendo el estándar PHPDoc qué es el estándar oficial para documentar código en PHP y luego, phpDocumentor se encargará de generar toda la documentación en distintos formatos: HTML, PDF, etc.
¿Cómo se instala?
Aquí me voy a centrar solo en como instalar el archivo “.phar” de phpDocumentor bajo Windows.
Para otro tipo de instalación puedes seguir o elegir el modo que te convenga a través de su web o de github.
Para descargar el archivo «phpDocumento.phar» basta con ir a una de las siguientes direcciones: https://phpdoc.org/phpDocumentor.phar
https://github.com/phpDocumentor/phpDocumentor/releases
Uso de phpDocumentor.
Por ahora, me voy a limitar a explicar el uso básico, es decir, como generar documentación para un proyecto. Quizá, mas adelante, cree una segunda parte de este articulo explicando todos los parámetros de configuración y como darle un uso más profesional, pero por ahora empecemos por lo básico.
Una vez has descargado el archivo «phpDocumentor.phar», muévelo a la carpeta raíz de tu proyecto.
En mi caso, dado que uso laragon, la ruta es:
“C:\laragon\www\proyecto1”.
Si usas xampp por ejemplo, la ruta sería:
“C:\xampp\htdocs\tu-proyecto”.
Ahora necesitamos abrir la consola de Windows (cmd) y movernos hasta la carpeta del proyecto.
Por ejemplo, y siguiendo como lo he hecho yo, en la consola escribo:
cd C:\laragon\www\proyecto1
Ahora vamos a generar la documentación.
Para ello en la consola escribimos el siguiente comando:
php phpDocumentor.phar -d src -t docs
Dónde, “-d” significa el directorio fuente, es decir, donde esta nuestro código PHP y “-t”, quiere decir el directorio destino (donde guardaremos la documentación generada).
Así pues, siguiendo con el ejemplo, podríamos hacer:
php phpDocumentor.phar -d C:\laragon\www\proyecto1 -t C:\laragon\www\proyecto1\documentacion
Creo que queda bastante claro ¿no? Genero documentación para el proyecto “C:\laragon\www\proyecto1” y la guardo en “C:\laragon\www\proyecto1\documentacion”.
Ya esta, eso es todo. Si vamos al directorio podemos ver como la documentación ha sido generada.
Por último, decir que también podemos crear un archivo “phpdoc.xml” en la raíz del proyecto para una configuración más avanzada y completa pero, como he dicho antes, sería conveniente hacerlo en otro articulo aparte. De momento, eso es todo por ahora.
Sobre el autor
