duckbrain-docs/starting-manual.org

Duckbrain - Manual de inicio

• Introducción
  • Estructura de archivos de Duckbrain
    • Carpeta src
    • Carpetas: Controllers, Libs, Models, Middlewares, Views y Routers
    • Los archivos en la raíz
    • Los archivos en la carpeta Libs
  • Comprendiendo el arranque del sistema
  • Extra: Namespaces
• Primeros pasos
  • Usando un Webserver para el desarrollo
  • Hola mundo
    • Explicación del código del hola mundo
• Mi primera aplicación
  • Definición del proyecto
  • Base de datos
    • Configuración de Duckbrain para la base de datos
  • Modelos
  • Creando vistas
  • Mostrando el formulario
    • Extra: Explicación del tipo callable
  • Creando la nota encriptada
  • Recta final: Desencriptando y mostrando las notas
  • Repositorio
• Contacto

Introducción

Duckbrain es un conjunto de librerías creadas especialmente pensando en hacer algo simple, que cualquiera pueda deshacer y rearmar fácilmente.

Gracias a esa versatilidad, puedes usarlo cualquier proyecto, pero por ello debes tener en cuenta que mientras más grande sea el proyecto, mayor será el nivel de ingeniería que se requerirá de tu parte para acondicionar esta herramienta a los requerimientos.

Otro punto fuerte que puedo dar de esta herramienta, es que te puede ser tremendamente útil si estás comenzando, ya que al ser tan pequeño y modificable, es más sencillo que lo comprendas y esto más adelante te ayudará a comprender cosas más grandes.

Estructura de archivos de Duckbrain

Al entrar a la carpeta de Duckbrain encontrarás esta estructura de archivos (ignoramos el readme.org por obvias razones).

.
├── config.php
├── index.php
├── .htaccess
└── src
    ├── Controllers
    ├── Libs
    │   ├── Database.php
    │   ├── Middleware.php
    │   ├── Model.php
    │   ├── Neuron.php
    │   ├── Request.php
    │   ├── Router.php
    │   └── View.php
    ├── Middlewares
    ├── Models
    ├── Routers
    └── Views

Primero veamos las carpetas y luego los archivos:

Carpeta src

En esta carpeta se encuentra todo el código PHP de lo que será nuestro proyecto. Es posible cambiarle el nombre/ruta a gusto, como te darás cuenta más adelante.

Carpetas: Controllers, Libs, Models, Middlewares, Views y Routers

Si sabes de estructuras de diseño, ya te debe quedar claro qué va en cada una de estas carpetas, puesto que en el nombre de las mismas lo indica.

Si no sabes que es un Model, un Middleware, Controller, etc. entonces requieres buscar ahora mismo lo que es una arquitectura de diseño de software y leerte al menos en qué consiste la arquitectura de MVC, ya que es una arquitectura simple y la que usaremos más adelante en este manual. Si lo comprendes, solo sigue leyendo.

Al igual que con la carpeta src, todo lo puedes cambiar y colocar otra estructura de carpetas y las únicas que requerirían algún tipo de edición de archivos serían las carpetas Views y Router que se editarían en el archivo src/Libs/View.php y el archivo index.php respectivamente. Las demás carpetas las puedes borrar cuando quieras y usar otra estructura, pero por lo pronto no lo hagas al menos hasta que hayas pasado la sección Mi primera aplicación que es cuando ya habrías leído y, con algo de suerte y pericia, asimilado los conocimientos necesarios para hacer lo que te de la gana con este ser de librería al punto de que ya le podrás colocar las tuyas propias, le borrarás alguna de las que viene por defecto porque no la necesites o incluso crees una versión extendida de las que viene por defecto para poder añadirle alguna mejora que necesites.

Desde luego, si eres un ansias y ya has programado antes en alguna arquitectura de diseño como DDD, MVC, TDD, EDD, etc. y manejas decentemente PHP, con que te leas el código del archivo index.php (son solo 20 líneas de código) te deberá bastar y puedes saltarte el resto del este manual y guiarte de ahora en adelante con la documentación de los comentarios (docblocks) de las librerías.

Los archivos en la raíz

El .htaccess es un archivo que te será útil si usas apache o algún otro servidor web que use estos archivos. Contiene una configuración especial para que funcionen las rutas virtuales, o sea, para que podamos crear una ruta tipo mitsitio.com/mi-ruta-virtual/ a pesar de que la carpeta mi-ruta-virtual no exista.

