NetBeans

En este tema vamos a trabajar con el IDE NetBeans, en este caso orientándonos a PHP.

NetBeans es un IDE open source, que se puede usar para tecnologías muy diferentes, lo que incluye Java, C/C++, PHP, HTML5 y Groovy. También es multiplataforma, y está disponible para Windows, Linux y OS X.

En https://netbeans.org/downloads/ podemos descargar NetBeans exclusivamente para PHP y HTML5 (y tecnologías asociadas), o bien el paquete completo, para soportar Java, C/C++ y Groovy.

En nuestro caso, nos centraremos en PHP y HTML5.

Algunas versiones de NetBeans incorporan los servidores Apache Tomcat y Glassfish. Estos servidores solo son necesarios en el caso de estar desarrollando con Java. Apache Tomcat es un contenedor de servlets (implementa servlets, Java Beans y JSP). Glassfish es un servidor JEE completo, con soporte para EJB (Enterprise Java Beans) y JMS (Java Message Service), tecnologías que permiten al programador abstraerse de los problemas generales de una aplicación empresarial, como concurrencia, transacciones, persistencia, seguridad, etcétera, y centrarse en la lógica de negocio.

Para nuestros objetivos, trabajar con PHP en NetBeans, podemos descargar la versión HTML5 & PHP.

Instalación de NetBeans

La instalación de NetBeans no merece demasiada consideración, afortunadamente. Descargar, instalar y abrir, es todo lo que hay que hacer. A continuación, se muestran algunas capturas del proceso.

Nótese que si no tenemos instalado JDK, obtendremos un error al intentar instalar NetBeans.

Error al instentar instalar si no tenemos instalado Java SE Developmente Kit (JDK).

Una vez que hemos instalado NetBeans, al abrirlo, veremos lo siguiente.

Crear un proyecto

Vamos a crear un proyecto PHP con NetBeans. Para ello, seguimos los siguietes pasos:

  1. Nos vamos al menú File\New Project
  2. Seleccionamos la categoría PHP. Si partimos de un proyecto existente, elegimos la opción "PHP Application with Existing Sources". En caso constrario elegimos "PHP Application". Después hacemos clic en "Next"
  3. En la siguiente ventana, tenemos las siguientes cuestiones:
    • Se nos sugiere un nombre de proyecto y la ruta al "Document Root" de Xampp. Debemos cambiar el nombre del proyecto.
    • La versión de PHP a utilizar, en principio la última disponible.

    • La codificación de la página, por defecto UTF-8.
    • Los metadatos son usados únicamente localmente por NetBeans. Podemos guardar dichos archivos en un directorio separado marcando "Copy files from Sources to another location".
  4. En el paso 3 (Run configuration), definimos la ubicación del servidor web. En nuestro caso, este servidor es local (el servidor XAMPP instalado anteriormente). También es posible definir un servidor FTP remoto. Hacemos clic en "Finish"

Los siguientes pasos no nos serán de utilidad de momento ya que nos ayudan a elegir uno de los frameworks disponibles (que veremos más adelante), y para gestionar las dependencias de nuestro proyecto proyecto con Composer.

Ya podemos empezar a escribir en nuestro proyecto, añadiendo lo siguiente, por ejemplo:

<?php echo "Hola mundo"; ?>

Si escribimos en el navegador la url http://localhost/proyecto1, podemos ver nuestra primera página.

Para añadir más archivos y clases en nuestro proyecto, podemos hacer clic derecho sobre el nombre del proyecto, y desplegar el submenú "New".

Al hacer clic derecho sobre el nombre del proyecto, obtenemos el menú del proyecto

Características de NetBeans

NetBeans incluye un amplio conjunto de características que permiten optimizar el desarrollo diario con PHP. Incluye el editor, depurador, software de control de versiones, y otras características para el trabajo en equipo.

Búsqueda rápida

Permite buscar en archivos, tipos, símbolos, menú de acciones, opciones, ayuda y en proyectos abiertos.

Para acceder directamente a la entrada de búsqueda, hay que pulsar Ctrl+i

En la lista de resultados de búsqueda, podemos elegir la categoría de búsqueda.

Administrador de Plugins

Desde el administrador de plugins (Tools \ Plugins), se pueden añadir, eliminar o actualizar características.

Actividad 1. A veces un cierto plugin no está disponible directamente en NetBeans. Entre los plugins más descargados de NetBeans, está el plugin del tema "Sublime Theme". Puedes verlo en http://plugins.netbeans.org/PluginPortal/. Descarga dicho plugin e instálalo (busca la forma de hacerlo).

