====== Trabajando con bases de datos en Laravel ======

[[informatica:programacion:php:frameworks:laravel|Laravel]]

<WRAP center round info 60%>
A partir de la versión 11, cada proyecto nuevo de Laravel está configurado para trabajar con una base de datos SQLite.
</WRAP>

===== Conexiones soportadas =====

Laravel soporta por defecto los siguientes motores de bases de datos:

  * MariaDB
  * MySQL
  * PostgreSQL
  * SQLite
  * SQL Server

<WRAP center round info 60%>
En el fichero ''config/database.php'' podemos ver los diferentes tipos de conexiones con bases de datos.
</WRAP>

===== Conexión con bases de datos =====

==== SQLite ====

Fichero ''.env'':

<code>
// ...
DB_CONNECTION=sqlite
#DB_HOST=
#DB_PORT=
#DB_DATABASE=
#DB_USERNAME=
#DB_PASSWORD=
</code>

Laravel, por defecto, asumirá que usaremos un fichero llamado ''database.sqlite'' que se almacenará en ''database/''. En ese directorio crearemos el archivo.

==== MySQL ====

Una vez creada la base de datos MySQL, vamos a ''config/database.php''. En cierto punto veremos que la conexión por defecto es a SQLite:

<code php>
    'default' => env('DB_CONNECTION', 'sqlite'),
</code>

La variable que vamos a cambiar, ''DB_CONNECTION'' está en el archivo ''.env'', en la raíz del proyecto. Hacemos los siguientes cambios:

<code>
DB_CONNECTION=mysql
DB_HOST=127.0.0.1
DB_PORT=3306
DB_DATABASE=blog
DB_USERNAME=root
DB_PASSWORD=
</code>

Probaremos si la conexión es exitosa ejecutando unas migraciones:

<code>
php artisan migrate
</code>

Revisamos que se hayan creado nuevas tablas en nuestra base de datos de MySQL.
===== Migraciones =====

Son clases a partir de las cuales podemos crear o modificar tablas en la base de datos.

Si vamos a la carpeta ''database/migrations'' veremos 3 ficheros de migraciones:

  * ''database/migrations/xxxx_create_users_table.php''
  * ''database/migrations/xxxx_create_cache_table.php''
  * ''database/migrations/xxxx_create_jobs_table.php''

Esas migraciones son las responsables de crear tablas. Por ejemplo, el fichero ''xxxx_create_users_table.php'' crearía las siguientes tablas:

  * ''users''
  * ''password_reset_tokens''
  * ''sesions''

==== Ejecutar migraciones ====

<code bash>
php artisan migrate
</code>

<WRAP center round info 60%>
Si ejecutamos migraciones de nuevo (sin haberlas borrado), Laravel no hará nada porque sabe que se ejecutó anteriormente porque mantiene una tabla llamada **migrations** con esa información.
</WRAP>

==== Deshacer migraciones ====

<code bash>
php artisan migrate:rollback
</code>

Ese comando ejecutará el método ''down()'' de cada uno de los ficheros de migraciones para eliminar todas las tablas.
==== Crear migración ====

Para crear una migración que nos permita crear una tabla de productos:

<code>
php artisan make:migration create_posts_table
</code>

Esto habrá creado una migración, una clase anónima con los métodos ''up'' y ''down'':

<code php>
    // ...
    public function up(): void 
    {
        Schema::create('posts', function (Blueprint $table) {
            $table->id();
            $table->timestamps();
        });
    }
    
    public function down(): void 
    {
        Schema::dropIfExists('posts');
    }    
</code>

La completamos a nuestro gusto:

<code php>

    // ...
    public function up(): void 
    {
        Schema::create('posts', function (Blueprint $table) {
            $table->id();
            $table->string('title');
            $table->longText('content');
            $table->timestamps();
        });
    }

</code>

<WRAP center round info 60%>
''$table->timestamps()'' creará los campos ''created_at'' y ''updated_at''.
</WRAP>

Para ejecutar las migraciones:

<code>
php artisan migrate:fresh
</code>

<WRAP center round important 60%>
El modificador ''fresh'' **elimina todo de la base de datos**. Es útil mientras desarrollamos, pero no deberíamos hacer eso nunca en producción. Si usamos el modificador ''rollback'', solo borrará las migraciones del último lote (campo ''batch'' de la tabla **migrations**).
</WRAP>

<WRAP center round tip 60%>
Existe el modificador ''refresh'' que no eliminaría las tablas creadas sin usar ''php artisan''
</WRAP>


Si tuviéramos un método para insertar datos:

<code>
php artisan migrate:fresh --seed
</code>

==== Modificar tablas ====

Si hacemos cambios en las tablas gestionadas por las migraciones, lo ideal es crear una nueva migración:

<code bash>
php artisan make:migration add_avatar_to_users_table
</code>