En caso de que uses nginx, debes configurar el webserver con la regla equivalente al contenido del archivo .htaccess que sería más o menos esto:

location / {
    try_files $uri $uri/ ./index.php$args;
}

El archivo index.php es el punto de entrada de nuestra aplicación, aquí sucederá toda la magia inicial y sólo requiere de 20 míseras lineas para hacer ese gran trabajo y soportar sistemas tan grandes sin despeinarse ante frameworks más complejos como laravel o que son usados por cientos de miles de usuarios en cientos de instalaciones. Esto lo menciono no por creer que ttps://git.kj2.me/kj/duckbrain][Duckbrain podría soportarlo, sino porque es algo que ya sucede, o sea, dichos sistemas ya existen: Los he hecho yo o he estado involucrado en parte del proyecto al punto de poder elegir Duckbrain como base para el mismo.

El archivo config.php, como su nombre indica, es el archivo para colocar las configuraciones.

Los archivos en la carpeta Libs

Son básicamente librerías, cada una tiene como nombre lo que hace, no tiene mucho misterio y al igual que antes con las carpetas, si sabes algo de diseño, con leer el nombre de las mismas te debería bastar para saber lo que hacen. Si no lo entiendes, sigue leyendo el manual que hablaremos de casi todas poco a poco.

Comprendiendo el arranque del sistema

Como la intención de este manual es que comprendas Duckbrain y no solo seas un robot que copia y pega de la documentación, vamos a calentar comprendiendo el código que lo arranca.

Como ya mencionamos antes, el archivo .htaccess se encarga de hacer funcionar las rutas virtuales, pero eso como programador que eres te debería hacer saltar una pregunta "¿Cómo es que hace eso?" y la respuesta es bastante simple:

Supongamos que entramos en la ruta /hola (o sea, misitio.com/hola), lo que hará el .htaccess será lo siguiente:

Primero intenta comprobar si el fichero "hola" existe en la ruta a la que se desea acceder, si no es el caso prueba si existe una carpeta "hola" y si tampoco sucede eso, reenvía todo a index.php y le pide que él se encargue de ahí en adelante.

Si llega hasta la tercera opción decimos que es una ruta virtual (lo que mencionamos en Los archivos en la raiz), porque devolveremos algo desde el PHP simulando un archivo o una carpeta, a pesar de que esa ruta realmente no existe ni como fichero ni como carpeta.

Ahora veamos que hace index.php, en la primera línea nos dice esto:

require_once('config.php');

Aquí carga el archivo config.php, o sea, carga la configuración. Para esta parte del manual, solo nos interesa las 2 últimas líneas ya que todo lo demás en realidad no está configurando nada aún. Lo que dice las líneas es esto:

define('ROOT_DIR', __DIR__);
define('ROOT_CORE', ROOT_DIR.'/src');

Se está definiendo una constante ROOT_DIR que contiene como valor el directorio en donde está el archivo config.php, que también sería la raíz de Duckbrain. La siguiente línea también es la definición de una constante: ROOT_CORE lo que hace es tener la ruta de la carpeta src. Hasta aquí acabamos con la definición de constantes, ahora el bloque que viene es donde se poner lo bueno:

spl_autoload_register(function ($className) {
    $fp = str_replace('\\','/',$className);
    $name = basename($fp);
    $dir  = dirname($fp);
    $file = ROOT_CORE.'/'.$dir.'/'.$name.'.php';
    if (file_exists($file)) {
        require_once $file;
        return;
    }
});

Este bloque define un autoloader para PHP. Como su nombre lo indica, lo que hace es cargar los archivos en función del su clase, considerando siempre que dichos archivos estarán dentro de la carpeta configurada en ROOT_CORE, que generalmente será src.

Si aún no te ha hecho clic lo bonito que es tener un autoloader como este, básicamente lo que sucede es que en lugar de que a cada archivo que uses lo tengas que cargar usando la función include(), require(), include_once() o require_once(), bastará solo con usar la clase que contiene, siguiendo la convención de que el namespace indica las carpetas y el nombre del archivo tiene el mismo nombre de la clase.

