Como una librería me obligó a programar toda una API. Parte II: namespace y .env

Continuamos con esta historia en la que me vi obligado a crear una API por culpa una librería actualizada, recuerda que puedes leer la primera parte:

Análisis de creación de REST API

En el artículo anterior repasamos cómo me enfrenté a tener que escoger entre las distintas posibilidades de actualización e hice un repaso a todos los elementos, que en el momento previo a la programación de la API, analicé que podría necesitar.

¿Qué librerías escojo? ¶

En el vasto mundo de internet, las posibilidades son incontables. Muchos sistemas contienen librerías estrechamente ligadas a una API:

• Librerías puras del lenguaje.
• Frameworks.
• CMS.

Aprovecho para recomendarte que leas este articulo: Programación a medida, Framework o CMS. ¿Con cuál me quedo?. En él hago un análisis de cinco claves a tener en cuenta a la hora de decidirse por un sistema u otro.

Lo único que tenía claro por el momento era que la opción que eligiera, tenía que utilizar el lenguaje PHP.

Podría aventurarme a utilizar un lenguaje en el que no me sintiera cómodo, pero en este caso premiaba la necesidad de actualizar una librería, que desde ya, estaba desactualizada.

Finalmente decidí optar por la opción de instalar librerías que de forma independiente me dieran la posibilidad de desarrollar todos los puntos que necesitaba: rutas, middleware, variables de entorno, etc.

Durante mi mentorización con Daniel Primo, me descubrió un paquete de librerías de PHP que contenían muchas de las funcionalidades que necesitaba: ThePHPLeague.

Además la filosofía de la herramienta me gustaba, el index de su página oficial reza:

La liga de los paquetes extraordinarios es un grupo de desarrolladores que se han unido para construir paquetes PHP sólidos y bien testeados usando estándares modernos de codificación.

¿Cómo me deshice de los famosos require_once() ¶

Si hay algo que realmente saca de quicio a un programador que lleve a cabo una programación orientada a objetos, es el hecho de hacer referencia a archivos externos en código.

Hacer referencias a clases para crear objetos, es una pasada. Cada cual tiene su responsabilidad y cuando tienes que cambiar algo, en lugar de cambiarlo en varios archivos, se cambia en la definición de la clase. ¡Genial!

Pero esto conlleva un daño colateral, y es que hacer referencia a archivos que se encuentran en un nivel superior de directorio, además de la continua colisión de referencias; ¡Es un auténtico infierno!

Pero ya encontraron solución para esto y se llama estándar PSR. Tenéis más información de los distintos estandares PSR en su página oficial.

¿Vamos a meter las manos en faena, no?

Lo primero que tenemos que instalar en nuestro equipo es Composer.

Composer es el instalador oficial de librerías PHP y nos facilita mucho la vida a la hora de realizar instalación de librerías dentro de nuestro proyecto.

Podemos instalar Composer desde su página web oficial.

Es hora de crear una carpeta de proyecto. Dentro vamos crear un archivo llamado composer.json en la raíz del proyecto.

El archivo contendrá simplemente un objeto vacío:

{

}

Una vez creado el archivo, vamos a dirigirnos a la línea de comandos y ejecutar un comando que ahora será reconocido por nuestro sistema operativo:

composer install

Este comando nos creará una carpeta /vendor, necesaria para ejecutar librerías instaladas a través de Composer.

Para instalar PSR en su especificación 4 (PSR-4), añadiremos las siguientes líneas a nuestro archivo composer.json:

{
    'autoload':{
        'psr-4': {
            'TestNamespace\\': 'src'
        }
    }
}

La especificación PSR-4 se encarga de la gestión del autoload (auto carga) de las clases y las rutas de las mismas.

Si nos fijamos bien, hay dos parámetros que hemos tenido que especificar, el primero: TestNamespace, hace referencia al nombre del espacio de trabajo. Este nombre será utilizado frecuentemente durante el desarrollo de nuestro proyecto. src hace referencia a la carpeta en la que se contendrá nuestro espacio de trabajo. De este modo cada vez que se haga referencia a TestNameSpace, el sistema entenderá que nos referimos a un archivo contenido dentro de la carpeta /src.

