Download the PHP package rguezque/katya-router without Composer

Katya

A lightweight PHP router

Tabla de contenidos

• Install
• Configuration
  • Autoloader
• Routing
  • Shortcuts
  • Controllers
• Routes group
• Wildcards
• Views
• Request

• Response

  • HttpHeaders
  • Stream
• SapiEmitter
• Session
• Services
• Variables
• DB Connection
  • Connecting using an URL
  • Auto connect
• Middleware
• CORS
• Environment Management

Install

Desde la terminal en la raíz del proyecto:

Configuration

Para servidor Apache, en el directorio del proyecto crea y edita un archivo .htaccess con lo siguiente:

Para Nginx edita el archivo de configuración de la siguiente forma:

Para prueba desde el servidor inbuilt de PHP, dentro del directorio del proyecto ejecuta en la terminal:

Y abre en el navegador web la dirección http://localhost:80

Autoloader

Desde la terminal, ubícate dentro del directorio del proyecto y ejecuta:

Routing

Cada ruta se define con el método Katya::route, que recibe 3 argumentos, el método de petición (solo son soportados GET, POST, PUT, PATCH y DELETE), la ruta y el controlador a ejecutar para dicha ruta. Los controladores siempre reciben un objeto Request que contiene los métodos necesarios para manejar una petición (Ver Response).

Para iniciar el router se invoca el método Katya::run y se le envía un objeto Request.

Si el router se aloja en un subdirectorio, este se puede especificar en el constructor al crear la instancia del router.

[!TIP] El router devuelve tres posibles excepciones; RouteNotFoundException cuando no se encuentra una ruta, UnsupportedRequestMethodException cuando un método de petición no está soportado por el router o un UnexpectedValueException cuando el controlador no devuelve un tipo Response. Utiliza un try-catch para atraparlas y manejar el Response apropiado como se ve en el ejemplo.

Shortcuts

Los atajos Katya::get, Katya::post, Katya::put, Katya::patch y Katya::delete sirven respectivamente para agregar rutas de tipo GET, POST, PUT, PATCH y DELETE al router.

[!NOTE] Para detener el router en cualquier momento puedes utilizar Katya::halt que recibe un objeto Response que se envía antes de detener los procesos del router.

Controllers

Los controladores pueden ser: una función anónima, un método estático o un método de un objeto.

[!TIP] Si se usan métodos de un objeto como controladores se recomienda nombrar las clases con el sufijo Controller y los métodos con el sufijo Action para identificarlos mejor a través del proyecto.

Routes group

Para crear grupos de rutas bajo un mismo prefijo se utiliza Katya::group; recibe 2 argumentos, el prefijo de ruta y una función anónima que recibe un objeto Group con el cual se definen las rutas del grupo.

Wildcards

Los wildcards son parámetros definidos en la ruta. El router busca las coincidencias de acuerdo a la petición y los envía como argumentos al controlador de ruta a través del objeto Request, estos argumentos son recuperados con el método Request::getParams que devuelve por default un objeto Parameters donde cada clave se corresponde con el mismo nombre de los wildcards. El argumento por default de esté método es Request::PARAMS_ASSOC el cual indica que el array de parámetros tiene índices nombrados correspondientes a los wildcards y no numéricos.

El objeto Parameters tiene los siguientes métodos:

• get(string $key, mixed $default = null): Devuelve un parámetro por nombre o el valor default especificado, si no existe.
• set(string $key, mixed $value): Agrega o sobrescribe un parámetro.
• all(): Devuelve todo el array de parámetros.
• has(string $key): Devuelve true si un parámetro existe, false en caso contrario.
• valid(string $key): Devuelve true si un parámetro existe y si no es null y no está vacío; false en caso de que no cumpla alguna de las condiciones anteriores.
• remove(string $key): Elimina un parámetro por nombre.
• clear(): Elimina todos los parámetros.
• keys(): Devuelve un array lineal con los nombres de todos los parámetros.
• gettype(string $key): Devuelve el tipo de dato de un parámetro.