Si aún no lo entendiste, no pierdas tiempo releyendo el párrafo anterior, en seguida lo vamos a retomar y a explicar mejor. Por lo pronto vamos a por el bloque final:

$routers = glob(ROOT_CORE.'/Routers/*.php');

foreach($routers as $file){
    require_once($file);
}

\Libs\Router::apply();

La primera línea de código lista todos los archivos .php dentro de nuestra carpeta src/Routers/, la segunda parte los incluye todos esos archivos PHP, o sea, ejecuta el código PHP que tengan dentro y la última llama a la clase \Lib\Router::apply() y aquí hacemos uso del bloque anterior de la siguiente manera:

Hasta ahora, el único archivo que hemos cargado es el de configuración en la primera línea. La clase \Libs\Router realmente no está definida y en un PHP normal nos daría error por ello, pero aquí viene al rescate nuestro autoloader, ya que el toma la clase y como se llama \Lib\Router comprende que tiene que intentar cargar el archivo en src/Libs/Router.php que es donde vendría a estar la clase que estamos necesitando. Como el archivo existe y la clase está definida allí, es capaz de cargarla y de correr la función estática apply() y así es como todos terminan felices sin dar ningún error :).

Nótese que lo que ha hecho el autoloader es convertir los backslashes o barras invertidas en slashes o barrar normales y luego concatenarlas con ROOT_CORE para obtener la ruta de nuestro archivo. Esto es muy importante, así que si no lo entiendes léelo nuevamente (explicación y código) o pide a algún amigo, conocido o random de internet en algún foro o chat de telegram, matrix, steam, discord, reddit, etc. que te lo explique hasta que comprendas perfectamente ese fracmento de código.

Extra: Namespaces

Si eres nuevo en esto puede que no sepas lo que es un namespace, pero si también te dio curiosidad el que la una clase tenga \ (backslash) en su nombre, entonces tienes futuro en este campo y como no quiero que te vayas de este manual, voy a explicarte rápidamente de donde viene ese backslash.

Si abres el archivo src/Libs/Router.php verás que en su primera línea dice esto:

namespace Libs;

Esa línea generalmente será la primera siempre de un archivo PHP que use namespaces, no puede haber ninguna otra línea de código. Lo que hace dicha línea es darle una "familia" a la clase y con dicha familia, también viene el apellido de la misma.

De modo que cualquier clase que se cree dentro de un archivo con un namespace, de ahora en adelante tendrá como "apellido" ese namespace en su nombre. De ese modo, como en el archivo Router declaramos la clase Router, en realidad estamos creando la clase Libs\Router (el backslash del inicio se puede omitir).

Puede que ahora mismo no notes la utilidad de esto, pero es algo muy útil realmente y ya verás más adelante la magia que supone.

Primeros pasos

Antes de ponernos a programar vamos a asegurarnos de estar en la misma pagina preparando nuestro entorno de trabajo y haciendo el usual Hola mundo.

Usando un Webserver para el desarrollo

Desde luego esta la carpeta con Duckbrain supongo que ya la tienes con un webserver nginx o apache en localhost. Si no es el caso, al menos deberás instalarte PHP primero y una ves instalado, abres una terminal en la carpeta donde tienes Duckbrain y ejecutas:

php -S localhost:80

Eso te creará un webserver que podrás acceder escribiendo en el navegador http://localhost y verás lo que estemos corriendo en el proyecto.

En la terminal, ahora verás los logs de acceso y en caso de que tu código tenga un error, igual aparecerá allí. En el caso de Linux, MAC y FreeBSD los accesos se verán en amarillo para errores no fatales como archivos inexistente y en rojo si es un error fatal que detiene la ejecución de PHP. En Windows no estoy seguro.

He conocido gente que usa directamente un hosting y edita los archivos allí. Eso no está mal si estás aprendiendo o para hacer código rápido, pero en lo personal, siempre recomiendo desarrollar en local, ya que es más rápido y con herramientas como Docker o KVM puedes simular la misma configuración que tendría un servidor en producción, con los retoques que necesites para tu entorno de desarrollo.

Hola mundo

Agarren su teclado y su editor de código que vamos a comenzar a hacer la magia. Como es usual, el primer paso para hacer nuetra aplicación, será imprimir un hello world.

Para ello vamos a la carpeta src/Routers y crearemos un archivo con el nombre de main.php y dentro colocaremos el siguiente código:

<?php
use Libs\Request;
use Libs\Router;

Router::get('/', function(Request $requets) {
    echo "Hola mundo";
});

Ahora, siguiendo con el código, abrimos la URL donde estamos corriendo el sitio (normalmente localhost) y veremos nuestro esperado "hola mundo".

Explicación del código del hola mundo

Si entendiste el código con solo leerlo, perfecto, pero si no lo hiciste, vamos a explicarlo. Primero vamos a explicar esta parte:

Router::get('/', function(Request $requets) {
    echo "Hola mundo";
});

Lo que estámos haciendo aquí, es llamar al método get de la clase Router. La clase, como indica su nombre, maneja las rutas, el método get indica el método HTTP que vamos a configurar (Duckbrain soporta los métodos HTTP: get, post, put, patch y delete).

Los parámetros que recibe la función son 2:

• La ruta que vamos a configurar: En este caso es / que es la raíz de nuestro dominio, o sea, http://localhost/. Prueba ahora mismo cambiar eso a /hola y verás que al refrescar ahora da error 404, pero al entrar en http://localhost/hola nuevamente podrás ver el mensaje Hola mundo.
• Una función anónima: Por lo pronto quédate que en ese segundo parámetro va un elemento callable, en este caso es una función anónima, lo cual entra dentro de las cosas que son callable. Este segúndo parámetro, como se puede deducir con facilidad, es lo que se ejecutará cuando ingresemos a la ruta configurada en el primer parámetro.

La palabra reservada use:

Al igual que en Extra: Namespaces la explicación de las primeras 2 líneas de este código, realmente no es algo de Duckbrain, sino del lenguaje mismo, pero de todos modos lo explicaré.

Primero que nada, si no quisieramos o no tuviéramos la posibilidad de usar use, nuestro código se vería así:

<?php
Libs\Router::get('/', function(Libs\Request $requets) {
    echo "Hola mundo";
});

Puedes probarlo y verás que funciona perfectamente. El problema es que en códigos más largos, con namespaces más largos, sería demasiado tedioso escribir el nombre completo de las clases todo el tiempo, del mismo modo que en la vida real sería tedioso referirnos a las personas siempre por sus nombres completos y en su lugar los llamamos por su nombre de pila o un apodo.

Si un namespace es como dar un apellido, use es como dar un apodo o nombre temporal. Por defecto, ese apodo o nombre local será el nombre de pila de la clase, pero igual podemos definirlo de la siguente manera:

use Libs\Router as Rutercito;

En este caso, estamos usando la plabra reservada as para definir arbitrariamente que el apodo de Libs\Router será, Rutercito. El código ahora entenderá a qué clase nos referimos ya sea que usemos el nombre completo o el apodo Routecito.

Prueba ponerle apodos ambas clases y usar sus distintos nombres en el código. Es importante que siempre que aprendas, pruebes por cuenta propia las cosas, así te aburres menos y es mas fácil que lo comprendas.

Mi primera aplicación

Ya hicimos un hola mundo, ahora vamos a hacer algo completo de verdad. Una buena práctica a la hora de crear proyectos es comenzar a definir lo que vamos a hacer, por lo tanto:

Definición del proyecto

Vamos a hacer un sistema que nos permita compartir textos de manera secreta. Una persona cualquiera podrá entrar a nuestra web, escribir un texto o nota secreta y se le entregará un enlace con el que puede compartir esa nota secreta.

Como medida de seguridad, existirá una llave secreta que se usará para encriptar la nota y dicha llave secreta no se guardará en nuestra base de datos, sino que irá en el enlace que le daremos a la persona a la hora de crear su texto secreto. De modo que las únicas personas capaces de desencriptar ese texto secreto, serán aquellas que tengan ese enlace.

Como extra, la notas tendrán siempre un tiempo de expiración definido por el creador de la nota y/o una cantidad de lecturas máximas, luego de lo cual ya se podrán desencriptar y serán eliminadas de nuestra base de datos si alguien intenta leerlas.

El nombre de la aplicación será Ignota. No soy bueno con los nombres y pensaba que podría llamarla Ignita nota (nota de fuego en latín) e intentando crear un apócope, llegué a una palabra que ya existe en español y además tiene un significado acorde, además de tener la palabra "nota" en el nombre :).

