====== Eloquent ORM (Laravel) ======

Eloquent es un ORM (//Object-Relational Mapper//) incluido en [[informatica:programacion:php:frameworks:laravel|Laravel]] para interactuar con la base de datos.

Al usar Eloquent, cada tabla de la base de datos está asociada a un model que se usa para interactuar con dicha tabla.

  * [[https://laravel.com/docs/master/eloquent|Documentación oficial sobre Eloquent]]
===== Generación de clases para modelos =====

Para generar una clase que se empleará de modelo:

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

Si añadimos la opción ''-m'' (o ''%%--%%migration''), también se creará la migración.

===== Convenciones =====

==== Nombres de las tablas ====

Por defecto, Eloquent considerará que el nombre de la tabla al que está asociado el modelo será el nombre del modelo en //snake_case// y en plural.

Por ejemplo, si nuestra clase modelo es ''Product'', la tabla será ''products''. Si tenemos una clase modelo llamada ''AirTrafficController'', la tabla se llamará ''air_traffic_controllers''.

Si no seguimos esta convención, entonces debemos indicar el nombre de la tabla:

<code php>
// 
class Product extends Model
{
    /**
     * The table associated with the model.
     *
     * @var string
     */
    protected $table = 'mis_productos';
</code>

==== Claves primarias ====

Eloquent también asuma que cada tabla tiene una columna llamada ''id'' y que es la clave primaria.

Si queremos indicar otra distinta, definimos una propiedad en el modelo:

<code php>
// 
class Product extends Model
{
    /**
     * The primary key associated with the table.
     *
     * @var string
     */
    protected $primaryKey = 'id_producto';
}
</code>

==== Timestamps ====

Por defecto, Eloquent espera que las tablas tengan las columnas ''created_at'' y ''updated_at''. Si no queremos que Eloquent gestione esto, debemos indicarlo en el modelo correspondiente:

<code php>
// 
class Product extends Model
{
    /**
     * Indicates if the model should be timestamped.
     *
     * @var bool
     */
    public $timestamps = false;
}
</code>
===== Inspeccionar modelos =====

<code>
php artisan model:show Flight
</code>

===== Obtener modelos =====

Una vez creado el modelo y su tabla asociada, podemos obtener información de la base de datos. Eloquent es como un potente constructor de consultas para la tabla asociada al modelo.

Por ejemplo, obtener todos los registros de productos:

<code php>
use App\Models\Product;

foreach (Product::all() as $product) {
    echo $product->name;
}
</code>

==== Construcción de consultas ====

Si queremos aplicar criterios en las consultas:

<code php>
$products = Product::where('active', 1)
    ->orderBy('name')
    ->take(10)
    ->get();
</code>

===== Insertar y actualizar modelos =====

==== Insertar ====

Para añadir un registro a la base de datos, creamos una instancia del modelo y establecemos los atributos del modelo. Finalmente, llamamos al método ''save'':

<code php>
<?php
namespace App\Http\Controllers;

use App\Models\Product;
use Illuminate\Http\RedirectResponse;
use Illuminate\Http\Request;

class ProductController extends Controller
{
    /**
     * Store a new product in the database.
     */
    public function store(Request $request): RedirectResponse
    {
        // Validate the request...
        $product = new Product;
        $product->name = $request->name;
        $product->save();
 
        return redirect('/products');
    }
}
</code>

Como alternativa, también podríamos usar el método ''create'' para añadir el registro en una única sentencia PHP:

<code php>
use App\Models\Flight;

$product = Product::create([
    'name' => 'Mesa camilla',
]);
</code>

Sin embargo, para poder usar el método ''create'', necesitaremos indicar la propiedad ''fillable'' o ''guarded'' en la clase del modelo. Estas propiedades son necesarias para proteger los modelos contra vulnerabilidades por asignaciones masivas.

==== Actualizar ====

El método ''save'' también se puede usar para actualizar. Primero debemos recuperar el registro /modelo que queremos modificar:

<code php>
use App\Models\Product;

$product = Product::find(1);

$product->name = 'Silla de madera';

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

==== Eliminar ====

Para eliminar un modelo, llamamos a su método ''delete'':

<code php>
use App\Models\Product;

$product = Product::find(1);

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

Si conocemos la clave primaria del modelo que queremos eliminar, no es necesario obtenerlo primero, bastaría con llamar a ''destroy'':

<code php>
Flight::destroy(1);
</code>
===== Consultas SQL generadas =====

Cuando en Laravel usamos lo siguiente:

<code php>
User::get()
</code>

Eloquent lo traduce a:

<code sql>
SELECT *
FROM users
</code>

  * [[https://github.com/alexeymezenin/eloquent-sql-reference|SQL queries generated by Eloquent ORM reference]]