Si los wildcards fueron definidos como expresiones regulares envía el argumento Request::PARAMS_NUM el cual devuelve un array lineal con los valores de las coincidencias encontradas.

[!IMPORTANT] Evita mezclar parámetros nombrados y expresiones regulares en la misma definición de una ruta, pues no podrás recuperar por nombre los que hayan sido definidos como regex. En todo caso si esto sucede, envía el argumento Request::PARAMS_BOTH para recuperar un array con todos los parámetros en el orden que hayan sido definidos en la ruta.

Views

Las vistas son el medio por el cual el router devuelve y renderiza un objeto HtmlResponse con contenido HTML en el navegador. La única configuración que se necesita es definir el directorio donde estarán alojadas las plantillas en la instancia de la clase ViewEngine.

El método ViewEngine::fetch recibe el nombre de la plantilla (puede omitirse la terminación .view.php del archivo) y opcionalmente un array con variables. Devuelve en un string el contenidos de la plantilla, listo para ser enviado como un HtmlResponse. Los archivos deben nombrarse con la terminación .view.php.

Recibe los parámetros enviados en $data (según el ejemplo del bloque de código de arriba)

Otros métodos para agregar argumentos a la plantilla antes de invocar ViewEngine::fetch, son:

• addArgument(string $key, mixed $value): Agrega un argumento por nombre a la vez, a los ya existentes.
• addArguments(array $data): Agrega un array asociativo de argumentos de tipo clave-valor a los ya existentes.
• setArguments(array $data): Asigna o sobrescribe los argumentos para la plantilla.

También puedes utilizar ViewEngine::fetchAsArgument para renderizar una plantilla y agregarla como un argumento para enviarse a la plantilla principal en ViewEngine::fetch. Siguiendo el ejemplo anterior, modificado podría quedar así:

Y la vista principal quedaría así:

Request

Los métodos de la clase Request que empiezan con get devuelven un objeto Parameters con excepción de Request::getParams que puede variar.

• fromGlobals(): Crea un objeto Request con las variables globales PHP.
• getQuery(): Devuelve el array de parámetros $_GET.
• getBody(): Devuelve el array de parámetros $_POST.
• getPhpInputStream(int $option = Request::RAW_DATA): Devuelve el stream php://input sin procesar. Si se recibe la petición en formato JSON se envía un argumento Request::JSON_DECODE; si es un query string se envía el argumentoRequest::PARSED_STR. En estos últimos dos casos, devolverá un objeto Parameters.
• getServer(): Devuelve el array de parámetros $_SERVER.
• getCookies(): Devuelve el array de parámetros $_COOKIE.
• getFiles(): Devuelve el array de parámetros $_FILES.
• getParams(Request::PARAMS_ASSOC): Devuelve el array de parámetros nombrados de una ruta solicitada. Dependiendo de la definición de los wildcards de una ruta, se puede especificar el formato de datos a devolver (Ver Wildcards).
• getAllHeaders(): Devuelve todos los encabezados HTTP recibidos en la actual petición.
• setQuery(array $query): Asigna valores a $_GET.
• setBody(array $body): Asigna valores a $_POST.
• setServer(array $server): Asigna valores a $_SERVER.
• setCookies(array $cookies): Asigna valores a $_COOKIE.
• setFiles(array $files): Asigna valores a $_FILES.
• setParams(array $params): Asigna valores al array de parámetros nombrados.
• buildQuery(string $uri, array $params): Genera y devuelve una cadena de petición GET en una URI.

Response

Métodos de la clase Response.

• clear(): Limpia los valores del Response.
• setStatusCode(int $code): Asigna un código númerico de estatus HTTP.
• getStatusCode(): Devuelve el actual código de estatus HTTP.
• headers: Atributo público de tipo HttpHeaders. Contiene métodos para agregar encabezados HTTP al Response.
• body: Atributo público de tipo Stream. Contiene métodos para agregar contenido al cuerpo del Response.