Cada cambio que se realice en nuestro archivo composer.json debe de ser implementado ejecutando el siguiente comando en consola:

composer dump-autoload

A partir de ahora, cada declaración de clase dentro de la carpeta /src (que en un futuro contendrá todos nuestro controladores) contendrá una declaración al namespace de esta forma (siempre al comienzo del archivo):

<?php

namespace TestNamespace;

Para poder usar otras clases dentro del mismo directorio (o subdirectorio del mismo), simplemente tendremos que hacer referencia a ellos con use, de la siguiente forma:

<?php

namespace TestNamespace;
use TestNamespace\subFolder\TestInSubfolder;

Por último, sólo nos queda cargar la librería autoload en el punto de entrada de la aplicación para que todo lo que hemos configurado surta efecto. Esta acción se lleva acabo normalmente en el archivo index.php (o bien en cualquier parte del código por el que sepamos que la aplicación va a pasar siempre).

En el raíz de la aplicación, vamos a crear el archivo index.php con el siguiente código:

<?php

require 'vendor/autoload.php';

¿Cómo cargar variables de entorno en nuestra aplicación? ¶

Puede que te estés preguntando:

¿para qué necesitamos cargar variables de entorno en nuestra aplicación?

Por una razón muy sencilla: porque queremos tener todas nuestras variables en un mismo lugar, ya que hace mucho más sencillo su mantenimiento; y porque las variables de entorno del sistema operativo son un lugar seguro donde albergarlas sin que tengamos que depender variables de sesión (algo muy utilizado en entornos de programación PHP normalmente).

En nuestro caso vamos a utilizar la librería vlucas/phpdotenv, puedes encontrar su código en el repositorio oficial de GitHub.

Gracias a esta librería, todas las variables de configuración que utilice la aplicación estarán albergadas en un archivo .env que se encontrará en el raíz de la aplicación.

Con variables de configuración nos referimos a cualquier cosa que la aplicación pueda necesitar para su correcto funcionamiento, entre otras podemos señalar:

• IP, usuario, password de la base de datos.
• URL principal de la aplicación.
• Datos de token.

Para realizar la instalación de phpdoenv ejecutaremos el siguiente comando:

composer require vlucas/phpdotenv

Ahora es el momento de crear un archivo .env en el raíz de nuestro proyecto y declarar una variable.

##APP (Esto es un comentario)
APP_URL=https://localhost

Debido a que este es un archivo que contiene información sensible, tenemos que incluirlo dentro del archivo .gitignore para que no sea subido a nuestro repositorio.

Para que el desarrollador que se baja el código conozca las variables a configurar dentro de la aplicación, es buena práctica crear un archivo .env-example en el mismo directorio raíz que contenga la declaración de variables sin valor asignado.

Para que se realice la carga de variables de entorno, en el archivo index.php de nuestra aplicación añadiremos:

<?php 

require 'vendor/autoload.php';

$dotenv = Dotenv\Dotenv::createImmutable(__DIR__);
$dotenv->load();

echo $_ENV['APP_URL'];

Como hemos podido ver, además podemos acceder al valor estas variables a través de $_ENV['nombreVariable'].

En este caso, el navegador nos mostrará el valor https://localhost.

Dos pasitos ya andados ¶

Seguimos pasito a pasito, andando, para la consecución de nuestra API; y estos dos pasos no han sido pequeños.

En este artículo hemos visto cómo crear un espacio de nombres (namespace) y como declarar nuestras propias variable de entorno para poder tener las mismas contenidas en un archivo independiente (¡Bye Bye db.php!).

Podéis encontrar todo el código que hemos desarrollado hoy en este siguiente repositorio de Github.

Os espero en la siguiente entrega de la creación de la API.

¡Esto va creciendo ya!