Eloquent models (part 2)

• In previous chapters, we discussed the basics about models:
  • we created a model for each database table
  • used the $fillable or $guarded properties to prevent mass assignment vulnerability
  • used the $hasMany and $belongsTo relations between the database tables
• In this chapter, you will get an introduction to:
  • accessors and mutators
  • hide attributes from the database table
  • add additional properties
  • query scopes
• For these examples, we work in the controller app/Http/Controllers/Admin/RecordController.php and the related view resources/views/admin/records/index.blade.php

do this first

• Before starting this chapter, make sure you have configured the debug middleware

Genres table

• Let's start with querying the smallest table genres

Get all genres

• Replace the code in the index method of the controller
• Display the resulting record set (or collection (opens new window)) in a browser

• Get all records from the genres table and return this as JSON

public function index()
{
   $genres = Genre::get();
   return $genres;
}

• Open http://vinyl_shop.test/admin/records (opens new window) in the browser
• Because we return the $genres directly, Laravel will convert the result to a JSON format

REMARK

The same result (retrieving all the genres) can be achieved with $genres = Genre::all()

TIP

• Use the autocompletion of PhpStorm for automatic imports
  • Start typing 'Gen..'
  • Choose the proper class: Genre [App\Models]
  • Push Enter
• By doing so, you do not have to add the import statement (use App\Models\Genre;) manually

Order genres

• Laravel's ORM allows chaining different Eloquent methods to fine-tune the query
• One of the methods you probably always use is orderBy() (a -> z) or orderByDesc() (z -> a)

• Update the query and order the genres by the name attribute

public function index()
{
   $genres = Genre::orderBy('name')->get();
   return $genres;
}

Hide attributes

• If we don't need the created_at and updated_at attributes in our JSON representation, we can hide them by adding these fields to the $hidden array in the Genre model

class Genre extends Model
{
    ...
    
    /**  Add attributes that should be hidden to the $hidden array */
    protected $hidden = ['created_at', 'updated_at'];
}

• What if you want to hide these attributes for almost every query except for this one?
• No problem, you can make hidden attributes back visible inside the controller by chaining the makeVisible()methode AFTER you get all the genres

public function index()
{
   $genres = Genre::orderBy('name')->get();
   $genres->makeVisible('created_at');
   return $genres;
}

TIP

If you want an attribute to be visible in most of your queries, except for one, leave the $hidden array in the model empty and chain the makeHidden() method inside the controller.
E.g. $genres = Genre::orderBy('name')->get()->makeHidden(['created_at', 'updated_at']);

REMARK

• $hidden and makeHidden() only hides attributes from the JSON representation but you can still use the hidden attribute in a view!

Accessors and mutators

• An accessor transform the attribute after it has retrieved from database
• A mutator transform the attribute before it is sent to database
• In our genres table we want:
  • always store the name in lowercase letter (= mutator)
  • always show the name with the first letter in uppercase (= accessor)
• IMPORTANT: the name of the method MUST BE the name of the attribute you want to manipulate!

• Accessor (get): capitalize the first letter of the value with the PHP function ucfirst (opens new window)
• Mutator (set): make the value lowercase with the PHP function strtolower (opens new window)

class Genre extends Model
{
    ...
    
    /**  Accessors and mutators (method name is the attribute name) */
    protected function name(): Attribute
    {
        return Attribute::make(
            get: fn($value) => ucfirst($value),         // accessor
            set: fn($value) => strtolower($value),      // mutator
        );
    }
    
    ...
}

• Remove the makeVisible()methode from the previous example

public function index()
{
   $genres = Genre::orderBy('name')->get();
   return $genres;
}

Genre with records

• The model Genre has a relation with the model Record
• You can include the records that belong to a genre with the with() method
  • The with() method takes a relation name as argument: with('records')
• Also update the view to show all the genres with the records

TIP

Open a second browser tab and go to http://vinyl_shop.test/admin/records?json (opens new window) to see the JSON representation of the data

• For future purposes, we pass the data collection to the view by wrapping it into an associative array using the PHP function compact()
• compact('records') is the same as ['records' => $records] like we did in basic controllers

public function index()
{
   $genres = Genre::orderBy('name')->with('records')->get();
   return view('admin.records.index', compact('genres'));
}

