Con la reutilización del código surge el problema de la gestión de dependencias, históricamente un proceso bastante manual y propenso a errores. Afortunadamente, en los últimos años la mayoría de los lenguajes de programación han resuelto este problema introduciendo diversas herramientas para la gestión de dependencias. En el ecosistema PHP, Composer se ha convertido en el estándar gracias a su facilidad de uso, flexibilidad y amplia adopción.

Aunque Composer se creó para la gestión de dependencias, también puedes utilizarlo para tareas como:

  • Carga automática: Cargar automáticamente clases y funciones de bibliotecas externas para hacerlas fácilmente accesibles desde tu código y simplificar el proceso de integración de código externo en tu proyecto.
  • Generación de código: Genera código repetitivo para tu proyecto, como archivos de configuración u otros fragmentos de código de uso común para acelerar el proceso de desarrollo y garantizar la coherencia.
  • Programación: Un sistema de scripts integrado puede automatizar tareas comunes, como ejecutar pruebas o generar documentación a partir de tu base de código. Esto puede ayudar a agilizar tu flujo de trabajo de desarrollo y reducir el trabajo manual.

Este tutorial paso a paso te guía para crear tu propio paquete Composer y publicarlo en Packagist, un repositorio de paquetes PHP que los desarrolladores de todo el mundo pueden utilizar en sus propios proyectos.

¿Cómo funciona Composer?

Primero, asegurémonos de que entendemos Composer. En términos sencillos, Composer funciona utilizando un archivo composer.json que contiene las definiciones de las dependencias de tu proyecto PHP. Busca esos paquetes en un repositorio centralizado y luego descarga e instala automáticamente esas dependencias utilizando el repositorio de paquetes.

Suponiendo que ya tienes Composer instalado en tu entorno de trabajo PHP, éste es el aspecto de su proceso de descarga e instalación de dependencias:

  1. Define las dependencias necesarias para tu proyecto en un archivo composer.json en el directorio raíz de tu proyecto. Este archivo incluye información sobre las bibliotecas necesarias y sus versiones, así como cualquier otro ajuste de configuración o dependencia de dichas bibliotecas.
  2. Resuelve las dependencias en Composer con comandos como install para instalar las dependencias necesarias; update para actualizar las dependencias existentes; y require para añadir nuevas dependencias al archivo composer.json. Cuando ejecutas un comando, Composer lee el archivo composer.json para determinar las dependencias necesarias, comprueba en el repositorio de paquetes la última versión de cada dependencia adecuada para tu entorno PHP y, a continuación, comprueba si hay conflictos o restricciones de versión.
  3. Composer descarga e instala las dependencias necesarias, incluidas las bibliotecas, en el directorio vendor de tu proyecto. Composer crea un archivo composer.lock que registra las versiones exactas de las dependencias instaladas.
  4. Composer configura un cargador automático que carga automáticamente las clases y funciones de las dependencias instaladas. Esto facilita el uso de las bibliotecas instaladas en tu proyecto sin tener que incluir manualmente cada archivo.

En resumen, Composer simplifica la gestión de dependencias en los proyectos PHP, facilitando la instalación, actualización y uso de bibliotecas y frameworks externos.

Crear y publicar un paquete Composer

Este tutorial te muestra cómo crear una sencilla biblioteca PHP llamada tempconv que convierte la temperatura Celsius a Fahrenheit y viceversa, y termina publicándola como paquete Composer.

Requisitos previos

Necesitarás un par de cosas antes de empezar:

  • PHP y Composer instalados correctamente en tu sistema. En el momento de escribir esto, la última versión de Composer es la v2.6.6, pero estas instrucciones deberían funcionar con cualquier variante de la v2.
  • Una cuenta de GitHub para crear un repositorio donde alojar tu código.
  • Una cuenta Packagist para publicar tu biblioteca.

Crear un repositorio del proyecto

Crea tu propio repositorio de GitHub para este tutorial, donde podrás publicar el código y los archivos de tu biblioteca terminada.

Captura de pantalla de la página que se ve al crear un repositorio en GitHub.
Crear el repositorio del proyecto en GitHub.

Este tutorial utiliza el nombre de proyecto tempconv. En el campo Descripción, proporciona breves detalles sobre la aplicación. Marca la casilla para añadir un archivo README, elige la plantilla Composer para la opción Añadir .gitignore, y selecciona una licencia de tu elección—este tutorial utiliza la Licencia MIT. Por último, haz clic en Crear repositorio.

Clona el repositorio

Clona el repositorio que acabas de crear en tu máquina local. No olvides sustituir la URL por la tuya, tanto aquí como a lo largo de este tutorial:

$ git clone https://github.com/rexfordnyrk/tempconv.git

Esto crea un directorio llamado tempconv en tu directorio de trabajo actual. En este momento, sólo contiene los archivos README.md, LICENSE y .gitignore, pero también crearás aquí los archivos de tu paquete.

