kj/duckbrain-docs
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

first commit

Browse Source
This commit is contained in:
KJ 2024-05-13 00:50:47 -04:00
commit 18200dfa38
2 changed files with 2056 additions and 0 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

1335
starting-manual.html Normal file
View File

File diff suppressed because one or more lines are too long

721
starting-manual.org Normal file
View File

@ -0,0 +1,721 @@
#+TITLE: Duckbrain - Manual de inicio
#+AUTHOR: KJ
#+OPTIONS:
#+SETUPFILE: ./readtheorg_inline.theme
* Introducción
Duckbrain es un conjunto de librerías creadas especialmente pensando en hacer algo simple, que cuarquiera pueda deshacer y rearmar fácilmente. Gracias a esa versatilidad, puedes usarlo cualquier proyecto, peo 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.
Ducho eso, vamos a comenzar...
** Estructura de archivos de duckbrain
Al entrar a la carpeta de duckbrain encontraras esta estructura de archivos (ignoramos el readme.org porque no es necesario).
#+begin_src ditaa
.
├── 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
#+end_src
Primero veamos las carpetas y luego los archivos:
*** Carpeta src
En esta carpeta se encuentra todo el código PHP.
Como todo en Duckbrain, esta ruta se puede cambiar editando una variable en el archivo =index.php=.
*** Carpetas: Controllers, Libs, Models, Middlewares, Views y Routers
Si sabes de estructuras de diseño, el nombre de estas carpetas ya te debe quedar claro qué va en cada una de ellas, puesto que en el nombre de la carpeta dice lo que va a ir dentro.
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.
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 sabes lo que son las arquitecturas de diseño, ya has programado en alguna arquitectura de diseño como DDD, MVC, TDD, EDD, etc. antes y sabes PHP, con que te leas el código del archivo =index.php= (son solo 20 líneas de código) y tengas el nivel de PHP para entenderlo y programar en la arquitectura de diseño que desees, entonces con ver esas 20 líneas te deberá bastar y puedes saltarte el resto del este manual y guiarte de ahora en adelante con la documentación API de las librerías o directamente con el LSP de tu editor de código para poco que queda.
Para el resto de mortales y gente con menos arrogancia, pueden seguir un ratito más por aquí :P.
*** 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 y lo que lleva es una configuración especial para que funcionen las *rutas virtuales*, o sea, para que podamos crear una ruta tipo =mitsitio.com/mi-ruta-virtual/= y podamos decir que allí muestre un mensaje de ~Hola mundo~, a pesar de que la carpeta =mi-ruta-virtual= no exista, ni haya dentro ningún archivo index que tenga el texto ~Hola mundo~. Si esta aún no lo entendiste, no exasperes que ya lo vas a entender en un momento y ahí podrás volver a repasar esta parte.
En caso de que uses nginx, debes configurar el webserver con la regla equivalente al contenido del archivo =.htacess= que sería más o menos esto:
#+begin_src nginx
location / {
try_files $uri $uri/ ./index.php$args;
}
#+end_src
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 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 arranca Duckbrain.
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 raíz][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:
#+begin_src php
require_once('config.php');
#+end_src
Aquí carga el archivo =config.php=, o sea, carga la configuración. Para esta parte del manual, solo nos interesa la última línea ya que todo lo demás en realidad no está configurando nada aún. Lo que dice la línea es esto:
#+begin_src php
define('ROOT_DIR', __DIR__);
#+end_src
Solo 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:
#+begin_src php
define('ROOT_CORE', ROOT_DIR.'/src');
#+end_src
Esta constante =ROOT_CORE= lo que hace es tener la ruta de src. Hasta aquí acabamos con la definición de constantes, ahora el bloque que viene es donde se poner lo bueno:
#+begin_src php
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;
}
});
#+end_src
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:
#+begin_src php
$routers = glob(ROOT_CORE.'/Routers/*.php');
foreach($routers as $file){
require_once($file);
}
\Libs\Router::apply();
#+end_src
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:
#+begin_src php
namespace Libs;
#+end_src
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:
#+begin_src bash
php -S localhost:80
#+end_src
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:
#+begin_src php
<?php
use Libs\Request;
use Libs\Router;
Router::get('/', function(Request $requets) {
echo "Hola mundo";
});
#+end_src
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:
#+begin_src php
Router::get('/', function(Request $requets) {
echo "Hola mundo";
});
#+end_src
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 [[https://es.wikipedia.org/wiki/Protocolo_de_transferencia_de_hipertexto#M%C3%A9todos_de_petici%C3%B3n][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][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í:
#+begin_src php
<?php
Libs\Router::get('/', function(Libs\Request $requets) {
echo "Hola mundo";
});
#+end_src
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:
#+begin_src php
use Libs\Router as Rutercito;
#+end_src
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:
#+begin_src plantuml
|-----------|
| notes |
|-----------|
| id |
| content |
| expire_at |
| max_views |
|-----------|
#+end_src
El código para crear las tablas en SQLite sería este:
#+begin_src sqlite
CREATE TABLE notes (
id INTEGER PRIMARY KEY,
content TEXT,
expire_at INTEGER,
max_views INTEGER
);
#+end_src
Duckbrain soporta también MySQL/MariaDB, por lo que si quisieramos usar dicho gestor, el código sería así:
#+begin_src sql
CREATE TABLE notes (
id BIGINT PRIMARY KEY AUTO_INCREMENT,
content TEXT,
expire_at INT default null,
max_views INT default 0
);
#+end_src
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:
#+begin_src php
<?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__);
?>
#+end_src
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í:
#+begin_src php
<?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__);
?>
#+end_src
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:
#+begin_src php
<?php
namespace Models;
use Libs\Model;
class Note extends Model {
public string $content;
public ?int $expire_at;
public int $max_views = 0;
}
#+end_src
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:
#+begin_src php
<?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'];
}
#+end_src
*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:
#+begin_src html
<!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>
#+end_src
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:
#+begin_src php
<?php
namespace Controllers;
use Libs\Request;
use Libs\View;
class NoteController {
public static function home(Request $request): void
{
View::render('CreateNote');
}
}
#+end_src
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:
#+begin_src php
<?php
use Libs\Router;
Router::get('/', 'Controllers\NoteController::home');
#+end_src
O de esta otra manera:
#+begin_src php
<?php
use Controllers\NoteController;
use Libs\Router;
Router::get('/', [NoteController::class, 'home']);
#+end_src
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:
#+begin_src php
<?php
use Controllers\NoteController;
use Libs\Request;
use Libs\Router;
Router::get('/', function(){});
[NoteController::class, 'home'](new Request);
#+end_src
O también:
#+begin_src php
<?php
use Libs\Request;
use Libs\Router;
Router::get('/', function(){});
'Controllers\NoteController::home'(new Request);
#+end_src
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:
#+begin_src php
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;
}
#+end_src
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=:
#+begin_src php
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}");
}
#+end_src
Desde luego, también tenemos que añadir los uses de =Libs\Router= y =Models\Note=:
#+begin_src php
use Libs\Router;
use Models\Note;
#+end_src
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:
#+begin_src php
Router::post('/', [NoteController::class, 'create']);
#+end_src
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:
#+begin_src php
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.';
}
}
#+end_src
Ahora en el =NoteController= añadiremos esta otra función:
#+begin_src php
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);
}
#+end_src
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:
#+begin_src php
Router::get('/{id}/{key}', [NoteController::class, 'show']);
#+end_src
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:
[URL faltante]
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.