[!TIP] Utiliza JsonResponse para devolver datos de una API en formato JSON y HtmlResponse para devolver contenido html.

HttpHeaders

• set(string $key, string $value): Agrega un encabezado.
• get(string $key, ?string $default = null): Devuelve un encabezado por nombre.
• remove(string $key): Elimina un encabezado por nombre.
• clear(): Elimina todos los encabezados.
• all(): Devuelve todos los encabezados en un array.
• has(string $key): Devuelve true si un encabezado existe, false en caso contrario.

Stream

• write(mixed $string): Escribe contenido y retorna el total de bytes escritos; o false en error.
• read(int $length): Lee el stream.
• getContents(): Recupera el contenido restante del stream desde la posición actual del puntero.
• detach(): Libera y devuelve el flujo actual.
• getSize(): Devuelve el tamaño en bytes del stream.
• tell(): Devuelve la posición actual del puntero de lectura/escritura del stream.
• eof(): Devuelve true si el puntero del stream está al final del archivo; false en caso contrario.
• seek(int $offset, int $whence = SEEK_SET): Establece el indicador de posición del archivo referenciado por el stream. La nueva posición, medida en bytes desde el principio del archivo, se obtiene sumando el desplazamiento a la posición especificada por consiguiente.
• rewind(): Rebobina el puntero del stream al inicio.
• close(): Cierra el flujo contra escritura.

SapiEmitter

Emite el Response con el método estático SapiEmitter::emit.

Para más control utiliza try-catch:

Session

La clase Session sirve para la creación de sesiones y la administración de variables de $_SESSION que son almacenadas en un namespace privado del router. Se inicializa o selecciona una colección de variables de sesión con el método estático Session::create el cual devuelve un singleton de la clase. Los métodos disponibles son:

• create(string $session_name = Session::NAMESPACE): Crea o reanuda una sesión. Se envía como argumento un nombre para la sesión; aunque no es obligatorio es recomendable hacerlo para evitar colisiones de variables con otras aplicaciones. Por default se asigna un nombre definido por el router.

  [!TIP] Utiliza variables de entorno (.env) para declarar un nombre de sesión a través de toda la aplicación.

• start(): Inicia o retoma la sesión activa.
• started(): Devuelve true si la sesión está activa.
• set(string $key, mixed $value): Crea o sobrescribe una variable de sesion.
• get(string $key, mixed $default = null): Devuelve una variable de sesión, si no existe devuelve el valor default que se asigne en el segundo parámetro.
• all(): Devuelve un array con todas las variables de sesión del actual namespace.
• has(string $key): Devuelve true si existe una variable de sesión.
• valid(string $key): Devuelve true si una variable de sesión no es null y no está vacía.
• remove(string $key): Elimina una variable de sesión.
• clear(): Elimina todas las variables de sesión.
• destroy(); Destruye la sesión actual junto con las cookies y variables de sesión.

[!NOTE] Session::start se invoca automáticamente en cada llamado del resto de métodos pero se deja como acceso público.

Services

La clase Services sirve para registrar servicios que se utilizarán en todo el proyecto. Con el método Services::register agregamos un servicio, este recibe 2 parámetros, un nombre y una función anónima. Para quitar un servicio Services::unregister recibe el nombre del servicio (o servicios, separados por coma) a eliminar.

Para asignarlos al router se envía el objeto Services a través del método Katya::setServices, a partir de aquí, cada controlador recibirá como tercer argumento la instancia de Services. Un servicio es invocado como si fuera un método más de la clase o bien como si fuera un atributo en contexto de objeto.

Opcionalmente se puede seleccionar que servicios específicamente serán utilizados en determinada ruta o grupo de rutas con Route::useServices el cual recibe los nombres de los servicios registrados previamente, separados por comas.

Para verificar si un servicio existe se usa Services::has (se envía como argumento el nombre del servicio) y Services::names devuelve un array con los nombres de todos los servicios disponibles.