Crear tu biblioteca PHP

En el directorio de tu proyecto, añade un archivo llamado TemperatureConverter.php con el siguiente código:

<?php

namespace RexfordnyrkTempconv;

class TemperatureConverter
{
    //Caller must provide the temperature value and the unit either C Celsius or F Fahrenheit
    public function convert($temperature, $unit)
    {
        //Checking whether the unit we're working with is Celsius or Fahrenheit
        if ($unit === 'C') {
            $fahrenheit = ($temperature * 9 / 5) + 32;
            return $fahrenheit;
        } elseif ($unit === 'F') {
            $celsius = ($temperature - 32) * 5 / 9;
            return $celsius;
        } else {
            //Throwing error if the unit provided is neither C nor F
            throw new InvalidArgumentException('Invalid unit, only C (Celsius) or F (Fahrenheit) are allowed');
        }
    }
}

Esta clase tiene un único método llamado convert que toma la temperatura y la unidad como argumentos y devuelve la temperatura convertida. Lanza una excepción si la unidad no es válida.

Por ahora es suficiente. En un escenario real, probablemente escribirías pruebas unitarias para asegurarte de que tu código funciona como se espera tras modificaciones o actualizaciones.

Crear tu paquete composer.

Con el código de tu biblioteca en su sitio, es hora de convertirlo en un paquete Composer. Generarás un archivo composer.json para tu paquete utilizando un asistente paso a paso, y trataremos algunas de las mejores prácticas para organizar tu código como un paquete antes de enviarlo a tu repositorio.

Generar un archivo de paquete composer.json

Aunque podrías escribir manualmente el contenido de un archivo composer.json en la raíz del directorio de tu proyecto, es mejor generarlo utilizando el siguiente comando de Composer:

$ composer init

Este comando te lleva a través de un pequeño asistente paso a paso. Las respuestas que des a preguntas como el nombre del paquete, la descripción, la información sobre el autor y el tipo de licencia generarán el archivo composer.json de tu paquete.

La documentación de Composer describe los valores esperados, así como otras opciones que puedes utilizar para definir el composer.json de tu proyecto.

Captura de pantalla del generador de configuraciones de Composer en acción.
Utilizar composer init para generar una configuración.

Observa que el asistente proporciona respuestas predefinidas a las preguntas cuando procede, como obtener tu nombre y correo electrónico de git. Si quieres, puedes cambiarlas.

Esta biblioteca no depende de ningún otro paquete para funcionar, así que puedes responder No a las preguntas que especifican dependencias.

El asistente te muestra una vista previa del contenido del archivo generado y te pide que lo confirmes para completar el asistente.

Organizar los archivos del paquete

Al completar el asistente se crean dos directorios además del archivo composer.json:

  • src para tu código fuente
  • vendor para tus dependencias descargadas

Mueve el archivo TemperatureConverter.php al directorio src. Si tu biblioteca tiene dependencias, ejecuta composer install para generar el autoloader e instalar las dependencias del paquete.

Subir el código a GitHub

Añade tus cambios y archivos nuevos a git:

$ git add -A

Haz commit de los cambios realizados en el repositorio local y envíalo al repositorio remoto en GitHub para que puedas publicar fácilmente el proyecto en la siguiente sección:

$ git commit -am "Initial Release" && git push

Crear una versión de lanzamiento para tu biblioteca

Con tu código en tu repositorio, puedes crear una versión de tu biblioteca con un número de versión para que otros desarrolladores puedan hacer un seguimiento de tus actualizaciones estables e importantes.

Accede a tu repositorio en GitHub y haz clic en Releases (Versiones), debajo de la sección About (Acerca de). En la página Releases, donde se espera que no tengas nada en este momento, haz clic en Create a new release (Crear una nueva versión).

Una captura de pantalla de la página Releases de GitHub.
Página Releases de GitHub.

Rellena algunos detalles sobre tu publicación, como la versión de la etiqueta y el título de la publicación. La versión de la etiqueta debe ser un identificador único para esta versión (ejemplo: v1.0.0), y el título de la versión debe describir los cambios incluidos en la versión (ejemplo: Versión inicial).

Opcionalmente, puedes añadir una descripción de la versión. Si quieres subir un archivo, como un binario compilado o un archivo de código fuente, arrastra y suelta el archivo en el área Adjuntar binarios soltándolos aquí o seleccionándolos (Attach binaries by dropping them here or selecting them), pero eso no es necesario para este tutorial.

Captura de pantalla que muestra los detalles introducidos en la página Releases de GitHub.
Introducir los detalles de la versión inicial en GitHub.

Haz clic en Publicar versión (Publish release) para crear la versión.

Tu proyecto debería estar ahora disponible en la página Lanzamientos (Releases) de tu repositorio. Los usuarios pueden descargar cualquier archivo que hayas adjuntado y ver las notas de la versión. Además, si has añadido una etiqueta a la publicación, otros desarrolladores pueden utilizarla para comprobar el código exacto que se ha incluido en la publicación.