Base de datos

Este sistema no es algo complicado en lo que al diseño de la base de datos se refiere, por lo que sólo vendría a tener una tabla:

|-----------|
| notes     |
|-----------|
| id        |
| content   |
| expire_at |
| max_views |
|-----------|

El código para crear las tablas en SQLite sería este:

CREATE TABLE notes (
    id INTEGER PRIMARY KEY,
    content TEXT,
    expire_at INTEGER,
    max_views INTEGER
);

Duckbrain soporta también MySQL/MariaDB, por lo que si quisieramos usar dicho gestor, el código sería así:

CREATE TABLE notes (
    id BIGINT PRIMARY KEY AUTO_INCREMENT,
    content TEXT,
    expire_at INT default null,
    max_views INT default 0
);

Voy a obviar la parte de cómo crear las bases de datos ya que ambas cosas se pueden encontrar fácil, ya sea preguntando o buscando por cuenta propia. Desde luego, si son muy nuevos, recomiendo que usen SQLite que es la más sencilla de las 2 opciones y por ello también usaremos esa opción de ahora en adelante.

Configuración de Duckbrain para la base de datos

Desde luego, Duckbrain va necesitar tener la información de la base de datos, por lo que abriremos el archivo y veremos algo como esto:

<?php
define('DB_TYPE', 'mysql');
define('DB_HOST', 'localhost');
define('DB_NAME', '');
define('DB_USER', '');
define('DB_PASS', '');

//define('SITE_URL', '');

define('ROOT_DIR', __DIR__);
?>

La primera línea define el tipo de base de datos que vamos a usar, mientras que el resto su información. Ya que estamos, voy a configurar también SITE_URL que en realida no es necesario, pero quiero hacerlo para dar a notar que en caso de configurarlo, es obligatorio que la url en termine en /.

El código terminaría así:

<?php
define('DB_TYPE', 'sqlite');
define('DB_HOST', 'localhost');
define('DB_NAME', 'mi-bd.sqlite');
define('DB_USER', '');
define('DB_PASS', '');

define('SITE_URL', 'http://localhost/');

define('ROOT_DIR', __DIR__);
?>

Como nuestra base de dato es solo un archivo sqlite, no requerimos de DB_HOST, DB_USER ni DB_PASS. Todas esas líneas podemos eliminarlas o dejarlas tal cual, pues no afectarán en nada.

Modelos

Debo hacer incapié en que nada está escrito en piedra y podemos hacer las cosas de muchas manera con Duckbrain, pero en este caso, siguiendo la estructura MVC, vamos a crear modelos, vistas y controladores.

Comenzando con los modelos, que en realidad para este proyecto sería en singular, vamos a crear un archivo llamado Note.php en src/Models con el siguiente contenido:

<?php
namespace Models;

use Libs\Model;

class Note extends Model {
    public string $content;
    public ?int   $expire_at;
    public int    $max_views = 0;
}

En el caso de los modelos que extienden de Libs\Model es necesario poner como públicos los nombres de las variables que queremos que se guarden o traigan de la base de datos. Del mismo modo es importante el nombre de la clase, ya que esta se pasará de PascalCase a snake_case en plural (añadiendo una s al final), para usarlo como tabla, o dicho más simple, como la clase se llama Note, la tabla con la que estará asociada será notes. Si por otro lado la clase se llamara EncriptedNote, la tabla en la base de datos tendría que llamarse encripted_notes.

Repitiendo otra vez lo antes dicho ya muchas veces, nada está escrito en piedra y si quieres usar un nombre de la tabla y no hacer uso de la conversión de nomenclaturas antes mencionada, puedes hacerlo definiendo la propiedad protegida table. Del mismo modo, si quieres tener alguna propiedad privada o protegida en lugar de pública, pero igualmente quieres que se guarde, solo debes definirlo en la propiedad forceSave y si lo que quieres es todo lo contrario (que una propiedad pública no se guarde), entonces podrías hacer uso de la propiedad ignoreSave.

Nada de lo mencionado en el anterior párrafo lo necesitaremos, pero de todos modos aquí tienes un ejemplo de como se vería:

<?php
namespace Models;

use Libs\Model;

class Note extends Model {
    public string    $content;
    public ?int      $expire_at;
    public int       $max_views = 0;
    public string    $tmp_cache;
    private string   $password;
    protected string $salt;