• Line 7: loop over all the genres @foreach ($genres as $genre) ... @endforeach
• Line 10: show the genre name with $genre->name
• Line 11:
  • count the number of records belonging to this genre with $genre->records()->count()
  • pluralize (opens new window) the word record Str::plural('record', $genre->records()->count())
    (if the second argument is 1, the word is singular, otherwise it is plural)
• Line 14: loop over all the records belonging to this genre @foreach($genre->records as $record) ... @endforeach
• Line 15: show the artist of the record with $record->artist
• Line 15: show the title of the record with $record->title

<x-vinylshop-layout>
    <x-slot name="description">Admin records</x-slot>
    <x-slot name="title">Records</x-slot>

    <h2>Genres with records</h2>
    <div class="grid grid-cols-1 lg:grid-cols-2 gap-4">
        @foreach ($genres as $genre)
            <div class="flex space-x-4 bg-white shadow-md rounded-lg p-4">
                <div class="flex-none w-36 border-r border-gray-200">
                    <h3 class="font-bold text-xl">{{ $genre->name }}</h3>
                    <p>Has {{ $genre->records()->count() }} {{ Str::plural('record', $genre->records()->count()) }}</p>
                </div>
                <div>
                    @foreach($genre->records as $record)
                        <x-tmk.list class="list-outside ml-4">
                            <li>
                                <span class="font-bold">{{ $record->artist }}</span><br>
                                {{ $record->title }}
                            </li>
                        </x-tmk.list>

                    @endforeach
                </div>
            </div>
        @endforeach
    </div>
</x-vinylshop-layout>

• Most of the genres have no records, so scroll down to find the genres with records

Genres that has records

• Most of the genres have no records
• Use the has() method to filter on only the genres that have records
  • The has() method takes a relation name as argument: has('records')

public function index()
{
   $genres = Genre::orderBy('name')->with('records')->has('records')->get();
   return view('admin.records.index', compact('genres'));
}

Records table

Get all records with genre

• The model Record has a relation with the model Genre
• You can include the genre of a record with the with() method
  • The with() method takes a relation name as argument: with('genre')
• Before we update the view, let us first inspect the JSON representation of the data at http://vinyl_shop.test/admin/records?json (opens new window)

• Line 3: get all records with the genre, ordered first by the artist and secondly by the title
  (if an artist has multiple records, the records for this artist are ordered by the title)
• Line 5: add records to the compact() function

public function index()
{
   $records = Record::orderBy('artist')->orderBy('title')->with('genre')->get();
   $genres = Genre::orderBy('name')->with('records')->has('records')->get();
   return view('admin.records.index', compact('records','genres'));
}

Additional attribute (genre_name)

• In the view, we can select the genre name with $record->genre->name and that's fine but won't it be easier to add the genre name as an additional attribute to the record?
• To add additional attributes to the JSON representation of the model
  • First, define an accessor for the attribute you want to add
    (The name of the accessor must be different from the attribute names in the database table)
  • Then, add the attribute to the $appends array in the model

• The accessor genreName searches in the Genre table for the record with id equal to genre_id from the record and gets the name attribute Genre::find($attributes['genre_id'])->name
  E.g. the record Atari Teenage Riot - The Future of War has the genre_id of 12, so the accessor searches in the Genre table for the record with id=12 and gets the name attribute
  Genre::find(12)->name = Noise
• Next, append the accessor in snake_case to the $appends array

class Record extends Model
{
    ...
    
    /**  Add additional attributes that do not have a corresponding column in your database */
    protected function genreName(): Attribute
    {
        return Attribute::make(
            get: fn($value, $attributes) => Genre::find($attributes['genre_id'])->name,
        );
    }
    
    protected $appends = ['genre_name'];
    
    ...
}

• Line 3: delete the with('genre') because we don't need it anymore

public function index()
{
   $records = Record::orderBy('artist')->orderBy('title')->get();
   $genres = Genre::orderBy('name')->with('records')->has('records')->get();
   return view('admin.records.index', compact('records','genres'));
}

Additional attribute (price_euro)

• The second additional attribute we're going to add is the price, formatted with 2 decimals and the Euro symbol (€)

• The accessor priceEuro is a Euro symbol followed by the price formatted with 2 decimals (opens new window)
• Next, append the accessor in snake_case to the $appends array

class Record extends Model
{
    ...
    
    /**  Add additional attributes that do not have a corresponding column in your database */
    protected function genreName(): Attribute {...}
    