Tu biblioteca está lista para compartirla con el mundo. Vamos a publicarla como paquete en Packagist.

Primeros pasos con Packagist

Packagist es el principal repositorio de paquetes para PHP. Proporciona una ubicación central para que los desarrolladores publiquen y compartan sus paquetes PHP, y para que otros desarrolladores descubran y utilicen esos paquetes en sus propios proyectos. ¡Vamos a publicar tu paquete!

Navega hasta el sitio web de Packagist, haz clic en Iniciar sesión y selecciona GitHub como método de inicio de sesión para utilizar tu cuenta de GitHub para la autenticación.

Captura de pantalla que muestra la página de autorización de Packagist a través de GitHub.
Registrarse en Packagist con GitHub.

Haz clic en Autorizar para conceder permiso a Packagist para acceder a tu cuenta.

Captura de pantalla de un usuario conectado a Packagist.
Inicio de sesión con éxito en Packagist con GitHub.

Enviar tu paquete Composer a Packagist

Para publicar un paquete en Packagist, envía el repositorio de GitHub que contiene el archivo composer.json que describe tu paquete y sus dependencias. Haz clic en Enviar en el sitio de Packagist, indica la URL de tu repositorio en la página que aparece y haz clic en Comprobar para validarlo.

Si el repositorio es válido, Packagist detecta el nombre del paquete, y el botón Comprobar se convierte en Enviar.

Captura de pantalla de los detalles del paquete Composer listos para enviar a Packagist.
Paquete compositor rexfordnyrk/tempconv validado y listo para enviar.

Haz clic en Enviar, y Packagist tardará un momento en configurar y publicar tu proyecto.

Captura de pantalla de los detalles del paquete Composer después de publicarlo.
Paquete Composer publicado correctamente.

¡Ya está! Tu paquete ya está disponible en Packagist para que otros desarrolladores lo utilicen como dependencia en sus propios proyectos.

Utilizar tu paquete Composer en otros proyectos

Puedes utilizar tu paquete publicado en otros proyectos añadiéndolo como dependencia en el archivo composer.json. Puedes crear y editar manualmente el archivo, pero es mejor utilizar el comando Composer como se indica a continuación:

$ composer require rexfordnyrk/tempconv

Composer crea automáticamente el archivo composer.json si aún no existe, luego busca, descarga y carga automáticamente el paquete desde Packagist. El resultado debería ser algo parecido a esto

Captura de pantalla del terminal tras añadir una biblioteca a un proyecto con Composer.

Crea un archivo demo.php que contenga el código de tu aplicación de demostración para trabajar con tu biblioteca.
A continuación, puedes utilizar la clase TemperatureConverter en el código de tu aplicación de la siguiente manera:

<?php
use RexfordnyrkTempconvTemperatureConverter;

require_once './vendor/autoload.php';

$converter =  new TemperatureConverter();

$fahrenheit = $converter->convert(20, 'C');
echo "20°C is equivalent to $fahrenheit °Fn";

$celsius = $converter->convert(68, 'F');
echo "68°F is equivalent to $celsius °Cn";

Este código utiliza la clase TemperatureConverter para convertir las temperaturas 20 Celsius y 68 Fahrenheit y mostrar los resultados. El archivo importado autoloader.php fue creado por Composer para cargar todas las dependencias que necesites. Esto se encarga de cargar la clase automáticamente cuando es necesario.

Por último, ejecuta este código en tu terminal:

$ php demo.php

Deberías tener una salida similar a ésta:

$ php demo.php
20°C is equivalent to 68 °F
68°F is equivalent to 20 °C

Resumen

Acabas de crear una sencilla biblioteca PHP que convierte la temperatura de Celsius a Fahrenheit y viceversa en una clase orientada a objetos que puede reutilizarse en otras aplicaciones. Has visto cómo utilizar Composer para crear un paquete a partir de la clase con el comando Composer Init, y has aprendido algunas buenas prácticas básicas de organización del código para tu biblioteca. Publicaste tu biblioteca en Packagist, para que tú y otros desarrolladores pudierais utilizarla como dependencia en otros proyectos.

Por supuesto, una vez que hayas terminado de desarrollar tu aplicación, necesitarás alojarla. Lleva tu desarrollo PHP al siguiente nivel con el Alojamiento de Aplicaciones Web en Kinsta. Puedes desplegar tu aplicación PHP basada en Composer en cuestión de minutos. Sólo tienes que añadir tu aplicación a través del repositorio git de tu proyecto, y Kinsta se encarga del resto. Detecta automáticamente el archivo Composer y construye tu aplicación automáticamente. ¡Empieza hoy mismo sin riesgos!

Rexford Nyarko

Rexford Nyarko is a solution architect with a background in software and network systems, cloud environments, server administration, and various database technologies. Rexford particularly enjoys explaining technical concepts to non-technical audiences.