Toma una captura llamada Act1-netbeans.png donde se pueda ver el tema Sublime instalado. En el editor de textos, deberá aparecer tu nombre dentro de un comentario.

Administrador de proyectos

Desde el administrador de proyectos podemos hacer tareas sobre los proyectos, como ejecutar, depurar, probar, generar documentación, ajustar la configuración, establecer propiedades, etc.

Para fijar el administrador de proyectos, debemos elegir la opción Window \ Projects o bien pulsando Ctrl+1.

Desde el menú constextual de un proyecto se pueden ejecutar muchas acciones diferentes.

Administrador de archivos

Desde el administrador de archivos se puede navegar por los archivos de los proyectos, y llevar a cabo acciones genéricas como copiar, pegar, borrar, renombrar, etc.

Para mostrar el administrador de archivos (si no está ya accesible) elegimos la opción Window \ Files o bien Ctrl+2

Con el administrador de archivos, podemos ver archivos del proyecto que no veremos desde el administrador de proyectos. Además, podemos llevar acciones generales sobre ellos.

Administrador de servicios

Eclipse cuenta con servicios web SaaS (Software as a Service). Arrastrando el componente al editor, insertamos el código correspondiente.

Arrastrando el componente geocode de Google, obtenemos el siguiente código.

Menú de navegación

Desde este menú podemos ir a un archivo, símbolo, línea, etc. Se suele utilizar para saltar a un cierto punto del proyecto.

Podemos buscar archivos, tipos (clases), símbolos, tests y números de línea.
Si elegimos Navigate\Declaration saltaremos al punto en que se definió el elemento sobre el que estamos.

El editor de NetBeans

El editor de NetBeans posee entre otras las siguientes características:

  • Resaltado de sintaxis
  • El resaltado facilita la lectura del código.
  • Salto a la declaración: permite saltar a la línea donde se ha declarado una variable o un método.
  • Para usar esta opción nos tenemos que poner sobre la variable o método deseados y presionar CTRL+B, o bien hacer clic derecho sobre la variable/método, y elegir en el menú contextual la opción Navigate | Go to Declaraction.

    Salto desde un método hasta el lugar de su declaración.
  • Navegador de código: muestra la estructura del código contenido en el archivo.
  • A la izquierda se pueden ver los métodos definidos en el código de una clase.
  • Mostrar/Ocultar fragmentos del código: permite ocultar/mostrar ciertas partes del código, como clases, métodos, bloques de comentarios, etiquetas HTML, clases CSS, etc. En la parte izquierda del editor hay nodos que permiten mostrar y ocultar los elementos.
  • Los detalles no deseados se pueden ocultar temporalmente.
  • Sangrías automáticas: el editor introduce sangrías automáticamente cuando detecta un anidamiento.
  • Las sangrías ayudan en la lectura del código fuente.
  • Formato: para que el código sea más legible, el editor proporciona un asistente de formato que modifica el código del modo más adecuado.
  • Para dar formato a un fragmento de código, lo seleccionamos y hacemos clic derecho sobre él, y elegimos la opción Format, o bien pulsamos Alt+Shift+F.

    Si queremos dar formato a todo el archivo, debemos elegir la opción Source | Format, o bien pulsamos Ctrl+A y Alt+Shift+F

    Un buen estilo en el código es necesario para garantizar su calidad.
  • Completado automático de corchetes: ciertos caracteres van en parejas, como "", (), {} ó [].
  • El cierre automático de corchetes evita pérdidas de tiempo por errores difíciles de encontrar.
  • Asistente de parámetros: el editor ofrece ayuda para elegir funciones, métodos, parámetros, etc.
  • Sugerencia de función, según las coincidencias disponibles.
    Información sobre los parámetros de la función.
  • Definición de tipo de variable por comentario: podemos definir el tipo de una variable mediante un comentario del tipo /* @var $variable tipo */ . De este modo, el editor nos hará sugerencias atendiendo a la naturaleza del tipo.
  • Para evitar tener que escribir /* @var $variable tipo */ , podemos escribir vdoc y pulsar tabulador, para que se genere automáticamente. Este mecanismo, además, se adapta al contexto en que estemos usándolo. Por ejemplo, si lo escribimos delante de una variable, utilizará dicho nombre.

    NetBeans identifica el tipo de la variable y hace una sugerencia de método posible.
  • Mensajes de error: el editor nos mostrará errores de sintaxis con subrayado rojo, y una viñeta con una admiración en el margen izquierdo. Si hacemos clic sobre la admiración, obtendremos una descripción del error.
  • Setencia if incompleta.