Variables

Asigna variables globales dentro de la aplicación con Katya::setVariables que recibe como parámetro un objeto Variables.

Con Variables::setVar se crea una variable, recibe como parámetros el nombre de la variable y su valor.

Recupera una variable con el método Variables::getVar, recibe como parámetros el nombre de la variable y un valor default en caso de que la variable llamada no exista; este último parámetro es opcional y si no se declara devolverá un valor null por default.

Para verificar si una variable existe se utiliza el método Variables::hasVar que devolverá true si la variable existe o false en caso contrario.

[!NOTE] Todos los nombres de variables son normalizados a minúsculas y son enviadas siempre como último argumento en cada controlador, solo si se han definido y asignado con Katya::setVariables.

DB Connection

La clase DbConnection proporciona el medio para crear una conexión singleton con MySQL a través del driver PDO o la clase mysqli. El método estático DbConnection::getConnection recibe los parámetros de conexión y devuelve un objeto con la conexión creada dependiendo del parámetro driver donde se define si se utilizara por default MySQL con PDO o con mysqli.

Connecting using an URL

Otra alternativa es usar una database URL como parámetro de conexión, a través del método estático DbConnection::dsnParser; este recibe una URL y la procesa para ser enviada a DbConnection::getConnection de la siguiente forma:

Auto connect

El método estático DbConnection::autoConnect realiza una conexión a MySQL tomando automáticamente los parámetros definidos en un archivo .env.

El archivo .env debería verse mas o menos así:

[!NOTE] Se debe usar alguna librería que permita procesar la variables almacenadas en .env y cargarlas en las variables $_ENV. La más usual es vlucas/phpdotenv.

Middleware

El middleware Route::before ejecuta una o varias acciones previas al controlador de una ruta.

Route::before Recibe uno o varios objetos callable (función, método de objeto o método estático) donde se definen las acciones a ejecutar, este objeto a su vez recibe los mismos parámetros que los controladores: obligatoriamente un objeto Request y en orden de prioridad, Services y Variables según hayan sido definidos. Y además recibe como último argumento una función que representa el siguiente middleware en la cadena o, finalmente, el controlador. Para continuar el flujo, el middleware debe invocarse con los mismos argumentos que reciben los controladores. Ej: return $next($request, $services, ...).

Los middlewares de grupo se heredan, pero los definidos en rutas individuales tienen prioridad y no son sobreescritos.

[!NOTE]

• Los middlewares se ejecutan en orden inverso de definición (LIFO) y cada uno debe invocar $next para continuar la cadena.
• Los middlewares de grupo se heredan, pero los definidos en rutas individuales tienen prioridad y no son sobreescritos.
• Si el middleware es una instancia de clase, esta clase debe definir las acciones del propio middlewae en el método __invoke()

CORS

(Cross-Origin Resource Sharing). Esta configuración se define a través de un objeto CorsConfig en el cual se agregan los origenes, los métodos de petición permitidos para cada origen así como los encabezados http aceptados, el tiempo en segundos para la cache de las preflight requests y soporte para credenciales de acceso.

Los métodos y configuración http son opcionales; por default para todos los origenes todos los métodos son aceptados y la configuración default es la siguiente:

Asigna la configuración de CORS con el método Katya::setCors y automaticamente se ejecutará al correr el router:

Environment Management

Environment::register inicializa el ambiente de desarrollo y puede recibir el argumento development o production. Si se invoca sin argumento buscará cargar automáticamente desde la variable APP_ENV del archivo .env; en caso de no encontrarla se tomará por default el modo development.

Environment::setLogPath especifica el directorio (obligatorio) donde se guardará el registro de errores. Todos los errores que ocurran en ambos ambientes de desarrollo se volcarán en un archivo php_errors.log.

Usa Environment::getLogPath para recuperar la ruta completa del archivo de registro de errores.

[!NOTE] La salida en pantalla del registro de errores se muestra en formato JSON para una mejor legibilidad.