====== Laravel 9 ======

Framework PHP

  * [[https://laravel.com/|Web oficial]]
  * [[https://laravel.com/docs/9.x|Documentación oficial]]

<WRAP center round important 60%>
Las notas que aquí se recogen están centradas en la versión 9 de Laravel
</WRAP>

===== Índice =====

  * [[informatica:programacion:php:frameworks:laravel:gestion_de_errores|Gestión de errores con Laravel]]
  * [[informatica:programacion:php:frameworks:laravel:bases_de_datos|Trabajando con bases de datos en Laravel]]
  * [[informatica:programacion:php:frameworks:laravel:uso_de_vistas|Trabajando con vistas en Laravel]]
  * [[informatica:programacion:php:frameworks:laravel:rutas|Rutas en Laravel]]
  * [[informatica:programacion:php:frameworks:laravel:formularios|Trabajando con formularios en Laravel]]
  * [[informatica:programacion:php:frameworks:laravel:redirigir_al_usuario|Redirigir al usuario en Laravel]]
  * [[informatica:programacion:php:frameworks:laravel:validacion_de_informacion|Validación de información en Laravel]]
  * [[informatica:programacion:php:frameworks:laravel:sesiones|Sesiones en Laravel]]
  * [[informatica:programacion:php:frameworks:laravel:inyeccion_implicita_de_modelos|Inyección implícita de modelos en Laravel]]
  * [[informatica:programacion:php:frameworks:laravel:creando_componentes_con_artisan|Creando componentes con Artisan en Laravel]]
  * [[informatica:programacion:php:frameworks:laravel:relaciones_entre_modelos|Relaciones entre modelos]]
  * [[informatica:programacion:php:frameworks:laravel:seeder|Seeder]]
  * [[informatica:programacion:php:frameworks:laravel:programacion_de_tareas|Programación de tareas en Laravel]]
  * [[informatica:programacion:php:frameworks:laravel:comandos|Comandos en Laravel]]
===== Requisitos =====

Para que Laravel funcione correctamente, el servidor web que lo correrá debe tener la siguiente versión de PHP y extensiones:

  * PHP >= 8.0
  * BCMath PHP Extension
  * Ctype PHP Extension
  * cURL PHP Extension
  * DOM PHP Extension
  * Fileinfo PHP Extension
  * JSON PHP Extension
  * Mbstring PHP Extension
  * OpenSSL PHP Extension
  * PCRE PHP Extension
  * PDO PHP Extension
  * Tokenizer PHP Extension
  * XML PHP Extension



===== Instalación =====

<WRAP center round important 60%>
Laravel utiliza [[https://getcomposer.org/|Composer]] para gestionar sus dependencias, así que es necesario que Composer esté instalado previamente.
</WRAP>


Descargamos el instalador de Laravel:

<code>
composer global require laravel/installer
</code>

Para crear un proyecto Laravel:

<code>
laravel new nombre-proyecto
</code>

Esto descargará los archivos necesarios y los guardará en el directorio desde el que ejecutemos el comando.

==== Sail ====

Si estamos en Linux y tenemos Docker instalado, Laravel proporciona una herramienta llamada **Sail** que permite crear un entorno de ejecución para Laravel:

<code>
curl -s https://laravel.build/example-app | bash
</code>

Podemos sustituir ''example-app'' por el nombre que queramos (será el directorio donde descargará Laravel).

Entramos en el directorio y ejecutamos:

<code>
./vendor/bin/sail up
</code>

[[https://laravel.com/docs/8.x/sail|Sail]] es una aplicación para usar Laravel con Docker de forma sencilla:

  * Servidor web en puerto 80
  * Servidor Redis en puerto 6379
  * Mailhog en puerto 1025 y 8025 (dashboard)
  * Servidor MySQL en puerto 3306
  * Meilisearch en puerto 7700
  * Selenium 


==== Docker ====



==== Composer ====

Si tenemos PHP y Composer instalados, podemos crear un proyecto Laravel con Composer:

<code>
composer create-project laravel/laravel example-app
</code>

Entramos en el directorio recién creado:

<code>
cd example-app
</code>

Arrancamos el servidor de desarrollo de Laravel:

<code>
php artisan serve
</code>

Tendremos disponible la aplicación desde http://localhost:8000

===== Estructura de directorios =====

Al crear un proyecto Laravel, se crearán los siguientes directorios:

  * ''app/'': código de la aplicación. Modelos, controladores, comandos y el código personalizado.
  * ''bootstrap/'': ficheros que Laravel necesita cada vez que se ejecuta.
  * ''database/'':  contiene las migraciones de base de datos (//migrations//), //model factories// y //seeds//. También se puede almacenar en él una base de datos SQLite.
  * ''config/'': ficheros de configuración.
  * ''lang/'': ficheros de idiomas.
  * ''public/'': directorio al que apunta el servidor web cuando sirve la aplicación. Contiene index.php, que es el //front-controller//. También contiene todo lo que se sirve públicamente como imágenes, hojas de estilo, scripts de JavaScript...
  * ''resources/''
  * ''routes/'': contiene la definición de las rutas del proyecto
  * ''storage/'': contiene logs, caché y otros ficheros generados por Laravel.
  * ''tests/'': contiene tests automatizados.
  * ''vendor/'': contiene las dependencias de Composer.

<WRAP center round important 60%>
La carpeta ''app/Models'' se incluyó por primera vez en la versión 8
</WRAP>

  * ''composer.json'' dependencias requeridas por nuestro proyecto.
  * En el fichero ''.env'' se definen las variables de entorno (este fichero debe figurar en el ''.gitignore'' para que no salga de nuestro entorno local).

==== Ejecución de Laravel ====

Todo inicia con un archivo ''index.php''. En Laravel, todo lo que sea público, es decir, todo lo que se pueda acceder desde una petición desde un navegador web, está en la carpeta ''public''. Ahí encontraremos el archivo ''index.php''.

En este fichero se controla el tiempo de ejecución del script, se cargan automáticamente las definiciones de las clases que instalamos por medio de Composer (dentro de la carpeta ''vendor'') y se carga el "kernel" que es el que recibe la petición del usuario / navegador, la gestiona y envía la respuesta asociada. El kernel está en el fichero ''app/Http/Kernel.php''. A su vez, hereda de ''vendor/laravel/framework/src/Illuminate/Foundation/Http/Kernel.php''.

En el kernel se inicia el enrutador (router) que es el encargado de enviar la petición hacia las rutas.

Las rutas se encuentran en ''routes/''. Lo normal es que trabajemos con el fichero ''web.php''.

La ruta que hay en ''web.php'' gestiona la vista principal. Las vistas están en ''resources/views/''. Los ficheros con las vistas siguen la nomenclatura ''nombre_vista.blade.php''. Las vistas contienen el HTML, lo que devuelve Laravel al navegador web.


===== Configuración =====

==== Servidor web ====

Configurar el servidor web para que sirva desde la carpeta ''public''. Por ejemplo, en el caso de Nginx:

<code>
server {

    server_name localhost;
  
    index index.php index.html;
    root /var/www/html/mi-proyecto/public;

(...)
</code>

==== Permisos ====

El servidor web debe poder escribir en los directorios ''storage'' y ''bootstrap/cache''

==== Configuración de variables de entorno ====

En un proyecto de Laravel tendremos dos ficheros:

  * ''.env'': contiene las variables de entorno que usa Laravel. No se debe publicar.
  * ''.env.example'': es el que sí compartiremos porque es la base de la configuración de las variables de entorno.

<code>
APP_NAME=Laravel
APP_ENV=local
APP_KEY=
APP_DEBUG=true
APP_URL=http://localhost
...
</code>

Por ejemplo, en ''/config/app.php'' se cargan algunas variables de entorno como ''APP_NAME'' , ''APP_ENV''...


===== Migraciones =====

Creación del esquema de las tablas..

===== Modelos =====

''app/Models''

Podemos crear un modelo apoyándonos en ''artisan'':

<code>
php artisan make:model Usuario --migration
</code>

Esto creará la clase ''Usuario'' en ''app/Models/Usuario.php'' con el código:

<code php>
<?php

namespace App\Models;

use Illuminate\Database\Eloquent\Factories\HasFactory;
use Illuminate\Database\Eloquent\Model;

class Usuario extends Model
{
    use HasFactory;
}

</code>

Además, como hemos indicado que queremos generar una migración de la base de datos, también tendremos un fichero ''AAAA_MM_DD_HHMMSS_create_usuarios_table'' en ''database/migrations/'' con el código:

<code php>
<?php

use Illuminate\Database\Migrations\Migration;
use Illuminate\Database\Schema\Blueprint;
use Illuminate\Support\Facades\Schema;

class CreateUsuariosTable extends Migration
{
    /**
     * Run the migrations.
     *
     * @return void
     */
    public function up()
    {
        Schema::create('usuarios', function (Blueprint $table) {
            $table->id();
            $table->timestamps();
        });
    }

    /**
     * Reverse the migrations.
     *
     * @return void
     */
    public function down()
    {
        Schema::dropIfExists('usuarios');
    }
}

</code>
===== Controladores =====

Laravel se basa en un patrón de diseño llamado **MVC**, de **Modelo-Vista-Controlador**. Centrándonos en aplicaciones web, mantiene separado el código PHP del HTML.

{{ :informatica:programacion:mvc-programming.jpg?nolink |}}

Un controlador se encarga de manejar la lógica del negocio (crear, actualizar, mostrar, eliminar, realizar filtrados, etc).

Los controladores se ubican en ''app/Http/Controllers''

Para crear un nuevo controlador, podemos hacerlo desde cero o utilizar **Artisan**:

<code php>
php artisan make:controller ProductController
</code>

Esto creará un fichero llamado ''ProductController.php'' en ''app/Http/Controllers/'' con el siguiente contenido rellenado por Laravel:

<code php>
<?php

namespace App\Http\Controllers;

use Illuminate\Http\Request;

class ProductController extends Controller {

}
</code>

Vamos añadiendo acciones (métodos) al controlador:

<code php>
    // ....
    public function index() 
    {
        return "This is the list of products";
    }
</code>


Podemos relacionar las rutas con los controladores, en lugar de tener [[https://www.php.net/manual/es/functions.anonymous.php|funciones anónimas]]:

<code php>
Route::get("products", "ProductController@index")->name("products.index");
</code>

Hemos asociado la ruta ''/products'' con la acción ''index'' del controlador ''ProductController''.

Haríamos el resto de acciones:

<code php>
    // ...
    public function create() 
    {
        return "This is the form to create a product from controller";
    }
    
    public function store() 
    {
        return "Product stored";
    }
    
    public function show($product) 
    {
        return "Showing the product with ID {$product}";
    }
    
    public function edit($product) 
    {
        return "Showing the form to edit the product with id {$product}";
    }
    
    public function update($product) 
    {
    // ...
    }

    public function destroy($product) 
    {
    // ...
    }
</code>

===== Vistas =====

No es práctico devolver cadenas con el HTML directamente desde las rutas o controladores. Las **vistas** proporcionan una forma conveniente de organizar todo el HTML en ficheros separados. Las vistas separan el controlador / lógica de la aplicación de su presentación.

Se almacenan en ''resources/views/''

Si, por organización, creamos las vistas en otros directorios dentro del "oficial", para hacer referencia a ellas: 

<code php>
// ...
    return view('users.profile', $data);
</code>

Con esto indicamos que queremos el fichero ''profile.blade.app'' que está en ''resources/views/users/''

El nombre de los ficheros con las vistas deben terminar en ''.blade.php''.

  * [[https://laravel.com/docs/10.x/views|Laravel Views]]

==== Creación de vistas ====

Los ficheros con las vistas se almacenan en ''resources/views/''. Podemos crear directorios dentro de ese directorio para organizar mejor nuestros ficheros. Por ejemplo ''resources/views/products/index.blade.php''.

<code html>
<!DOCTYPE html>
<html lang="es">
    <head>
        <meta charset="utf-8">
        <title>Título</title>
    </head>
    <body>
        <h1>Listado de productos</h1>
        
        <div class="table-responsive">
            <table class="table table-striped">
                <thead class="thead-light">
                    <tr>
                        <th>ID</th>
                        <th>Title</th>
                        <th>Description</th>
                    </tr>
                </thead>
                <tbody>
                    <tr>
                        <td>1</td>
                        <td>Soap</td>
                        <td>Best soap ever</td>
                    </tr>
                    <tr>
                        <td>2</td>
                        <td>Shampoo</td>
                        <td>Best shampoo ever</td>
                    </tr>
                </tbody>
            </table>
        <div>
    </body>
</html>
</code>


==== Llamando a las vistas ====

Tanto desde un controlador como desde una ruta, podemos llamar a las vistas mediante el helper ''view'':

<code php>
Route::get("/", function() {
    return view("welcome");
})->name("main");
</code>

En caso de un controlador:

<code php>
    // ...
    public function index() 
    {
        return view("index");
    }
</code>

Si la vista ''index.blade.php'' está dentro de una carpeta llamada "products":

<code php>
    // ...
    public function index() 
    {
        return view("products.index");
    }
</code>

==== Motor de plantillas Blade ====

===== Identificación y gestión de errores =====

Laravel utiliza un componente llamando **[[https://github.com/spatie/laravel-ignition|Ignition]]**, una página de error para aplicaciones Laravel.

Además de ver el error, podremos ver la traza hasta llegar a dicho error.

<WRAP center round info 60%>
Las excepciones son controladas desde ''app/Exceptions/Handler.php''.
</WRAP>

==== Depurando con Laravel ====

Hay un par de //helpers// que nos ayudan a la hora de depurar errores en Laravel:

  * ''dd()'': //dump and die//, muestra la información y detiene el script.
  * ''dump()'': muestra la información, pero no detiene el script.

Por ejemplo, queremos saber el valor de cierta variable sin detener el script:

<code>
dump($variable);
</code>

===== Hecho con Laravel =====

Proyectos open source hechos con este framework:

  * [[https://github.com/firefly-iii/firefly-iii|Firefly III]]: gestor de finanzas personales
  * [[https://github.com/monicahq/monica|Monica]]: Gestor de relaciones personales.
  * [[https://github.com/snipe/snipe-it|Snipe-IT]]: Gestor de recursos y licencias TI
  * https://gist.github.com/msurguy/8590765
  * [[https://github.com/fgitpush/Top-Laravel-Interview-Questions-Wiki|Top Laravel Interview Questions & Answers]]

===== Artisan =====

Interfaz en línea de comandos incluida en Laravel.

Podremos ver todos los comandos que admite Artisan y una breve descripción de cada uno mediante:

<code>
php artisan
</code>

Borrar caché (por si hemos hecho muchos cambios y tenemos algún problema):

<code>
php artisan optimize:clear
</code>

Los comandos de Artisan que más usaremos serán los relacionados con migraciones de la base de datos y creación de componentes.

==== Servidor web de desarrollo ====

<code>
php artisan serve
</code>

Si queremos poner la aplicación en modo mantenimiento:

<code>
php artisan down
</code>

Esto hará que Laravel devuelva un error 503. Útil si queremos hacer modificaciones y evitar que los usuarios se muevan por donde no deben

Si queremos "reactivarla" o sacarla del modo de mantenimiento:

<code>
php artisan up
</code>

==== tinker: Interactuar con nuestra aplicación ====

Tinker es una consola de comandos con la que podremos interactuar con todas las clases y métodos de nuestra aplicación, una herramienta muy útil a la hora de realizar pruebas de funcionamiento.

<code>
php artisan tinker
</code>

A partir de ahí se abrirá una shell donde podremos ejecutar código PHP y funciones de Laravel. Por ejemplo, podemos usar los //[[https://laravel.com/docs/10.x/helpers|helpers]]// de Laravel:

<code>
>>> \Str::plural('apple');
=> "people"
>>> \Str::random(5);
=> "IgRFW"
</code>

==== Generar variables de entorno ====

Si necesitamos generar la variable ''APP_KEY'':

<code>
php artisan key:generate
</code>

Artisan añadirá al fichero ''.env'' la variable ''APP_KEY'' con un valor.


===== Ecosistema Laravel =====

  * [[https://laravel-mix.com/|Laravel Mix]]: gestión de dependencias para front-end, los assets (JavaScript y CSS). Necesita [[https://nodejs.org/en|Node.js]].

===== Entorno de desarrollo =====

==== Servidor web ====

Para simplificar, se puede usar un pequeño servidor que viene con Laravel:

<code>
php artisan serve
</code>

==== IDE o editor de código ====

Recomendación de plugins para el editor Sublime Text 3:

  * Package Control: Necesario para instalar plugins o paquetes
  * AdvancedNewFile: Para crear nuevos archivos fácilmente
  * Blade Snippets: Para usar instrucciones de Blade en las vistas
  * Bootstrap 4x Autocomplete: Sugerir componentes de Bootstrap 4 en las vistas
  * DocBlockr: Crear bloques de comentarios fácilmente
  * Emmet: Autocompletar etiquetas de HTML
  * Laravel Blade AutoComplete: Autocomplete estructuras comunes en las vistas de Blade
  * Laravel Blade Highlighter: Resalta el código con colores adecuados en las vistas
  * Laravel Helper Completions: Sugerir el uso de helpers comunes en el código
  * PHP Companion: Útil para importar definiciones de clases
  * phpfmt: Útil para corregir el estilo del código PHP
  * SideBarEnhacements: Para agregar opciones adicionales en la barra lateral
  * SublimeCodeIntel: Para explorar y abrir fácilmente definiciones de clases y métodos en el proyecto
  * SublimeLinter: Útil para detectar errores de sintaxis en el código
  * SublimeLinter-php: El linter propio para detectar errores en código PHP
===== Recursos =====

  * [[https://github.com/chiraggude/awesome-laravel|Awesome Laravel]]: A curated list of awesome bookmarks, packages, tutorials, videos and other cool resources from the Laravel ecosystem.
  * [[https://laravel.com/docs/10.x|Documentación de Laravel]]