Esto creará un nuevo fichero de migración:

<code php>
// ...
    public function up(): void
    {
        Schema::table('users', function (Blueprint $table) {
        });
    }
    
    public function down(): void
    {
        Schema::table('users', function (Blueprint $table) {
        });
    }    
</code>

Y ahora lo modificaremos para añadir y quitar el campo:

<code php>
// ...

    /**
    * Run the migrations
    */

    public function up(): void
    {
        Schema::table('users', function (Blueprint $table) {
            $table->string('avatar')->nullable()->after('name'); 
            // Para que se añada el campo después del campo 'name', usamos el método 'after'
        });
    }
    
    /**
    * Reverse the migrations
    */
    public function up(): void
    {
        Schema::table('users', function (Blueprint $table) {
            $table->dropColumn('avatar');
        });
    }    
</code>

Ya podríamos usar el comando:

<code bash>
php artisan migrate
</code>
===== Eloquent =====

Eloquent es el ORM de Laravel. Un ORM (//Object-Relational Mapping//) se encarga de "mapear" / asociar la base de datos con estructuras de modelos que tengamos en nuestro sistema. El propósito es poder interactura con la base de datos como si fueran objetos dentro de la Programación Orientada a Objetos.

===== Modelos =====

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

En Laravel, los modelos y las tablas están estrechamente relacionados. Los modelos son el mecanismo de conexión entre nuestro código y la estructura de tablas y base de datos.

Un modelo es una clase y contiene la funcionalidad de los campos de la tabla a la que representa.

Hay varios tipos de atributos:

  * ''$fillable'': atributos que se pueden asignar de manera masiva.
  * ''$hidden'': atributos que se ocultarán al recuperar información desde la base de datos. 
  * ''$casts'': atributos que deben ser transformados a cierto tipo de dato.

Por defecto, Laravel toma como nombre de la tabla el nombre del modelo, pero en plural, es decir, si tenemos un modelo **User**, Laravel asumirá que la tabla será **users**.

Si no queremos seguir esa convención, añadiríamos al modelo el atributo ''$table'' asignándole como valor el nombre de la tabla.

<WRAP center round info 60%>
La clase ''Model.php'', que es de la que heredan los modelos que creamos, está en ''vendor/laravel/framework/src/Illuminate/Database/Eloquent/''.
</WRAP>

==== Creación de un modelo ====

Nos ayudamos de Artisan:

<code>
php artisan make:model Post
</code>

Esto habrá creado el modelo ''Post.php'' en ''app/Models/'':

<code php>
namespace App\Models;

use Illuminate\Database\Eloquent\Model;

class Post extends Model 
{

}
</code>

Debemos indicarle qué tabla va a administrar:

<code php>
// ...
class Post extends Model 
{
    protected $table = 'posts';
}
</code>

<WRAP center round info 60%>
Si la tabla se llama igual que la clase, pero en plural, no sería necesario crear la variable ''$table'' con el nombre de la tabla. Hay que tener en cuenta que Eloquent usa el inglés, hay que tenerlo en cuenta para que funcionen estas convenciones. Por ejemplo, si tenemos una tabla llamada "voces" y el modelo ''Voz'', Eloquent esperará encontrarse una tabla llamada ''vozs''.
</WRAP>

==== Añadir registros ====

Si queremos añadir un registro:

<code php>
$post = new Post;

$post->title = "Título de prueba";
$post->content = "Contenido de prueba";

$post->save();
</code>

==== Editar registro ====

Si queremos editar un registro:

<code php>
$post = Post::find(1); // Recuperamos el registro con ID 1

$post->title = "Nuevo título de prueba";

$post->save();
</code>

Podemos listar todos los posts atendiendo a cierto criterio:

<code php>
$post = Post::orderBy('id', 'asc')
             ->select('id', 'title)
             ->take(2) // Limítalo a 2 registros
             ->get();
return $post;
</code>

==== Eliminar registro ====

Para eliminar un registro:

<code php>
$post = Post::find(1); // Recuperamos el registro con ID 1

$post->delete();
</code>

==== Mutadores y accesores ====

Imaginemos que queremos que antes de meterse un valor en un campo, queremos tratarlo. Y también queremos tratarlo a la hora de recuperarlo. Para eso están los "mutadores" y "accesores". 

En el modelo que gestiona la tabla que tiene el campo que nos interesa, crearemos una función con el nombre del campo en cuestión:

<code php>
// ...
Use Illuminate\Database\Eloquent\Casts\Attribute;

class Post extends Model 
{
    protected function title(): Attribute
    {
        return Attribute::make(
            set: function($value) {
                return strtolower($value);
            },
            get: function($value) {
                return ucfirst($value);
            }
        );
    }
}
</code>

Con el código anterior, cuando se vaya a introducir un valor al campo ''title'', se transformará antes a minúscula. Cuando vayamos a coger el valor del campo, se mostrará la primera letra en mayúscula.

==== Casting ====

Atributos de fecha con [[https://github.com/briannesbitt/Carbon|Carbon]] para facilitar operaciones como la diferencia de fechas, etc:

<code php>
namespace App\Models;

Use Illuminate\Database\Eloquent\Model;

class Post extends Model
{
    // Ahora indicamos qué campo debe ser transformado a una instancia de Carbon
    protected function casts(): array
    {
        return [
            'published_at' => 'datetime'
        ];
    }
}
</code>

Ahora podríamos usar el nuevo campo con las funcionalidades de Carbon:

<code php>
Route::get('prueba', function() {
    $post = Post::find(1);
    
    return $post->published_at->format('d/m/Y');
    // return $post->published_at->diffForHumans(); // Tiempo transcurrido (relativo)
});
</code>

Podemos ver todos los tipos que podríamos transformar (//casting//) desde la [[https://laravel.com/docs/12.x/eloquent-mutators#attribute-casting|documentación oficial]].
===== Insertar información =====

==== Seeders ====

Podemos definir qué registros estén presente siempre que creemos una tabla. Para esto existen los //seeders// en Laravel.

En la carpeta ''database/seeders/'' existe un fichero llamado ''DatabaseSeeder.php'' con un método ''run()''.

Imaginemos que cada vez que se cree una tabla de usuarios, se añada un registro de un usuario con ciertos campos:

<code php>
namespace Database\Seeders;

use App\Models\User;
use Illuminate\Database\Seeder;

class DatabaseSeeder extends Seeder 
{
    /**
    * Seed the application's database
    */
    public function run(): void
    {
        $user = new User();
        
        $user->name = 'Pepito Grillo';
        $user->email = 'pepito@paisdelasmaravillas.com';        
        $user->password = bcrypt('contraseña');
        
        $user->save();
    }
}
</code>

Si ahora ejecutamos:

<code bash>
php artisan migrate:fresh
</code>

Se habrán borrado todas las tablas, pero no se añade el registro que queremos. Para ello, debemos usar otro comando:

<code bash>
php artisan db:seed
</code>

Esto poblará las tablas de las bases de datos con lo que hemos programado.

<WRAP center round info 80%>
Si queremos ejecutar solo un determinado //seeder//:

<code bash>
php artisan db:seed --class=NombreSeeder
</code>
</WRAP>

Podemos combinar los dos comandos anteriores de la siguiente manera:

<code bash>
php arisan migrate:fresh --seed
</code>

Si queremos añadir varios registros, no es muy cómodo hacerlo todo en el fichero ''DatabaseSeeder.php''. Lo mejor es crear archivos con //seeders// por separado:

<code bash>
php artisan make:seeder UserSeeder
</code>

Esto habrá creado el fichero ''UserSeeder.php'' en ''database/seeders''. Y ahí iremos creando el código para añadir usuarios. Lo mismo para ''PostSeeder.php''.

Después tendremos que modificar el método ''run()'' del fichero ''DatabaseSeeder.php'' para indicar qué //seeders// queremos que se ejecuten:

<code php>
class DatabaseSeeder extends Seeder 
{
    /**
    * Seed the application's database
    */
    public function run(): void
    {
        $this->call([
            PostSeeder::class,
            UserSeeder::class
        ]);
    }
}
</code>

Para ejecutar los //seeders//:

<code bash>
php artisan migrate:fresh --seed
</code>
==== Factories ====

Los //factories// son clases con el nombre de un modelo y luego una definición donde indicamos cómo queremos rellenar los datos del modelo. Funcionan como una serie de fábricas donde indicamos qué queremos que se cree en cada campo.

Al crear un proyecto en Laravel, incluye el factory **User** en ''database/factories/UserFactory.php''.

<code php>
// ...
    public function definition(): array
    {
        return [
            'name' => fake()->name(),
            'email' => fake()->unique()->safeEmail(),
            'email_verified_at' => now(),
            'password' => static::$password ??= Hash::make('password'),
            'remember_token' => Str::random(10),
        ];
    }
</code>

Para generar estos datos, Laravel se apoya en la biblioteca [[https://github.com/FakerPHP/Faker|Faker]] que permite generar información aleatoria.

Para llamar a un //factory// existente, primero hay que modificar el método ''run()'' de ''DatabaseSeeder.php'':

<code php>
class DatabaseSeeder extends Seeder 
{
    /**
    * Seed the application's database
    */
    public function run(): void
    {
        // ...
        User::factory(10)->create();
    }
}
</code>

En el código anterior indicamos que queremos crear 10 registros de usuarios utilizando el //factory// ''UserFactory.php''. 

Para ejecutar el //factory//:

<code bash>
php artisan migrate:fresh --seed
</code>

También podíamos haber colocado el código de //factory// en ''UserSeeder.php'':

<code php>
// ...
    public function run(): void
    {
        $user = new User();
        
        $user->name = 'Pepito Grillo';
        $user->email = 'pepito@paisdelasmaravillas.com';
        $user->password = bcrypt('alicia');
        
        $user->save();
        
        User::factory(10)->create();
    }
</code>

Para crear nuestro propio //factory//, usaremos Artisan:

<code php>
php artisan make:factory PostFactory
</code>

Hemos indicado que el factory que queremos crear es para el modelo **Post** siguiendo la convención del nombre. Tendremos que rellenar la definición de la //factory// recién creada:

<code php>
    public function definition() 
    {
        return [
            'title' => $this->faker->sentence(),
            'content' => $this->faker->text(1000),
            'category' => $this->faker->word(),
            'published_at' => $this->faker->dateTime(),
        ];
    }
</code>

Es importante indicar en nuestro modelo (''app/Models/Post.php'') que tiene una //factory//:

<code php>
use Illuminate\Database\Eloquent\Factories\HasFactory;

class Post extends Model
{
   use HasFactory;
}
</code>

Ahora vamos a ''PostSeeder.php'' para usarlo:

<code php>
// ...
    public function run(): void 
    {
        Post::factory(100)->create();
    }
</code>

Ya podremos usarlo y se generarán 100 registros en la tabla ''posts'' con información aleatoria:

<code bash>
php artisan migrate:fresh --seed
</code>

De todos modos, si nuestro ''PostSeeder.php'' queda solo con esa instrucción, mejor sería moverla a ''DatabaseSeeder.php'' haciendo que el fichero ''PostSeeder.php'' ya no sea necesario:

<code php>
// ...
    public function run(): void
    {
        Post::factory(100)->create();
        
        $this->call([
            UserSeeder::class
        ]);
    }
</code>
==== Database seeder ====

Podemos indicar por código cómo queremos crear instancias de nuestros modelos sin usar tinker.

Vamos a ''database/seeders/DatabaseSeeder.php'':

<code php>
    public function run() 
    {
        $products = Product::factory(5)->create();
    }
</code>

Para ejecutar este seeder:

<code>
php artisan migrate:fresh --seed
</code>

Se crea de nuevo la base de datos y sus tablas y finalmente el seeder que ejecutará 5 instancias de Producto y las meterá en base de datos.

Si solo queremos ejecutar el seeder:

<code>
php artisan db:seed 
</code>

===== Construyendo consultas a base de datos =====

==== Usando el Query Builder ====

Laravel dispone de un [[https://laravel.com/docs/10.x/queries|Query Builder]] que permite construir las consultas SQL para interactuar directamente con la base de datos.

Si queremos obtener toda la información de cierta tabla usando Query Builder:

<code php>
use Illuminate\Support\Facades\DB;

class ProductController extends Controller
{
    public function index()
    {
        $products = DB::table("products")->get();
        
        dd($products);
    }
}
</code>

Cogiendo solo un elemento:

<code php>
    // code
    public function show($product)
    {
        $product = DB::table("products")->where("id", $product)->first();
        
        dd($product);
    }
</code>

Podríamos abreviar la consulta usando el método ''find'' ya que buscará el primer elemento que coincida con el ID que indicamos:

<code php>
    // code
        $product = DB::table("products")->find($product);
</code>

==== Usando los modelos ====

Cualquier cosa que se pueda hacer con el Query Builder, también se puede hacer a través del modelo, y es lo recomendable (usando Eloquent).

La mayor utilidad de usar el modelo es su mantenimiento y escalabilidad del proyecto. Por ejemplo, si en algún momento se cambia el nombre de la tabla, usando el Query Builder, tendríamos que buscar en nuestro código todas las sentencias donde usamos el Query Builder con dicha tabla. Si usamos modelos, basta con hacer el cambio en el atributo ''$table'' del modelo.

Si queremos obtener una lista completa de productos usando el modelo y Eloquent (el ORM de Laravel):

<code php>
use Illuminate\Support\Facades\DB;

class ProductController extends Controller
{
    public function index()
    {
        $products = Product::all();
        
        dd($products);
    }
}
</code>

Cogiendo solo un elemento:

<code php>
    // code
    public function show($product)
    {
        $product = Product::find($product);
        
        dd($product);
    }
</code>

Tenemos un método interesante para cuando no se encuentra lo que buscamos:

<code php>
    // code
    public function show($product)
    {
        $product = Product::findOrFail($product);
     
        // code       
 
    }
</code>

Lo que hará ''findOrFail'' es lanzar una excepción que Laravel tratará como un error 404.

Si no lo usásemos y no existiera el producto, ''find'' devolvería ''NULL''.