    protected function priceEuro(): Attribute
    {
        return Attribute::make(
            get: fn($value, $attributes) =>  '€ ' . number_format($attributes['price'],2),
        );
    }

    protected $appends = ['genre_name', 'price_euro'];
    
    ...
}

Additional attribute (cover)

• As you may have noticed, there is no cover column in the records table
• The image refers to the record's mb_id attribute and can be found in the covers folder.
  E.g. if the mb_id value is fcba15e2-3d1e-40b3-996c-be22450bda82, the path to the cover is
  /storage/covers/fcba15e2-3d1e-40b3-996c-be22450bda82.jpg
• We use Laravels File System (opens new window) to:
  • check if the file exists
  • if the file exists, return the path to the file
  • else return the path to the dummy cover (no-cover.png)

• Line 13: search in the public disk (= public folder) for the file with the path /storage/covers/{$attributes['mb_id']}.jpg
• Line 14 - 17: if the file exists, return an associative array with:
  • exists: true
  • url: the path to the file
• Line 14 - 17: if the file doesn't exist, return an associative array with:
  • exists: false
  • url : the path to the dummy cover
• Next, append the accessor to the $appends array

class Record extends Model
{
    ...
    
    /**  Add additional attributes that do not have a corresponding column in your database */
    protected function genreName(): Attribute {...}
    protected function priceEuro(): Attribute {...}
    
    protected function cover(): Attribute
    {
        return Attribute::make(
            get: function ($value, $attributes) {
                if (Storage::disk('public')->exists('covers/' . $attributes['mb_id'] . '.jpg')) {
                    return [
                        'exists' => true,
                        'url' => Storage::url('covers/' . $attributes['mb_id'] . '.jpg'),
                    ];
                } else {
                    return [
                        'exists' => false,
                        'url' => Storage::url('covers/no-cover.png'),
                    ];
                }
            },
        );
    }

    protected $appends = ['genre_name', 'price_euro', 'cover'];
    
    ...
}

Storage import

• Storage (opens new window) is a Facade class from Laravel
• Don't forget to add the correct import: use Illuminate\Support\Facades\Storage; or use Storage;

Update the view

• Add, for every record, a card with the fields: cover['url'], title, artist, genre_name, price_euro, and stock

• Line 7: loop over all the records @foreach ($records as $record) ... @endforeach
• Line 10: show the cover for this record $record->cover['url'] (remember the cover attribute is an associative array with the keys exists and url)
• Line 13: show the artist of the record $record->artist
• Line 14: show the title of the record $record->title
• Line 15: show the genre name $record->genre_name
• Line 16: show the formatted price in euro$record->price_euro
• Line 17 - 21:
  • if there are records in stock, show the stock: $genre->stock
  • else show the message 'SOLD OUT'

<x-vinylshop-layout>
    <x-slot name="description">Admin records</x-slot>
    <x-slot name="title">Records</x-slot>

    <h2>Records with a price ≤ € 20</h2>
    <div class="grid grid-cols-1 lg:grid-cols-2 gap-4 mb-8">
        @foreach ($records as $record)
            <div class="flex space-x-4 bg-white shadow-md rounded-lg p-4 ">
                <div class="inline flex-none w-48">
                    <img src="{{ $record->cover['url'] }}" alt="">
                </div>
                <div class="flex-1 relative">
                    <p class="text-lg font-medium">{{ $record->artist }}</p>
                    <p class="italic text-right pb-2 mb-2 border-b border-gray-300">{{ $record->title }}</p>
                    <p>{{ $record->genre_name }}</p>
                    <p>Price: {{ $record->price_euro }}</p>
                    @if($record->stock > 0)
                        <p>Stock: {{ $record->stock }}</p>
                    @else
                        <p class="absolute bottom-4 right-0 -rotate-12 font-bold text-red-500">SOLD OUT</p>
                    @endif
                    <p></p>
                </div>
            </div>
        @endforeach
    </div>

    <h2>Genres with records</h2>
    ...
</x-vinylshop-layout>

• Most of the genres have no records, so scroll down to find the genres with records

Query scope (price ≤ € 20)

• Sometimes you want to filter the results of a query by a certain attribute value
• This can be done with the where method inside the controller, but you can also do it in the model with local or global query scopes, so you don't have to write the same code twice
• Local scopes allow you to define common sets of query constraints that you may easily re-use throughout your application, e.g. to filter out all users with the admin role
• Let's create a filter for the records with a price less or equal to € 20
  • first, we filter the records inside the controller
  • then we refactor the controller and move the filter to the model