Actividad 2. Crea un nuevo proyecto PHP que realice conversiones de unidades de medida. El proyecto contará con los siguientes archivos:

  • conversor/index.php
    • contiene texto descriptivo y un formulario.
  • conversor/controlador/conversion.php
    • Valida los valores de entrada.
    • Si los datos son válidos:
      • carga un objeto Conversor y realiza la operación
      • carga un objeto VistaConversion y le pasa el resultado de la conversión
    • Si los datos no son válidos:
      • carga un objeto VistaNoValida y le pasa un mensaje de error
  • conversor/modelo/Conversor.php (Es una clase).
    • Realiza conversiones de centímetros a pulgadas y de pulgadas a centímetros.
    • Tiene un metodo llamado "convCmToInch($medidaEntrada)" que devuelve la conversión de cm a pulgadas.
    • Tiene un método llamado "convInchToCm($medidaEntrada)" que devuelve la conversión de pulgadas a cm.
  • conversor/vista/VistaConversion.php
    • Contiene código html legible con el resultado de una conversión.
    • Utiliza las variables obtenidas durante el flujo de ejecución con el valor de entrada, el tipo de conversión y el de salida
  • conversor/vista/VistaNoValida.php
    • Contiene código html que muestra un error.

Después de crear el proyecto, toma las siguientes capturas: Una captura introduciendo información en el formulario. Otra captura con el resultado de la conversión. Una última captura que muestra en el explorador de proyectos los métodos de la clase "Conversor". Guárdalas todas con el nombre Act2-netbeans.zip

Refactorizaciones

NetBeans permite realizar ciertas refactorizaciones sobre el código PHP, del mismo modo en que lo hace Eclipse.

Renombrado

Podemos renombrar un elemento en todas sus localizaciones. Para renombrar, colocamos el cursor sobre el nombre que queremos renombrar, y pulsamos Ctrl+R.

También se puede aplicar esta refactorización, haciendo clic derecho sobre el nombre, y eligiendo la opción Refactor\Rename. Hasta que no aceptemos la refactorización pulsando Do Refactoring, no se realizará.

Todas las instancias del nombre seleccionado son destacadas al pulsar Ctrl+R.
Refactorización utilizando la opción Refactor\Rename.

Autocompletado de código

Para utilizar el autocompletado, podemos elegir la opción Tools \ Options \ Editor \ Code Completion.

Configuración de las opciones de autocompletado de PHP.

Es importante elegir como lenguaje PHP para tener opciones específicas. Las características de autocompletado son las siguientes:

Sugerencias contextuales

El editor proporciona sugerencias para ciertos elementos:

  • Palabras clave como if, else, elseif, while, switch, function, etc.
  • Funciones predefinidas de PHP
  • Variables predefinidas o definidas por el usuario.

Para que se muestren las sugerencias, debemos empezar a escribir el nombre y pulsar Ctrl+Espacio, tal y como se muestra en la siguiente imagen. Si lo que deseamos

Sugerencia al empezar a escribir una palabra clave o un función y pulsar Ctrl+Espacio

Para generar una lista de palabras clave de PHP, pulsamos directamente Ctrl+Espacio. Si lo que queremos es una lista de las variables disponibles, escribimos $ y Ctrl+Espacio

Plantillas y abreviaturas

Crear una aplicación nueva no tiene porqué significar empezar desde cero. Podemos empezar desde una aplicación de ejemplo. Para hacer esto, durante la creación de un nuevo proyecto, elegimos la opción Samples\PHP en la sección Choose Categories

Podemos usar plantillas predefinidas como las que aparecen en la opción Tools\Templates. Con esta opción, abrimos un nuevo archivo sin nombre con la estructura deseada. Además, podemos añadir nosotros nuestras propias plantillas a partir de un archivo existente.

Podemos añadir

Además podemos insertar fragmentos de código. Para ello, debemos ir Tools\Options\Editor\Code Templates. Desde aquí, podemos conocer los fragmentos disponibles así como añadir nuevos fragmentos.

Una de la cosas que podemos decidir es qué combinación de teclas expandirá el código en el menú desplegable Expand template on

Al escribir cls y pulsar Tabulador se expandirá el código de una clase.
Inicialmente escribimos la abreviatura relacionada con la plantilla.

Podemos expandir código a partir de abreviaturas y plantillas predefinidas. Por ejemplo, la abreviatura cls genera una plantilla de clase. Para usar esta funcionalidad, escribimos la abreviatura, y después pulsamos el tabulador.