    // Cambiamos el nombre de la tabla a la que se relacionará nuestro modelo.
    static protected string $table = 'se_llama_como_YO_quiero_AAAhh';

    // Forzamos a que se guarden las propiedades salt y password a pesar de que no son públicas.
    static protected array $forceSave = ['password', 'salt'];

    // Frozamos a no guuardar la propiedad pública tmp_cache
    static protected array $ignoreSave = ['tmp_cache'];
}

Nota: En esta ocasión no explicaré qué es lo que hace la palabra reservada extends. Si no comprendes lo que hace, por favor busca y pregunta ya que es algo extremadamente importante de comprender, además de ser algo que se usa en prácticamente todos los lenguajes de programación que soportan clases.

Creando vistas

En este caso solo necesitaremos una sola vista, por ello no crearemos archivos aparte para el código CSS, sino que irá todo en un solo archivo.

Vamos a crear un archivo llamado CreateNote.php en src/Views/ con el siguiente código:

<!DOCTYPE html>
<html>
  <head>
    <meta charset="UTF-8"/>
    <meta name="viewport" content="width=device-width, initial-scale=1.0">
    <title>Ignota - Notas encriptadas punto a punto</title>
    <style>
     form {
       display: grid;
       place-content: center;
       gap: 5px;
       max-height: 100vh;
       min-height: 50vh;
       text-align: center;
     }

     textarea {
       min-width: 80vw;
       max-width: 95vw;
       min-height: 50vh;
     }

     button {
       padding: 5px;
       font-size: 18px;
       cursor: pointer;
     }

     .config {
       display: grid;
       grid-template-columns: auto 100px;
       text-align: left;
       gap: 5px;
       justify-content: center;
     }

     legend {
       font-size: 15px;
       font-weight: bold;
       display: ;
     }
    </style>
  </head>
  <body>
    <form method="POST">
      <textarea name="note" placeholder="Escribe tu texto a encriptar"></textarea>
      <fieldset class="config">
        <legend>Configuración de expiración</legend>
        <label for="max_views">Visualizaciones máximas (0 = infinitas):</label>
        <input name="max_views" type="int" value="0">
        <label for="expiration">Tiempo de expiración (en minutos):</label>
        <input name="expiration" type="int" value="15">
      </fieldset>
      <button type="submit">Guardar</button>
    </form>
  </body>
</html>

No creo que sea necesario que expliquemos un código html, si no lo entiendes, no te quedes con la duda y busca comprenderlo/aprenderlo.

Mostrando el formulario

Ahora no vamos a hacer un archivos completos, los haremos a pedacitos de código a medida que avancemos.

Comenzando con el controlador, vamos a crear un archivo llamado NoteController.php en la carpeta src/Controllers/ y colocaremos dentro este código:

<?php
namespace Controllers;

use Libs\Request;
use Libs\View;

class NoteController {
    public static function home(Request $request): void
    {
        View::render('CreateNote');
    }
}

Aquí lo que hemos hecho ha sido crear una función estática dentro de nuestro controlador, el ejecutará el metodo render, de la librería View (Libs\View) el cual en de manera interna en lo que hace es crear un objeto de tipo View y ejecutar el método html con los mismos argumentos que recibe el método render. Puedes comprobarlo tú mismo leyendo el código de esa librería, es cortito y no muerde.

Luego eso lo que teminará haciendo es buscar un archivo llamado CreateNote.php dentro de src/Views/ y lo cargará, de modo que terminaríamos viendo el formulario que creamos antes.

Sin embargo, aún nos falta un paso para que ese formulario se vea y es configurar la ruta donde se verá. Para hacerlo, vamos a renombrar el archivo main.php que creamos antes y como estas rutas que configuraremos son las rutas de nuestras notas, un buen nombre a usar sería note.php, si luego tuvieramos, usuarios entonces podríamos crear otro archivos llamado user.php y poner allí todas las rutas que sean de usuarios.

Bueno, siguendo a lo que íbamos. Si es que has estado tomando antención, el contenido de este archivo tiene que ser la configuración de una ruta que ejecute la función home que creamos antes en el controlador.