• Line 3: set the price limit to € 20 $maxPrice = 20;
• Line 4: limit the result to only records up to 20 euro where('price', '<=', $maxPrice)

public function index()
{
    $maxPrice = 20;
    $records = Record::where('price', '<=', $maxPrice)
        ->orderBy('artist')
        ->orderBy('title')
        ->get();
    $genres = Genre::orderBy('name')->with('records')->has('records')->get();
    return view('admin.records.index', compact('records','genres'));
}    

• Only records with a price ≤ € 20 are shown

• Let's create a global scope to filter the records with a price less or equal to $maxPrice
  • first, we create the scope
  • then we add it to the model
• Local scopes always start with the prefix scope, followed by the name of the scope
  • e.g. the scope scopeMaxPrice($query, $price = 100) can be used inside the controller as:
    • maxPrice($maxPrice)
    • maxPrice() (if the default value of 100 is used)
  • the first parameter in the function is always the query
  • the second parameter (optional) is the value or values to filter by

class Record extends Model
{
    ...
    
    /**  Apply the scope to a given Eloquent query builder */
    public function scopeMaxPrice($query, $price = 100)
    {
        return $query->where('price', '<=', $price);
    }
    
    ...
}

• Line 4: replace where('price', '<=', $maxPrice) with maxPrice($maxPrice)

public function index()
{
    $maxPrice = 20;
    $records = Record::maxPrice($maxPrice)
        ->orderBy('artist')
        ->orderBy('title')
        ->get();
    $genres = Genre::orderBy('name')->with('records')->has('records')->get();
    return view('admin.records.index', compact('records','genres'));
}    

• The same result as before

IMPORTANT

• Open the menu Laravel > Generate Helper Code to add the new scope for type hinting and auto-completion in PhpStorm
• Repeat this step for every new scope you create
  

Pagination

• Because the list of records can be very long, it's better to show only a fraction of the records and add some pagination (opens new window) to the views
• You can limit the number of records per page by replacing get() with paginate(x), where x is the number of records per view (e.g. 6)
• Add a pagination navigation to the view (e.g. one before and another one after the loop) using
  $records->withQueryString()->links()

• Line 5: set the number of records to display per page $perPage = 6;
• Line 9: replace get() with paginate($perPage)

public function index()
{

    $maxPrice = 20;
    $perPage = 6;
    $records = Record::where('price', '<=', $maxPrice)
        ->orderBy('artist')
        ->orderBy('title')
        ->paginate($perPage);
    $genres = Genre::orderBy('name')->with('records')->has('records')->get();
    return view('admin.records.index', compact('records','genres'));
}    

• Line 6 and 12: add the pagination links to the page $records->withQueryString()->links()

<x-vinylshop-layout>
    <x-slot name="description">Admin records</x-slot>
    <x-slot name="title">Records</x-slot>

    <h2>Records with a price ≤ € 20</h2>
    <div class="mb-4">{{ $records->withQueryString()->links() }}</div>
    <div class="grid grid-cols-1 lg:grid-cols-2 gap-4 mb-8">
        @foreach ($records as $record)
            ...
        @endforeach
    </div>
    <div class="mb-4">{{ $records->withQueryString()->links() }}</div>

    <h2>Genres with records</h2>
    ...
</x-vinylshop-layout>

• Most of the genres have no records, so scroll down to find the genres with records

REMARKS

• By default, the views rendered to display the pagination links are styled with Tailwind, but of course you can customize the pagination view (opens new window)
• Laravel adds some extra attributes (current_page, first_page_url, ...) that eventually can be used inside the view

Fast model overview

• Now that we added some extra attributes to the model, it's sometimes hard to remember all those attributes and the relations to other models
• The artisan CLI has the great command php artisan model:show <Model> to generate a compact overview with a lot of information about the model (table name, fillable attributes, appended attributes, relations to other models, ...)

Inspecting database information requires the Doctrine DBAL (doctrine/dbal) package. Would you like to install it?

• The first time you execute this artisan command, it might ask you to install the Doctrine DBAL package.
• Choose y and press enter to continue
• Re-execute the php artisan model:show <Model> command

• Run the command php artisan model:show Genre in the console

• Run the command php artisan model:show Record in the console

• Run the command php artisan model:show User in the console

Exercise

• Make the background color of the card red if the record is out of stock