Al pulsar el tabulador se despliega el código de la plantilla.

En la plantilla de clase de la imagen anterior, aparece el símbolo ${ClassName}. Se trata de un parámetro. Estos parámetros están diseñados para cambiarse cuando el código es expandido. Si aparece más de una vez en el fragmento de código, se renombrará en todas sus apariciones.

En algunos casos, estos parámetros pueden tomar valores en función del contexto, como por ejemplo fore, que toma el valor de array que haya sido definido anteriormente. Prueba el siguiente ejemplo:

$arr = array(); fore+Tab

Para ver las plantillas definidas, o modificarlas, debemos elegir la opción Tools \ Options \ Editor \ Code Templates. Desde aquí, podemos añadir/eliminar/editar plantillas.

Editando las plantillas disponibles.

Completado de código en constructures

Tras escribir la palabra new se sugiere la lista de constructores disponibles y parámetros para las clases disponibles en el proyecto.

Sugerencia de constructores disponibles en el proyecto.

Completado de códgio SQL

NetBeans también asiste en la escritura de código SQL a la hora de realizar consultas, escribiendo una palabra clave de una consulta, como select y pulsando Ctrl+Espacio.

Ayuda para la escritura de sentencias SQL.

Generación de código

El editor proporciona generación de código sensible al contexto, es decir, que NetBeans sugiere un código específico dependiendo de la ubicación del cursor. Por ejemplo, dentro de una clase sugerirá la inserción de setters, getters y cosas así.

Para introducir código, pulsamos simultáneamente Alt+Insert, y NetBeans nos ofrecerá diferentes posibilidades acordes al contexto.

NetBeans sugiere uno u otro código en función del contexto.

En la generación de constructores, NetBeans da la opción de elegir los atributos de clase a incluir como parámetros.

NetBeans ofrece la posibilidad de incluir los atributos de la clase en el constructor.
Se ofrecerá como campos del constructor las variables definidas en la clase.

En la generación de Getters y Setters, es posible escoger los atributos deseados para los que se crearán.

Se puede elegir para qué atributos crear getters o setters.
Al igual que en el constructor, al generar código de setter o getter, se ofrecen las variables de la clase.