Aquí me doy el lujo de hacer otro paréntesis para hablar del tipo callable de PHP. Esto es un tipo especial, ya que no es una clase realmente, de hecho puede ser un array, una función anónima o un string sin problemas. La única condición es que debe ser algo que puedas llamar como función, de modo que el contenido de nuestro archivo note.php lo podremos poner de una de estas 2 maneras:

<?php
use Libs\Router;

Router::get('/', 'Controllers\NoteController::home');

O de esta otra manera:

<?php
use Controllers\NoteController;
use Libs\Router;

Router::get('/', [NoteController::class, 'home']);

Ambas funcionarán y al entrar en http://localhost ya

Extra: Explicación del tipo callable

Enlos anteriores 2 bloques de código lo que hemos visto han sido 2 maneras de escribir un callable:

En el primer código he escrito el nombre completo hasta la función en un string, mientras que en el segundo hemos hecho lo mismo, pero en forma de array. Ambos funcionan como callables, ya que se podrían ejecutar como función y puedes comprobarlo tú mismo intentando correr el siguiente código:

<?php
use Controllers\NoteController;
use Libs\Request;
use Libs\Router;

Router::get('/', function(){});
[NoteController::class, 'home'](new Request);

O también:

<?php
use Libs\Request;
use Libs\Router;

Router::get('/', function(){});
'Controllers\NoteController::home'(new Request);

Sé que esto es algo raro y que realmente tiene que ver con el conocimiendo de PHP, pero tenía que mencionarlo porque me he topado con gente que usa frameworks como laravel y creen que eso es algo que sucede por "la magia del framework" y es un error.

Creando la nota encriptada

Ahora que ya tenemos el formulario, ya solo nos queda encriptar y guardar nuestra nota. Para ello comenzaremos agregando la siguiente función a nuestro modelo:

public function encrypt(): string
{
    // Generamos una llave aleatoria de entre 12 a 32 caracteres
    $secretKey = substr(
        str_shuffle('0123456789abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ'),
        0,
        mt_rand(16, 32)
    );

    // Encriptamos la nota en AES256 usando la llave antes generada
    $this->content = openssl_encrypt(
        $this->content,
        'AES-256-CBC',
        $secretKey,
        OPENSSL_RAW_DATA,
        substr($secretKey, 0, 16)
    );

    // Devolvemos la llave
    return $secretKey;
}

Con esto podemos encriptar la nota antes de guardarla y nos devolverá una llave aleatoria con la que habrá encriptado el texto.

Ahora vamos a hacer un controlador que recibirá el formulario, encriptará la nota para luego guardarla en la base de datos y finalmente redirigirá al enlace de la nota que llevará en la URL la llave de encriptado, para ello añadiremos esta función a la clase NoteController:

public static function create(Request $request): void
{
    // Creamos una instancia de Note y le pasamos los datos del formulario
    $note            = new Note;
    $note->content   = $request->post->note;
    $note->max_views = $request->post->max_views;
    $note->expire_at = strtotime("+{$request->post->expiration} minutes");

    // Encriptamos los datos y luego los guardamos
    $secretKey = $note->encrypt();
    $note->save();

    // Redirigimos a la url final donde se verá la nota
    Router::redirect("/{$note->id}/{$secretKey}");
}

Desde luego, también tenemos que añadir los uses de Libs\Router y Models\Note:

use Libs\Router;
use Models\Note;

Si te sientes permido y no sabes dónde poner esas 2 líneas, es arriba de la línea que comeniza con class, de hecho ahí verás otras líneas similares.

Para finalizar vamos configurar la ruta. Así que editamos el archivo note.php que está en src/Routers/ y le añadimos:

Router::post('/', [NoteController::class, 'create']);

Esta vez, como la petición viene de un formulario que la enviará mediande el método HTTP POST, al momento de configurar nuestra ruta, en lugar de usar el Router::get que hemos estado usando hasta ahora, usamos Router::post.

Ahora ya podemos comenzar a crear nuestras notas, auque aún no las podremos ver.

Recta final: Desencriptando y mostrando las notas

Vamos directo al grano, editaremos el modelo (src/Models/Note.php) y le añadiremos esta otra función para desencriptar:

public function decrypt(string $secretKey) : void
{
    // Verificamos si la nota ha expirado
    if ($this->expire_at < time()) {
        $this->content = 'La nota se ha destruido por expiración.';
        $this->delete();
        return;
    }

    // Intentamos desencriptar.
    $content = openssl_decrypt(
        $this->content,
        'AES-256-CBC',
        $secretKey,
        OPENSSL_RAW_DATA,
        substr($secretKey, 0, 16)
    );

    // Verificamos si desencriptó correctamente
    if (is_string($content)) {

        // Verificamos si está configurado para infinitas vistas.
        if ($this->max_views == 0) {
            $this->content = $content;
            return;
        }

        // Reducimos el contador de vistas
        $this->max_views = $this->max_views - 1;
        $this->save();

        // Verificamos si el contador de vistas ha llegado a 0.
        if ($this->max_views <= 0) {
            $this->content = 'La nota se ha destruido según su límite de vistas.';
            $this->delete();
            return;
        }

        // Si no ha expirado, solo devolvemos el contenido
        $this->content = $content;
    } else {
        // Si no se pudo desencriptar colocamos un error
        $this->content = 'Llave incorrecta.';
    }

}

Ahora en el NoteController añadiremos esta otra función:

public static function show(Request $request): void
{
    // Verificamos si el ID es un número
    if (!is_numeric($request->params->id)) {
        Router::defaultNotFound();
        return;
    }

    // Obtenemos la nota de la base de datos
    $note = Note::getById($request->params->id);

    // Verificamos si la nota existe
    if (is_null($note))  {
        Router::defaultNotFound();
        return;
    }

    // Desencriptamos la nota
    $note->decrypt($request->params->key);

    // Imprimimos en formato de texto plano el resultado del desencriptado
    $view = new View;
    $view->text($note->content);
}

En este código hay 2 cosas nuevas de Duckbrain que aún no hemos visto:

La primera serían los atributos $request->params->id y $request->params->key que propablemente te preguntes de dónde salen. Pero aún es momento de que te los explique, por lo que ten paciencia que no fatla mucho.

La segunda cosa es el método text de la librería View: Este método lo que hace es imprimir en texto plano lo que le enviemos, dicho de otro modo, en lugar de devolver el usual documento html que suelen cargar todas lás páginas, simulará que estamos abriendo un archivo .txt.

Ahora la cerecita del paste: Vamos a configurar el router, así que editamos nuestro archivo src/Views/note.php y le añadimos la siguiente línea:

Router::get('/{id}/{key}', [NoteController::class, 'show']);

Ahora notarás que esta vez tiene algo singular que no hemos visto antes y es que en la ruta hay textos encerrados entre llaves. Lo que eso quiere decir es que el texto allí puede ser arbitrario y que lo que pongas allí se guardará en una variable y si ya uniste las líneas esas variables luego podremos accederlas mediante $request->params->id y $request->params->key respectivamente (llevan el mismo nombre alfinal por algo).

Por si aún no se entiende, habamos un ejemplo:

Supongamos que entramos mediante la url: http://localhost/52/urE44g4we4r14daFifG entonces el valor de $request->params->id sería 52, mientras que el de $request->params->key sería urE44g4we4r14daFifG.

Si aún no lo entiendes, te recomiendo testearlo cambiando esos valores e imprimiendo los valores de esas variables en el método show de NoteController.

Y con eso ya hemos terminado, ya puedes probar la aplicación, intentar romperla, etc.

Ya puedes comenzar a hacer tus propias aplicaciones, no tienes ninguna idea de qué hacer, te reto a hacer lo siguiente:

Crea una aplicación de gestión tareas (un TODO list), en donde puedas agregar tareas, marcarlas como finalizadas, en espera o canceladas. Si te parece sencillo hasta ahí, añade que el sistema tendrá usuarios que deberán loguearse, cada uno tendrá sus propias listas de tareas que solo ellos pueden ver cuando se loguean.

Repositorio

Por si alguien se perdió o sencillamente quiere ver código, he subido la aplicación ignota en este repositorio:

https://gitlab.com/kj2me/Ignota

Te animo a hacerle un fork, mejorarlo y enviármelo. Los forks que me parezcan interesantes, los colocaré como destacados en el repositorio original para que otros puedan verlos.

Contacto

Como siempre, pueden contactarme mediante el correo webmaster@outcontol.net

También pueden unirse a mi comunidad de discord: https://discord.gg/p7TAAnTJPK

No es una comunidad de programación solamente, pero ahora mismo no existe una de solo Duckbrain.