Eloquent: l'ORM di Laravel

Dopo aver approfondito le componenti V (Views) e C (Controller) del pattern MVC, è giunto il momento di dedicarci alla M, il Model. Questo articolo rappresenta il primo di una serie dedicata alla gestione dei dati di business all'interno di una applicazione Laravel.

Laravel mette a disposizione del programmatore un ORM particolarmente funzionale di nome Eloquent. Utilizzando Eloquent, ciascuna tabella del database viene mappata con una classe PHP che ne faciliterà la gestione permettendo di eseguire una serie di operazioni ignorando completamente lo strato di interazione con il database.

Laravel supporta out-of-the-box 4 database differenti, mascherando le diverse implementazioni:

• MySQL
• Postgres
• SQLite
• SQL Server

Creazione e configurazione di modelli

Laravel offre un comando da terminale per la creazione di modelli. Grazie a php artisan make:model Model, il motore di generazione del codice creerà un file all'interno della cartella app.

Il framework sfrutta appieno il pattern convention over configuration che prevede di avere una serie di convenzioni pre-definite dagli autori del framework e che spesso possono essere condivise. Tutte queste convenzioni possono comunque essere sovrascritte in casistiche particolari.

La prima convenzione adottata riguarda la mappatura tra il nome del modello e il nome della tabella del database. La regola seguita è quella di convertire il nome del modello (spesso in camel case) in snake case e di pluralizzarlo. Quindi il modello User mapperà la tabella users e il modello BlogPost mapperà blog_posts. Questa convenzione è ovviamente sovrascrivibile tramite la property $table della stessa classe.

class User extends Model
{
    protected $table = 'name_of_the_users_table';
}

La seconda convenzione riguarda il campo chiave primaria. In automatico Laravel sfrutta il campo id, ma è possibile ridefinirlo utilizzando la property $primaryKey.

Oltre al campo id, Laravel utilizza altri due campi standard per tutti i modelli: created at e updated at che contengono rispettivamente la data di creazione e di ultima modifica del modello. Laravel popola automaticamente questi campi ma è possibile disattivarli, se non necessari, impostando la property $timestamps su false. E' inoltre possibile personalizzare il formato di questi campi tramite la property $dateFormat.

Recuperare modelli dal database

Una volta configurati i modelli sulla nostra struttura delle tabelle del database, è giunto il momento di utilizzare i modelli nei controller. Le prime operazioni che analizzeremo saranno quelle di retrieve multiple e singole.

Tramite il metodo statico all() è possibile recuperare tutte le entità di una particolare classe:

class UserController extends Controller
{
    public function index()
    {
        $users = User::all();
        return view('users', ['users' => $users]);
    }
}

Ciascun modello ottenuto tramite Eloquent è un oggetto PHP che presenta una serie di campi in base alle colonne della tabella sul database. Per esempio, per recuperare il valore username di un User, basterà scrivere $user->username.

Grazie al motore di query building di Laravel, è possibile aggiungere particolari vincoli alle query di selezione dei record. Questo esempio permette di recuperare i primi 20 utenti, ordinati per data di creazione che presentano il campo enabled su "1":

User::where('enabled', 1)->orderBy('created_at', 'asc')->take(20)->get()

Il motore di query building permette di concatenare una serie di direttive, la prima è rappresentata da un metodo statico (nel nostro esempio where) seguito da una serie di metodi; ognuno di questi ritorna un oggetto Query che può essere effettivamente eseguito tramite il metodo finale get(), che ritorna una Collection di record. Il precedente metodo all() rappresenta solamente un alias di un query builder.

Nel caso volessimo ottenere un singolo record, e non una lista, abbiamo a disposizione due strumenti: il metodo statico find() che permette di recuperare un record a partire dall'id e il metodo first() che sostituisce il precedente get() e che ritorna solamente il primo record a partire dalle direttive configurate.

Inserire e aggiornare record

Il modo più semplice per creare ed aggiornare record è sfruttare le property PHP dell'oggetto e invocare il metodo save(). Sarà Laravel ad occuparsi della discriminazione tra le query di INSERT e di UPDATE.

$song = new Song;
$song->title = 'Everybody hurts';
$song->artist = 'R.E.M';
$song->save();
$song = Song::find(1);
$song->artist = 'R.E.M.';
$song->save();

Se dovesse servire, è possibile invocare una query UPDATE direttamente da criteri di selezione senza istanziare oggetti PHP:

Song::where('artist', 'R.E.M'.)->update('stars', 5);

E' importante ricordare che esiste un modo alternativo per creare un nuova entità tramite l'invocazione del metodo statico create() e un array associativo di proprietà. Questo approccio è comodo in caso di creazione con i parametri POST di una richiesta che vengono appunto forniti tramite un array associativo.

Per evitare eventuali problemi di scrittura di proprietà private (come ad esempio la password) è possibile limitare i nomi dei campi impostabili tramite questa modalità di creazione di record. Con la property $fillable è possibile configurare i nomi dei campi accettati. Nel caso di approccio contrario, possiamo definire una blacklist di campi tramite $guarded. Non è invece possibile utilizzare entrambi i campi.

class Song extends Model
{
    protected $guarded = ['stars'];
}
[...]
Song::create([ 'title' => 'Losing my religion', 'artist' => 'R.E.M.' ]); //stars non è un attributo valido

Oltre al metodo create(), sono disponibili due altri metodi statici che possono ricevere un array associativo come parametro. firstOrCreate() permette di ottenere un istanza dal database o di crearla se non esiste; firstOrNew() è simile alla precedente ma in questo caso, se non presente, verrà solamente istanziata.

Eliminare record

Per eliminare un record già istanziato è possibile invocare il metodo delete(). Nel caso non si disponga dell'entità è possibile eliminare il record a partire dall'id o da una query:

$song = Song::find(1);
$song->delete();
Song::destroy(2);
Song::where('artist', 'Bieber')->delete();

Eliminazione logica

Laravel supporta out-of-the-box l'eliminazione logica dei record. Con "eliminazione logica" intendiamo la possibilità di gestire il classico "cestino" dove inserire i record eliminati: i record verranno sempre mantenuti all'interno del database ma verranno esclusi automaticamente da eventuali query di selezione. Per configurare l'eliminazione logica su un entità è necessario utilizzare il trait SoftDeletes nel modello e creare un campo deleted_at alla tabella relativa. Questo campo conterrà la data di eliminazione nel caso il record fosse stato cancellato e null nel caso opposto.

Ad ogni invocazione di delete su entità del modello, il record non verrà eliminato, ma verrà valorizzata la colonna deleted_at. Sarà comunque possibile ricercare tra le entità eliminate logicamente tramite i metodi withTrashed() e onlyTrashed().

Nel caso si volesse invece annullare l'eliminazione è possibile utilizzare restore() e, nel caso opposto in cui si voglia fisicamente eliminare il record dal database, il metodo forceDelete().