NOTA: La opción "Fluent Setter" hace que el método devuelva el objeto "$this", de forma que se puedan encadenar llamadas del tipo $variable = $objteo->setAtributo1("valor")->setAtributo2("valor)->hacerAlgo();

Cuando existan múltiples métodos que puedan ser sobreescritos en una clase, NetBeans da la posibilidad de seleccionar cuál de ellos implementar.

Cuando existen múltiples métodos en un clase, ya sean propios o heredados, es posible sobreescribirlos/implementarlos

Documentación del código

La documentación en PHP se puede hacer mediante PHPDoc, que es una adaptación de Javadoc.

Dado que se trata de un estándar para comentar código PHP, soporta generadores externos, como ApiGen, y permite a los IDEs como NetBeans a interpretar los tipos de variable para mejorar el autocompletado de código.

La documentación se realiza en bloques llamados "DocBlock", que preceden al elemento a ser documentado.

Un ejemplo de DocBlock

/** * Esto es un comentario DocBlock */

Un DocBlock contiene tres segmentos básicos, en el siguiente orden:

  • Descripción corta
  • Descripción larga
  • Anotaciones

Por ejemplo:

/** * Descripción corta * * La descripción larga da una descripción más * detallada del elemento a comentar. Puede tenera más * de una línea. * * Una línea en blanco hace referencia al * fin de un párrafo y el inicio de otro. */

La descripción corta termina en una línea en blanco. No puede tener más de dos líneas, ya que la tercera línea será ignorada.

La descripción larga puede tener la longitud que se desee.

Tanto la descripción larga como la corta pueden contener marcado html por cuestiones de formato. Las etiquetas html soportadas son: br, code, b, i, li, ol, ul, p y pre.

Además de estas, también se soportan:

  • <kbd> - muestra el texto con tipografía de terminal
  • <samp> - se usa para indicar un ejemplo.
  • <var> - se usa para marcar el nombre de una variable

En el extraño caso de que tengamos que escribir en la documentación un texto que coincide con el nombre de una etiqueta, podemos usar algo como lo siguiente: <<b>> para que se generle la cadena "<b>"

Anotaciones PHPDoc

Son etiquetas precedidas de @:

// Anotaciones de tipo de datos @param tipo $nombre_variable descripcion @return tipo descripcion @var tipo // Anotaciones legales @author nombre_del_autor email@email.com @copyright nombre fecha @licencia url nombre // Anotaciones de versión @version identificador_de_version @since identificador_de_version_estable @deprecated descripcion_de_elemento_obsoleto @todo cosas_por_hacer // Otras etiquetas @example descripcion_de_ubicacion_de_un_ejemplo @link referencia_url_documento @see nombre_elemento1, nombre_elemento2, ... @uses nombre_element @package nombre_del_paquete @subpackage nombre_del_subpaquete

Documentando el código

Documentar un método o función

Supongamos que contamos con el siguiente método:

function testFunc(DateTime $param1, $param2, string $param3 = NULL) { $number = 7; return $number; }

NetBeans ayuda a documentar los métodos del siguiente modo. Si escribimos /** en la línea previa a la función y presionamos Enter, obtenemos lo siguiente:

/** * * @param DateTime $param1 * @param type $param2 * @param string $param3 * @return int */ function testFunc(DateTime $param1, $param2, string $param3 = NULL) { $number = 7; return $number; }

Obsérvese que si un parámetro no declara su tipo, NetBeans indica como tipo type, como es el caso de ·$param2

Además, nosotros podemos añadir una descripción que acompañe al DocBlock generado

/** * * Aquí va una descripción corta * * @param DateTime $param1 * @param type $param2 * @param string $param3 * @return int */ function testFunc(DateTime $param1, $param2, string $param3 = NULL) { $number = 7; return $number; }

El asistente de código y PHPDoc

Cuando trato de llamar a una función que está comentada con PHPDoc desde cualquier otro punto del proyecto, el asistente de código de NetBeans me sugiere nuestra función y nos muestra los comentarios escritos:

NetBeans sugiere un método de una clase llamada "Persona", y además muestra el comentario asociado a dicho método.

Documentar una clase

Al crear una nueva clase, se añaden automáticamente algunos comentarios y anotaciones. A estos comentarios se pueden añadir otras anotaciones. NetBeans nos sugiere las anotaciones posibles teniendo en cuenta el contexto de clase. Basta con escribir @, y NetBeans nos muestra las anotaciones disponibles, y su descripción.

Finalmente una clase podría tener un aspecto similar al siguiente

/** * Descripción de la clase * * Descripción larga de la clase con varias líneas * * Nota: Cualquier comentario o comentarios finales * @package AprendiendoPHPDoc * @author José Peinado Peñalver * @version 1.0 * @copyright no acostumbro * @link http://www.josepeinadopenalver.com */

Al crear un nuevo objeto, NetBeans nos mostrará el comentario asociado a la clase, al igual que pasa con una función o método:

Al crear un nuevo objeto, los comentarios de la clase se muestran junto a la sugerencia de clase.

Documentar una propiedad de clase

Al igual que con la clase, para comentar una variable, basta con escribir en la línea previa /** y pulsar Intro. Por ejemplo, con una variable llamada $nombre obtendremos lo siguiente:

/** * * @var type */ private $nombre = "";

Este comentario podría quedar tras ser modificado del siguiente modo:

/** * * La variable <var>nombre</var> contiene el nombre de la persona. * * @var string */ private $nombre = "";

Tareas pendientes

Las anotaciones @todo permiten documentar tareas futuras. Por ejemplo:

/** * @todo Preparar pruebas unitarias para la clase Persona */

Además, es posible añadir anotaciones @todo del siguiente modo:

//TODO Preparar pruebas unitearias para la clase Persona.

Este tipo de anotaciones, podremos verlas en la ventana "Tasks" o "Action Items". Presionando Ctrl+6

Las tareas pendientes se muestran en la ventana "Action Items".

ApiGen

ApiGen nos permitirá generar la documentación

En la siguiente sección me voy a referir a la instalación de ApiGen en Windows. Existen procedimientos equivalentes para GNU/Linux que se explican en http://www.apigen.org/.

Es preciso descargar ApiGen desde http://apigen.org. A continuación podemos seguir las indicaciones dadas en https://github.com/fprochazka/apigen/blob/master/doc/installation.md con algunas modificaciones:

  1. Modificar la variable de entorno de Windows PATH para que incluya la ruta hasta el intérprete de PHP (en mi caso C:\xampp\php\)
  2. Crear el directorio C:\bin
  3. Ubicar en dicho directorio el archivo descargado apigen.phar
  4. Ejecutar las siguientes líneas desde la linea de comandos:
  5. cd C:\bin php -r "readfile('https://apigen.org/installer');" | php
  6. Al hacer esto, tendremos en C:\bin un archivo llamado apigen.bat

Para comprobar que todo ha ido bien, podemos probar a ejecutar lo siguiente:

C:\bin\apigen.bat --version

Deberíamos obtener el siguiente resultado:

ApiGen version 4.1.0

Para configurar NetBenas para utilice ApiGen hacemos lo siguiente:

  • Nos vamos a Tools\Options y elegimos la pestaña PHP.
  • Allí elegimos la pestaña Frameworks & tools.
  • En el menú de opciones a la izquierda, elegimos la opción "ApiGen".
  • Indicamos la ruta a Apigen. En Windows se trata del archivo "apigen.bat" que creamos anteriormente. En GNU/Linux se trata del archivo /usr/local/bin/apigen
  • Finalmente presionamos en Ok

Usar ApiGen en NetBeans

Es preciso indicar a NetBeans un directorio donde se generará la documentación. Para ello, debemos hacer los siguiente:

  • Hacemos clic con el botón derecho sobre el nodo del proyecto que vamos a documentar y elegimos la opción Properties
  • En esta sección debemos definir "Target Directory", indicando el directorio donde queremos que se genere la documentación.
  • Debemos también desmarcar la casilla "PHP" para excluir los elementos PHP por defecto de la documentación.
  • Debemos por último crear dentro del proyecto una carpeta tal como la que se ha definido en el apartado "Target Directory".
  • Definiendo la ruta donde se generará la documentación.
  • Finalmente hacemos clic en Ok.

Una vez hecho esto debemos generar la documentación. Para ello, hacemos clic con el botón derecho sobre el nodo del proyecto y elegimos la opción "Generate Documentation"

La documentación ha sido generada.

Esto no ha funcionado...

Si te ha funcionado el capítulo anterior, significa que por fin han corregido el problema. ¿Qué problema? Pues que al generar la documentación con ApiGen 4+, el mensaje devuelto es:

[InvalidArgumentException] There are no commands defined in the "C" namespace.

El problema está en que NetBeans lanza un comando para ApiGen que no se corresponde con la última versión de ApiGen. Hay un parámetros (generate) que es necesario. A continuación voy a dar una solución:

Solución en Windows. El script de apigen

Vamos a copiar los archivos apigen.phar y apigen.bat en el directorio C:\xampp\php\. Después, cambiamos el contenido de apigen.bat por el siguiente:

@php "C:\xampp\php\apigen.phar" generate

El problema de fondo es que ApiGen introduce el comando generate que no era necesario con anterioridad.

Además, debemos modificar la opción "ApiGen script" de Tools\Options\Frameworks & Tools para que apunte a C:\xampp\php\apigen.bat

Solución en GNU/Linux. Actualizar NetBeans

Tal y como cuentan en https://netbeans.org/bugzilla/show_bug.cgi?id=256081, Apigen 4+ está ya soportado en NetBeans 8.1.

Opciones de ApiGen

Las opciones de ApiGen las vamos a pasar a través de un archivo de configuración llamado apigen.neon (neon es un tipo de archivo de configuración relacionado con el framework Nette), con el siguiente contenido:

title: Mi proyecto PHP source: - ./ destination: documentation

Después de esto le indicamos al proyecto que utilice este archivo de configuración para ApiGen. Haremos esto en la opción Configuration file en la opción Properties\Apigen del menú contextual del proyecto (clic derecho).

Definiendo las opciones de ApiGen.

A partir de aquí, podemos volver a generar la documentación correctamente.

Las opciones de ApiGen

ApiGen no funciona igual de bien en Windows que en GNU/Linux... cosas de la vida. Por eso, aunque en la documentación de ApiGen se afirme que el comando apigen generate --help generará una lista con las opciones, se trata de una verdad en GNU/Linux. Al menos, en Windows, no lo he conseguido.

Las opciones disponibles en ApiGen son las siguientes:

Opciones obtenidas al ejecutar el comando apigen generate --help en GNU/Linux

Para utilizar las opciones aquí indicadas, debemos utilizar notación "camelCase", como se indica en el proyecto de ApiGen. Es decir, que la opción --no-source-code debe aparecer en el archivo "apigen.neon" del siguiente modo:

noSourceCode: true

Actividad 3. Retoma la actividad 2, en que creaste tu propio proyecto, y documéntalo. Asegúrate de que todos los archivos están documentados. Utiliza un archivo de configuración "neon".

Entrega la actividad en un archivo llamado Act3-netbeans.zip. El archivo debe incluir las siguientes cuestiones:

  • La carpeta con el proyecto, y una carpeta llamada doc donde se pueda ver la documentación generada.
  • Una imagen llamada configuracion_apigen donde se pueda ver la configuración de apigen para el proyecto, apuntando al archivo "neon"
  • Una imagen llamada salida_netbeans.pngdonde pueda verse la salida de NetBeans al generar la documentación.

También podemos usar ApiGen desde consola, ejecutando el comando y las opciones que deseemos incluir. Algo como:

apigen generate -s ./ -d ./documentos --no-source-code

o bien, si estamos usando un archivo con formato "neon":

apigen generate --config ./apigen.neon

Administrador de tareas

En el administrador de tareas podemos ver las líneas de nuestro código que incluyen palabras como TODO o FIXME.

Para mostrar el panel, debemos elegir la opción Window \ Action items, o bien Ctrl+6.

NetBeans escanea automáticamente el documento. Si un @TODO no aparece, sin duda aparecerá en breve.

Depuración con NetBeans

NetBeans ya ayuda a detectar gran parte de los errores sintácticos durante la escritura. El problema está con los errores que son detectables a simple vista y que tiene relación con la lógica del programa.

Depuración de código PHP con XDebug

XDebug permite inspeccionar variables, declarar puntos de ruptura y evaluar código, además de otras características.

Para configurar XDebug en Windows, debemos seguir los siguientes pasos:

  1. Localizar el archivo php.ini. Una forma sencilla de localizarlo es utilizando la función phpinfo()
  2. Se puede ver que php.ini está en C:\xampp\php\php.ini.
  3. A continuación abrimos php.ini y buscamos la siguiente línea:
  4. [XDebug] ;zend_extension = "C:\xampp\php\ext\php_xdebug.dll"
  5. Después, debemos encontrar y descomentar las siguientes líneas, eliminando el ";" delante:
  6. zend_extension = "C:\xampp\php\ext\php_xdebug.dll" xdebug.remote_enable = 1 xdebug.remote_handler = "dbgp" xdebug.remote_host = "127.0.0.1" xdebug.trace_output_dir = "C:\xampp\tmp"
  7. Después, guardamos el archivo php.ini y reiniciamos XAMPP.
  8. Para verificar que si el módulo XDebug ha sido activado nuestra página phpinfo() anterior.
  9. Se puede observar que XDebug está activado cuando vemos que aparece en el informe de phpinfo()
  10. Si tenemos activado XDebug, ya podremos notar algunos cambios. Por ejemplo, podemos observar el antes y el después de ejecutar un código sencillo como el siguiente:
  11. <?php $var = array("Volvo", "BMW", "Toyota"); var_dump($var); ?>
    Resultado el código anterior sin XDebug activado

    Al activar XDebug podemos ver una salida realzada de var_dump.

    Resultado el código anterior con XDebug activado

Instalar y configurar XDebug en GNU/Linux

Utilizando una distribución basada en Debian, podemos hacer lo siguiente:

  1. Instalar el paquete php5-xdebug:
  2. # apt-get install php5-xdebug
  3. Editar el archivo /etc/php5/mods-available/xdebug.ini añadiendo las siguientes líneas:
  4. zend_extension=xdebug.so xdebug.remote_enable=1 xdebug.remote_host=127.0.0.1 xdebug.remote_port=9000 xdebug.remote_handler=dbgp
  5. Reiniciar apache
  6. # service apache2 restart

Depurar un código PHP con NetBeans

Ahora que nuestro intérprete PHP tiene activado XDebug, vamos a preparar nuestro IDE para escuche lo que XDebug tenga que decir. La siguiente imagen muestra cómo se relaciona el IDE (NetBeans) con XDebug por medio del protocolo DBGp

El IDE recibe información de XDebug.

En nuestro caso hemos limitado la depuración a la máquina local, ya que en php.ini utilizamos el valor siguiente

xdebug.remote_host = "127.0.0.1"

Ahora que tenemos XDebug activado, vamos a ir a NetBeans, y configurarlo para que utilice XDebug para la depuración. Para ello, vamos a Tools\Options\PHP\Debugging

Desde esta ventana indicamos a NetBeans que escuche los mensajes de DBGp.

En esta ventana desmarca la casilla Stop at first line, ya que queremos detener en la linea que nosotros indiquemos. Debemos marcar también la casilla Watches and Balloon Evaluation, para poder examinar el valor de las variables durante la depuración. El significado de estas opciones es el siguiente:

  • Maximum Depth of Structures establece la visibilidad de las estructuras anidadas (como arrays anidados, objetos dentro de objetos, etc.).
  • Maximum Number of Children establece la visibilidad los elementos de un array durante su visualización. Si establecemos un máximo de 1, veremos solamente el primer elemento del array si tiene más de uno.

En la imagen se puede ver el campo Session ID. Cuando XDebug (a través de DBGp) conecta con el IDE, manda un primer paquete (init) que incluye entre otras cosas el campo IDEKEY. mediante phpinfo() podemos conocer el valor de dicha clave:

Valor de IDE KEY

El valor del IDE Key se puede moficar en php.ini, añadiendo en la sección de XDebug una línea com la siguiente:

xdebug.idekey = "netbeans-xdebug" xdebug.remote_enable = 1 xdebug.remote_handler = "dbgp" xdebug.remote_host = "127.0.0.1" xdebug.trace_output_dir = "C:\xampp\tmp"

Poniendo a prueba XDebug

Vamos a crear un nuevo proyecto. Llamémoslo depurando. Seguimos los siguientes pasos:

  1. Creamos el nuevo proyecto.
  2. Escribimos el siguiente código dentro de index.php
  3. <?php $distribuciones = array("Debian","Ubuntu","Fedora","OpenSUSE"); $miDistribucion = ""; selectorDistribucion(); // Primera llamada echo "Mi destribución es : " . $miDistribucion . "<br/>\n"; selectorDistribucion(); // Segunda llamada echo "Mi destribucion ahora es : " . $miDistribucion . "<br/>\n"; selectorDistribucion(); // Tercera llamada echo "Finalmente mi distribución es : " . $miDistribucion . "<br/>\n"; function selectorDistribucion() { Global $miDistribucion, $distribuciones; $miDistribucion = $distribuciones[rand(0, 3)]; // Elijo aleatoriamente una distribución. } ?>
  4. Para poder depurar a partir del punto de ruptura, podemos hacer clic en el número de línea, como se ve en la imagen siguiente:
  5. Creando un punto de ruptura. A partir de este punto podemos ir viendo línea a línea lo que está ocurriendo.
  6. Para iniciar la depuración, hacemos clic con el botón derecho sobre el proyecto, y elegimos la opción Debug. El depurador se detendrá en el depurador. El navegador abre una página en modo de pregarga con URL localhost/depurando/index.php?XDEBUG_SESSION_START=netbeans-xdebug
  7. Para avanzar un paso, podemos pulsar F7 o bien hacer clic sobre el botón indicado en la imagen siguiente:
  8. Avanzar una instrucción hacia delante.
  9. En cada nuevo paso podemos ver el valor de las variables, como se aprecia en la imagen anterior. Además de nuevo paso, podemos llevar a cabo otras acciones, mediante los botones que están junto a "Step Into"

Además de ver las variables del contexto de ejecución, es posible "hacer preguntas" a XDebug mediante expresiones. Por ejemplo, vamos a hacer una pequeña modificación al código fuente que acabamos de depurar. En concreto, la función seleccionarDistribucion() debe quedar como sigue:

function selectorDistribucion() { Global $miDistribucion, $distribuciones; $anteriorDistribucion = $miDistribucion; $miDistribucion = $distribuciones[rand(0, 3)]; // Elijo aleatoriamente una distribución. }

Supongamos que queremos comprobar si $anteriorDistribucion coincide con $miDistribucion. Entonces debo añadir una nueva expresión de control. Para ello, elegimos Debug\New Watch.

Creación de una nueva expresión de control.

La expresión de control está entre paréntesis, y utiliza operadores de comparación. Es similar lo que podríamos hacer en un if

Una vez que ha sido creada la expresión, se mostrará durante la depuración como muestra la siguiente imagen.

La condición es verdadera en este momento, porque $distribucionActual y $miDistribucion coinciden.

Actividad 4. Basándote en la actividad 3, en la que documentaste el proyecto, utiliza XDebug para depurar tu proyecto.

Toma varias capturas donde se pueda ver cómo has configurado xdebug:

  • Una captura donde se pueda ver la configuración de XDebug en NetBeans
  • Una captura donde se pueda ver la configura de XDebug en el servidor donde está el proyecto (que puede ser el mismo servidor) que donde está NetBeans
  • Una captura donde se pueda ver la sesión de depuración, de forma que se pueda ver el valor de una o más variables.
  • NetBeans Entrega la actividad en un archivo llamado Act4-netbeans.png