You are currently browsing the tag archive for the ‘instalar PHP’ tag.
Qué es
Lo que javadoc es para Java, phpDocumentor es para PHP: Una herramienta para generar documentación a partir del código fuente. (Ver artículo sobre
Documentación automatizada.)
Por ser dos proyectos separados, phpDocumentor no es automáticamente compatible con una nueva versión de PHP. Por ejemplo, yo tuve problemas con phpDocumentor 1.4.3 cuando instalé PHP 5.3 y volví a la versión 1.4.2 que funcionaba aunque con muchas advertencias.
Una alternativa a phpDocumentor es Doxygen que puede también documentar código PHP. Una diferencia es que doxygen es un programa, mientras phpDocumentor es una colección de código en PHP. Es decir, genera la documentación con el mismo PHP que usas para ejecutar tu propio código PHP. Por eso necesitas tener también PHP en tu máquina para poder usar phpDocumentor. Sin embargo, no necesitas instalar un servidor web.
Como instalar
phpDocumentor no es un programa sino un código fuente y, por eso, no tiene instalador. Es un archivo que descomprimes en un directorio. Para usar phpDocumentor debes abrir el fichero phpdoc.bat (en Windows) y especificar la ruta a php.exe en la variable phpCli. Por ejemplo
SET phpCli=C:\Program Files\PHP\php.exe
Como usar
Para un proyecto en concreto conviene crearse un script en que especificas todas las opciones de phpdoc.
El siguiente script es un ejemplo. Lo he utilizado para generar la documentación del mismo phpDocumentor. Antes de usarlo hay que ajustar los directorios de entrada y salida y de la instalación de PHP.
echo Generate automatic documenation for phpDocumentor echo Version from 12.6.2009 rem Directory list must be without spaces between the coma set phpdoc_dir="C:\opt\PhpDocumentor" set source_dir="C:\opt\PhpDocumentor" set target_dir="C:\doc\phpDocumentor" set title="phpDocumentor Documentation" set projects=phpDocumentor rem set output="HTML:frames:default" rem set output="HTML:frames:earthli" rem set output="HTML:frames:l0l33t" set output="HTML:frames:phpdoc.de" rem set output="HTML:frames:phpedit" rem set output="HTML:frames:phphtmllib" rem set output="HTML:frames:DOM/default" rem set output="HTML:frames:DOM/earthli" rem set output="HTML:frames:DOM/l0l33t" rem set output="HTML:frames:DOM/phpdoc.de" rem set output="HTML:frames:DOM/phphtmllib" rem set output="HTML:frames:DOM/phphtmllib" rem set output="HTML:Smarty:default" rem set output="HTML:Smarty:HandS" rem set output="HTML:Smarty:PHP" rem set output="CHM:default" rem set output="PDF:default" cd %phpdoc_dir% call phpdoc -d %source_dir% -t %target_dir% -ue on -ti %title% -pp off -po %projects% -o %output% -s off rem pause exit rem These are comments, but they will not be executed because the scripts exists before rem use phpdoc -h to see this -f --filename name of file(s) to parse ',' file1,file2. Can contain complete path and * ? wildcards -d --directory name of a directory(s) to parse directory1,directory2 -ed --examplesdir full path of the directory to look for example files from @example tags -tb --templatebase base location of all templates for this parse. -t --target path where to save the generated files -i --ignore file(s) that will be ignored, multiple separated by ','. Wildcards * and ? are ok -is --ignoresymlinks ignore symlinks to other files or directories, default is off -it --ignore-tags tags to ignore for this parse. @package, @subpackage, @access and @ignore may not be ignored. -dh --hidden set equal to on (-dh on) to descend into hidden directories (directories starting with '.'), default is off -q --quiet do not display parsing/conversion messages. Useful for cron jobs on/off default off -ue --undocumentedelements Control whether or not warnings will be shown for undocumented elements. Useful for identifying classes and methods that haven't yet been documented on/off default off -ti --title title of generated documentation, default is 'Generated Documentation' -h --help show this help message -c --useconfig Use a Config file in the users/ subdirectory for all command-line options -pp --parseprivate parse @internal and elements marked private with @access. Use on/off, default off -po --packageoutput output documentation only for selected packages. Use a comma-delimited list -dn --defaultpackagename name to use for the default package. If not specified, uses 'default' -dc --defaultcategoryname name to use for the default category. If not specified, uses 'default' -o --output output information to use separated by ','. Format: output:converter:templatedir like "HTML:frames:phpedit" -cp --converterparams dynamic parameters for a converter, separate values with commas -ct --customtags custom tags, will be recognized and put in tags[] instead of unknowntags[] -s --sourcecode generate highlighted sourcecode for every parsed file (PHP 4.3.0+ only) on/off default off -j --javadocdesc JavaDoc-compliant description parsing. Use on/off, default off (more flexibility) -p --pear Parse a PEAR-style repository (package is directory, _members are @access private) on/off default off -ric --readmeinstallchangelogSpecify custom filenames to parse like README, INSTALL or CHANGELOG files You can have multiple directories and multiple files, as well as a combination of both options
En la carpeta HTML nuevamente generado debes abrir el fichero index.html para ver la página principal de la documentación. La más práctico es crearse un enlace fuera del directorio con un nombre significativo como «Documentación de bla bla».
Puedes usar letras con acentos y otras letras no ASCII si guardas el fichero fuente (con el código) con la codificación UTF-8 (con BOM). En general no es mala idea guardar tu código como UTF-8 en lugar del habitual ISO-8859 si quieres usar otros idiomas que el inglés en los comentarios, porque phpDocumentor (y también doxygen) codifican su salida HTML en UTF-8.
phpDocumentor tiene diferentes convertidores. Cada uno compila la documentación en un formato y tema diferente (HTML, PDF, CHM). La página web de phpDocumentor muestra ejemplos de los diferentes temas visuales que permite la documentación en HTML.
Crear la documentación de phpDocumentor y tutoriales
Como ya he mencionado más arriba, phpDocumentor puede crear su propia documentación. Los ficheros fuente de esta documentación están en una subcarpeta «tutorials». Sin embargo, debes especificar el directorio raíz de phpDocumentor como directorio de entrada a phpdoc, para que se compilen estos tutoriales. (phpDocumentor no procesa documentación en «tutorials» que no esté vinculado a algún código fuente. No puedes compilar sólo tutoriales.) Como proyecto debes especificar «phpDocumentor». (Ver ejemplo abajo.)
Esta subcarpeta «tutorials» es también un ejemplo de como escribir documentación que no está directamente vinculada a algún objeto dentro del código. Estos tutoriales están escrito en un formato reducido de DocBook. Los elementos DocBook que se compilan están listado en la sección [ppage] del fichero options.ini que viene con cada convertidor. Por ejemplo, mi tema favorito «HTML:frames:earthli» está configurado por el fichero Converters/HTML/frames/templates/earthli/options.ini. Cada convertidor/tema tiene su fichero de configuración options.ini en una carpeta diferente.
Conclusión
phpDocumentor es una herramienta potente para crear documentación a partir de código fuente PHP. El formato de comentarios de documentación es fácil de aprender por ser muy parecido al formato de javadoc. (Ver lista de características de phpDocumentor.)
Una desventaja es que cuesta hacer phpDocumentor funcionar. Es un problema que desaparece una vez familiarizado con la herramienta, pero que puede causar frustración al principio. También existe una interfaz gráfica para generar la documentación pero que requiere un servidor web propiamente configurado. No está mal pero no quita el problema de tener que leer mucha documentación antes del primer éxito. En comparación el wizard de doxygen es bastante más fácil de usar.
Además, doxygen entiende varios lenguajes de programación, aunque no es capaz de ofrecer diferentes temas. Aún así vale la pena reflexionar sobre qué herramienta usar.
Referencias
- phpDocumentor – la herramienta descrita en este artículo
- Doxygen – una alternativa a phpDocumentor
- javadoc – un sistema de documentación para Java.
- PHP – el lenguaje de programación que phpDocumentor documenta.
- DocBook – un formato para escribir textos sin especificar su aparencia y que phpDocumentor usa para la documentación libre (tutoriales).
El lenguaje PHP viene con un instalador que se integra bien con el servidor web Apache bajo un entorno Windows. Sin embargo, es posible que el servicio de Apache ya no arranca después de la instalación de PHP. Recibes errores como “PHP Warning: PHP Startup: Unable to load dynamic library” en el fichero error.log del servidor Apache o cuando ejecutas php -i
.
Esto es obviamente un error de PHP y podemos esperar que no todas las versiones presentan este problema. Yo lo observé con PHP 5.2. Este problema se debe a que algunos componentes (librerías DLL) tienen incompatibilidades.
Por esto motivo conviene sólo instalar los paquetes que realmente se usan. Esto se puede hacer de dos formas:
- Cambiar la instalación de PHP: Ir al panel de control, agregar o quitar programas, y cambiar/quitar la instalación de PHP. En el diálogo del instalador deshabilitar todos los componentes que no se usan.
- Editar el fichero php.ini. Buscar la cadena «extenstion=» y comenta todos los modulos que no necesitas. Procura editar el fichero php.ini en el directorio correcto. En la configuración del servidor Apache httpd.conf encuentras (normalmente al final del fichero) el atributo PHPIniDir que indica la ruta al directorio de PHP.
Después de cambiar la instalación de PHP debes rearrancar el servidor web para hacer efectivo los cambios.
No todos los módulos causan problemas, pero cuando menos quedan mejor. Sin embargo, también arriesgamos correr en el problema contrario. Si PHP muestra un error «Call to undefined function«, entonces no tenemos cargado el módulo necesario que contiene esta función.
Busca esta función en el manual de PHP y comprueba en qué módulo se encuentra. Cuando tienes la página de la función abierta pulsa el enlace «Up» (hacía arriba) para encontrar en la tabla de contenidos la sección de instalación. Puedes habilitar un módulo en las dos formas mencionadas arriba: por el instalador de Windows o descomentando la línea «extenstion=» correspondiente en el fichero php.ini.