Duckbrain - Manual de inicio

Al entrar a la carpeta de Duckbrain encontraras esta estructura de archivos (ignoramos el readme.org porque no es necesario).

.
├── 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:

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 simple y puede que ya lo entiendas gracias al código de configuración de nginx que coloqué antes:

Supongamos que entramos en la ruta /hola (o sea, misitio.com/hola), lo que hará el .htacess o la configuración nginx 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.

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.

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.

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".

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 :).

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.

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.

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.

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

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.

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.

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.