Inicializa un proyecto PHP usando composer


Si tienes alguna idea novedosa, o simplemente te gustaría mejorar alguna librería existente agregando alguna funcionalidad o haciéndola compatible con tu framework favorito entonces este post es para ti.

El proceso de construcción de una librería puede variar dependiendo de tus requerimientos, pero en esta guia te compartiré los primeros pasos para iniciar tu proyecto utilizando composer. El contenido de éste post se resume en:

  • ¿Qué es composer?
  • Requisitos de la guía.
  • Inicializando el proyecto.
  • Registrar el namespace de nuestro proyecto en composer
  • Crear un archivo de utilerías y registrarlo en composer.

 

¿Qué es composer?

Composer es una herramienta que nos ayuda a gestionar las dependencias de nuestro proyecto, siendo éstas librerías externas o simplemente ficheros o clases internas. Composer se encarga desde la instalación de dependencias externas hasta la integración de nuestras clases o funciones, se basa en el uso de las convenciones PSR de PHP para logar su objetivo. Si quieres saber más de composer o de PSR puedes revisar los siguientes links:

 

Requisitos de la guia.

El único requerimiento para seguir ésta guía es tener PHP instalado y una copia composer (ejecutable o instalada) en tu computadora, para más detalles revisa la documentación oficial.

 

Inicializar el proyecto.

Para comenzar a trabajar en un proyecto, crearemos una carpeta con la siguiente estructura:

 

src

La carpeta src será la encargada de contener todo el código de nuestro proyecto, y aunque no es obligatorio que la carpeta de llame src, es una buena práctica ya que la mayoría de los desarrolladores están acostumbrados a manejarlo de esta manera.

 

README.md

Este es uno de los archivos más importantes de tu proyecto, se trata de un documento que contiene la definición completa de tu ibrería, notas de instalación, de uso, futuros planes, entres otros. Prácticamente es la carta de presentación de tu librería.

El archivo README está escrito en markdown y por ahora puedes dejarlo en blanco, o si gustas, puedes escribir algo como lo siguiente:

 

Composer.json

El archivo composer.json es el más importante de esta guía. Este archivo será el encargado de gestionar las dependencias de nuestro proyecto, cómo habrás notado, se trata de un archivo json, el cual debe tener por lo menos las siguientes entradas:

Nota: Para éste ejemplo en concreto utilizaremos mis datos personales al igual usuario de github (javleds) y llamaremos FabulosaLibreria al proyecto, en tu caso asegúrate de cambiar estos datos.

Cuyas entradas son:

  • name: Nombre de la librería conformada de 2 partes separadas por una diagonal (/):

    • Autor, empresa o usuario de git.
    • Nombre de la librería usando.

    Nota: Es muy importante este nombre, ya que será utilizado posteriormente para poder utilizarla en otros proyectos, utilizando composer require autor/nombre-libreria

  • description: Una descripción corta de lo que hace tu librería.

  • type: Define el tipo de proyecto, puede ser de diversos tipos: library, project, metapackage o composer-plugin.

  • authors: Lista de autores que participan en el desarrollo del proyecto.

  • version: Versión actual del proyecto.

  • license: Licencia del proyecto, en general te recomiendo darle una leída a las licencias existentes, pero si quieres que tu librería sea open source, puede utiliza MIT o BSD.

Una vez que tenemos definidos éstos campos ya tenemos una liberería declarada en composer.

 

Registrar el nombre de espacio de nuestro proyecto en composer

Para lograr que nuestras clases de php sean cargadas de manera automática en nuestro proyecto será necesario registrar un nombre de espacio ( o namespace) en el archivo composer.json.

Un nombre de espacio es lo equivalente a un directorio virtual, nos sirve para darle un identificador único a nuestras clases y evitar colisiones con clases similares de otras librerías. Por ejemplo, la clase User es utilizada en muchos paquetes, pero puedes diferenciarlas a través de un espacio de nombre. Regularmente el espacio de nombre se compone del usuario de USUARIO_GIT\NOMBRE_LIBRERIA, en éste caso usaremos Javleds\FabulosaLibreria .

Para llevar ésto a la práctica, crearemos un nuevo archivo en la carpeta libreria/src llamado Mensajes.php con el siguiente código:

La estructura de nuestro proyecto debería quedar así:

Una vez que hemos creada nuestra primera clase, es necesario registrar nuestro directorio /src con el espacio de nombre acordado para que sea reconocido por composer, para ello, editamos el archivo composer.json y agregamos la entrada autoload.psr-4:

Cuyas nuevas entradas son:

  • autoload: Le indicamos a composer que queremos que cargue de manera automática todos los registros de esta entrada.

  • psr-4: Le indíca a composer que todos los archivos dentro de la carpeta src que cumplan con el estándar PSR-4 seán auto-registradas con el namespace Javleds\FabulosaLibreria. Nota que las diagonales invertidas (\) deben ser escapadas utilizando doble diagonal invertida (\\).

Nota importante: Después de modificar el archivo composer.json, debemos indicarle a composer que actualice la información, para ello ejecutamos el comando composer dump-autoload

Una vez registrado el namespace de nuestra librería, debemos indicarle a nuestra clase Mensajes que pertenece a ese namespace, para ello, editaremos el archivo src/Mensajes.php y agregaremos la siguiente línea:

Importante: El namespace debe ser la primera línea de código de nuestro archivo PHP

 

Finalizado este proceso de registro, ahora podemos hacer uso de la clase Mensajes en cualquier proyecto de la siguiente manera:

Si necesitaramos crear más archivos dentro de la carpeta src solo debemos seguir las convenciones PSR-4 mencionadas anteriormente, por ejemplo, crearemos el archivo src/Utilerias/Calculadora.php con lo siguiente:

Estructura del proyecto:

Y cuyo uso sería:

 

Para utilizar ésta clase no es necesario editar el archivo composer.json ni ejecutar el comando composer dump-autoload porque el directorio src ya está registrado en composer.

 

Crear un funciones globales y registrarlas en composer

Si lo que deseas es tener funciones disponibles a lo largo de todo tu proyecto, puedes crear un archivo php que contenga dichas funciones y registrarlo en composer, para ejemplificarlo, crearemos el archivo src/funciones_globales.php con lo siguiente:

Estructura del proyecto:

Una vez creado debemos registrarlo en nuestro archivo composer.json agregando la entrada autoload.files como se muestra a continuación:

Nota: No olvides ejecutar composer dump-autoload para obtener los últimos cambios del archivo composer.json

Al agregar esta entrada las funciones contenidas en el archivo src/funciones_globales.php se cargarán automáticamente y estarán disponibles en todo el proyecto. A diferencia de la entrada psr-4, la entrada files solo puede mapear un solo archivo, por lo que será necesario editar esta entrada cada que requieras agregar más archivos php con funciones globales.

Para utilizar nuestra función en cualquier parte del proyecto solo debemos invocarla desde cualquier lado que sea necesaria de la siguiente manera:

 

Conclusión

Composer es una herramienta que nos ayuda bastante a desarrollar proyectos reutilizables, haciendo un buen uso de él podemos escalar nuestros proyectos muy fácil. Te invito a comiences a trabajar una idea propia o mejorar alguna que ya existe. Si ya lo has hecho, compartenos tu experiencia en los comentarios.