Eloquent models, mass assignment, soft deletes

Pathshala’s accountant imports fee instalments from a spreadsheet of 100 students at a time: 1,000 rows a term. If each row runs its own insert, that is 1,000 round trips through the database driver; if one of those rows has a key nobody declared on the model, the row is written anyway and the extra field is dropped in silence. This lesson settles both problems: a model with a short Fillable list, a boot method that turns on strict mode outside production, and an upsert call whose query count the probe prints as 1.

Along the way you will see what each strict-mode guard refuses, read a soft-deleted row with withTrashed, restore it, and give one Pathshala table a ULID key while still writing the authorization that an unguessable id does not replace.

A model is a row, and strict mode makes the slips loud

An Eloquent modelEloquent model: A PHP class that stands for one database table, each of its objects for one row: the Notice model queries the notices table, and saving a Notice object writes its row. More in “Your first CRUD feature with Eloquent” is a PHP class that stands for one database row. Pathshala’s fee sheet needs two of them, kept in app/Models/: Student for one row of the students table, and FeeInstalment for one row of the fee_instalments table. This lesson’s migrationmigration: A schema change written as a PHP class with an up method that applies it and a down method that undoes it, kept in database/migrations and run in file-name order. More in “Your first CRUD feature with Eloquent” gives the fee_instalments table a unique index on (student_id, due_on), so no two instalments belong to the same student on the same date; the model is what the rest of the code uses to read and write that table.

<?php

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

return new class extends Migration
{
    public function up(): void
    {
        Schema::create('fee_instalments', function (Blueprint $table) {
            $table->id();
            $table->unsignedBigInteger('student_id')->index();
            $table->date('due_on');
            $table->unsignedInteger('amount_paise');
            $table->string('status', 10)->default('due');
            $table->softDeletes();
            $table->timestamps();
            $table->unique(['student_id', 'due_on']);
        });
    }

    public function down(): void
    {
        Schema::dropIfExists('fee_instalments');
    }
};

<?php

namespace App\Models;

use Illuminate\Database\Eloquent\Attributes\Fillable;
use Illuminate\Database\Eloquent\Model;
use Illuminate\Database\Eloquent\Relations\HasMany;

#[Fillable(['name', 'phone'])]
class Student extends Model
{
    public function instalments(): HasMany
    {
        return $this->hasMany(FeeInstalment::class);
    }
}

<?php

namespace App\Models;

use Illuminate\Database\Eloquent\Attributes\Fillable;
use Illuminate\Database\Eloquent\Model;
use Illuminate\Database\Eloquent\Relations\BelongsTo;
use Illuminate\Database\Eloquent\SoftDeletes;

#[Fillable(['student_id', 'due_on', 'amount_paise', 'status'])]
class FeeInstalment extends Model
{
    use SoftDeletes;

    protected $casts = [
        'due_on' => 'date',
    ];

    public function student(): BelongsTo
    {
        return $this->belongsTo(Student::class);
    }
}

The #[Fillable([...])] attribute names the four columns a request array may write to a fee instalment, and nothing else. That is the mass assignmentmass assignment: Creating or updating a model from a whole array of fields in one call, which is why a model declares the columns such an array is allowed to write. More in “Your first CRUD feature with Eloquent” boundary from the first-feature module: whatever is not on the list is dropped before Eloquent builds the insert.

Dropped silently, by default. In development, three default behaviours of Eloquent hide bugs you want to see at once: lazy loading a relationship inside a loop runs an extra query per row, which only shows up when the page is slow; a request array with a stray key writes the row without reporting the key; and selecting a subset of columns then reading one of the others returns null, which looks like an empty column. Laravel offers one method, Model::shouldBeStrict(), that turns all three into exceptions.

<?php

namespace App\Providers;

use Illuminate\Database\Eloquent\Model;
use Illuminate\Support\ServiceProvider;

class AppServiceProvider extends ServiceProvider
{
    public function register(): void
    {
        //
    }

    public function boot(): void
    {
        Model::shouldBeStrict(! $this->app->isProduction());
    }
}

Strict modestrict mode: A development-only Eloquent setting that turns three default behaviours into exceptions: lazy loading of a relationship, writing a column the model has not declared, and reading a column the query did not select. only runs when isProduction() is false, so a production site keeps its old habit. The probe below seeds two students and four instalments without the guards, turns them on, and provokes each in turn, catching the exception each throws:

from session import run

# Model::shouldBeStrict() turns on three guards at once: no lazy loading, no silent discard of unfillable keys,
# and no reading of a column the query did not select. The probe below seeds two students and four instalments
# without those guards, then switches them on and provokes each in turn, catching the exception each throws.
run(
    """
php artisan migrate --no-interaction
php strict_mode_probe.php
""",
    app=True,
    overlay=("pathshala-model", "strict-mode"),
)

$ php artisan migrate --no-interaction
   INFO  Running migrations.

  2026_01_05_090000_create_students_table ............................... DONE
  2026_01_05_091000_create_fee_instalments_table ........................ DONE
$ php strict_mode_probe.php
Guard 1: lazy loading inside a loop
Illuminate\Database\LazyLoadingViolationException: Attempted to lazy load [instalments] on model [App\Models\Student] but lazy loading is disabled.

Guard 2: an array key the model does not allow
Illuminate\Database\Eloquent\MassAssignmentException: Add fillable property [written_off] to allow mass assignment on [App\Models\FeeInstalment].

Guard 3: a column the query did not select
Illuminate\Database\Eloquent\MissingAttributeException: The attribute [name] either does not exist or was not retrieved for model [App\Models\Student].

Three exceptions arrived in order and named the model and the attribute each time: LazyLoadingViolationException for the instalments relation accessed inside the loop, MassAssignmentException for the written_off key the model does not declare, and MissingAttributeException for the name column the select('id') query left out.

Create, read, update and delete, with firstOrCreate and updateOrCreate

Every row’s life passes through four actions, and Eloquent gives each a short name. create() builds a row from a Fillable array and saves it; find() reads one row by its primary key, where()->first() by any column; a model instance’s property setter plus save() or an array passed to update() writes the changed row back; delete() removes it, or marks it as deleted when the model is soft-deletable.

Two more combined moves cover the common cases. firstOrCreate([keys], [defaults]) reads the row that matches the first array and inserts it with the two arrays merged if there is no match. updateOrCreate([keys], [values]) is the write version: it finds the matching row and sets values on it, or inserts the merged arrays. The wasRecentlyCreated property says which side it took, so the controller after it knows whether to log a new row or a changed one.

<?php

use App\Models\FeeInstalment;

// read or create: idempotent on the keys array alone.
$apr = FeeInstalment::firstOrCreate(
    ['student_id' => 7, 'due_on' => '2026-04-05'],
    ['amount_paise' => 500000, 'status' => 'due'],
);

// write or create: the values on the right are the write.
$may = FeeInstalment::updateOrCreate(
    ['student_id' => 7, 'due_on' => '2026-05-05'],
    ['amount_paise' => 550000, 'status' => 'due'],
);

if ($may->wasRecentlyCreated) {
    // the row was inserted this call; log it to the audit trail.
}

The keys of the first array must land on columns the database agrees are unique together, which is why the migration gave (student_id, due_on) its unique index. Two accountants running firstOrCreate on the same month produce one row, not two: the database refuses the second insert, and firstOrCreate then reads the row the first one wrote.

Upsert changes a thousand rows in one statement

A spreadsheet of 1,000 instalments is 1,000 inserts if every row goes on its own, and 1,000 round trips through the database driver. upsert() sends them as one statement: the first array is every row to write, the second names the columns that make a row unique, and the third names the columns to overwrite when a matching row already exists. Laravel’s own documentation calls it “a single, atomic operation” that updates or inserts in one call. The probe below builds 1,000 rows (100 students over 10 months), upserts them twice and reads back the query log.

Upsertupsert: A single SQL statement that writes many rows: the database matches each row against a unique index and either inserts it or writes the given columns over the matching row. takes one statement whatever the number of rows:

from session import run

# upsert() sends every row of the array in one statement, matching on the unique columns of the
# second argument and updating only the columns of the third. The probe builds 1,000 instalments
# for 100 students over 10 months, upserts them twice, and prints the query count each time.
run(
    """
php artisan migrate --no-interaction
php upsert_fees_probe.php
""",
    app=True,
    overlay=("pathshala-model", "upsert-fees"),
)

$ php artisan migrate --no-interaction
   INFO  Running migrations.

  2026_01_05_090000_create_students_table ............................... DONE
  2026_01_05_091000_create_fee_instalments_table ........................ DONE
$ php upsert_fees_probe.php
Rows to upsert: 1000
Queries run by the first upsert: 1
Statement: insert into "fee_instalments" ("amount_paise", "created_at", "due_on", "status", "student_id", "updated_at") values ...
Rows in fee_instalments: 1000

Second upsert, with changed amounts:
Queries run: 1
Rows in fee_instalments: 1000
Updated amount of (student 1, due 2026-01-05): 500100 paise

The query log printed Queries run by the first upsert: 1 and Rows in fee_instalments: 1000, which is the whole promise: one statement, every row written. The second call changed every amount from 500000 to 500100 paise, and still ran one query; the row of student 1 due on 2026-01-05 came back with 500100 paise, so the matching rows were updated instead of duplicated.

The database decides what “matching” means. The documentation notes that every driver except SQL Server needs the columns of the second argument to have a primary or unique index, and MySQL and MariaDB ignore the second argument and read every unique index of the table. Pin the match down with the index you declared.

Soft deletes keep the row and let you restore it

An accountant who deletes an instalment should still be able to put it back; auditors want to see what was deleted and when. Laravel’s SoftDeletes trait writes the current time into a deleted_at column instead of running a DELETE: every default query of the model adds where deleted_at is null, so a trashed row drops out of it, and withTrashed() and onlyTrashed() read the trashed rows when the code asks for them.

Soft deletesoft delete: Marking a row as deleted with a deleted_at time instead of removing it. Normal queries and route binding skip such rows, and they can be restored. More in “Controllers and route model binding” is on FeeInstalment from the top of this lesson: the migration added softDeletes(), which is the Blueprint helper for a nullable deleted_at column, and the model used the SoftDeletes trait. One row through its states:

from session import run

# The SoftDeletes trait keeps the row and sets a deleted_at timestamp instead of removing it;
# the default query ignores soft-deleted rows, withTrashed() reads them, restore() clears the
# timestamp, and forceDelete() removes the row for good.
run(
    """
php artisan migrate --no-interaction
php soft_delete_probe.php
""",
    app=True,
    overlay=("pathshala-model", "soft-delete"),
)

$ php artisan migrate --no-interaction
   INFO  Running migrations.

  2026_01_05_090000_create_students_table ............................... DONE
  2026_01_05_091000_create_fee_instalments_table ........................ DONE
$ php soft_delete_probe.php
All rows at start:               3

After delete() on the April row:
  default query:                 2 rows
  withTrashed():                 3 rows
  onlyTrashed():                 1 row
  deleted_at of the April row:   2026-04-10 09:15:00

After restore() on the April row:
  default query:                 3 rows
  deleted_at of the April row:   NULL

After forceDelete() on the April row:
  default query:                 2 rows
  withTrashed() still finds it:  false

The default count fell from 3 to 2 after delete(), withTrashed()->count() kept 3 and onlyTrashed()->count() returned 1. deleted_at of the April row read 2026-04-10 09:15:00, which is the test clock the probe set with Carbon::setTestNow for a repeatable run. restore() wrote NULL back into the column and the row returned to every default query; forceDelete() ran the real DELETE and even withTrashed() could no longer find it.

UUID and ULID keys do not replace an authorization check

An auto-increment id in a URL is a page the next integer may reach. If a route serves /students/{student}/fees and the controller trusts the id alone, a visitor with one legitimate link can edit the number and try the next account. The insecure direct object referenceinsecure direct object reference (IDOR): Access to a record through a real identifier, such as an id in a URL, that the application loaded but failed to authorize for the current user. More in “Authorization: gates and policies” name is for that pattern, and OWASP’s cheat sheet is a defensive one: the fix is a check on who may read each row, not a bigger number. A key that is hard to guess stops a visitor from reaching the next row by adding one, and hides how many rows the table holds; it does not refuse any request.

The HasUuids trait gives a model a 36-character UUIDv7 primary key, which is lexicographically sortable because UUIDv7 starts with its timestamp. The HasUlids trait does the same with a 26-character ULIDULID: A 26-character identifier made of a 48-bit timestamp and 80 random bits, sortable in the order it was generated, used as a primary key when a sequential integer would make the next row too easy to guess., which is shorter in the URL and still sorts by time:

<?php

namespace App\Models;

use Illuminate\Database\Eloquent\Attributes\Fillable;
use Illuminate\Database\Eloquent\Concerns\HasUlids;
use Illuminate\Database\Eloquent\Model;

// A one-time code sent to a guardian when they open a session. The ULID key keeps the row's
// identifier out of the URL, so a URL on another device cannot be edited to reach another
// guardian's code. The authorization check in GuardianOtpController does the actual refusing.
#[Fillable(['guardian_id', 'code_hash', 'expires_at'])]
class OtpSession extends Model
{
    use HasUlids;
}

A ULID in the URL of a one-time code is a fence, not a lock. The second half of the pair is the controller: it calls an authorization policy before it reads anything about the row, and the policy answers from the authenticated user and the row, not the URL.

Pruning old rows on a schedule

A guardian one-time code is useful for 10 minutes and then it is clutter. A table of codes two months old is a cost and a liability. The Prunable trait tells a model which of its rows should leave the database over time, and the model:prune Artisan command runs that query on the schedule the application sets.

<?php

namespace App\Models;

use Illuminate\Database\Eloquent\Attributes\Fillable;
use Illuminate\Database\Eloquent\Model;
use Illuminate\Database\Eloquent\Prunable;
use Illuminate\Database\Eloquent\Builder;

#[Fillable(['guardian_id', 'code_hash', 'expires_at'])]
class OtpSession extends Model
{
    use Prunable;

    /**
     * One-time codes that have been consumed, or have been sitting
     * past their expiry for a day, can leave the table.
     */
    public function prunable(): Builder
    {
        return static::query()->where('expires_at', '<=', now()->subDay());
    }
}

Model pruningmodel pruning: A scheduled Artisan task that deletes rows a model marks as no longer needed, so a request that handles today's codes never also has to clean up last month's. runs on the schedule, not inside a request. One line in routes/console.php sets the time of day:

<?php

use App\Models\OtpSession;
use Illuminate\Support\Facades\Schedule;

// routes/console.php: run model:prune every night. Behind the scenes the command walks
// the app/Models folder for Prunable models and calls each one's prunable() query. Only
// the models the --model option names are scheduled when they live outside app/Models.
Schedule::command('model:prune', [
    '--model' => [OtpSession::class],
])->dailyAt('02:30');

model:prune --pretend reports how many rows would leave the table without touching them, which is the test to run before the first scheduled night. Soft-deleted rows that match the prunable query are permanently removed with forceDelete, so a trashed row scheduled for pruning does leave; a prunable method can also return a whereNotNull('deleted_at') to prune only trashed rows.

Practise: a soft-deletable guardian OTP log, with pruning

Give a copy of your Pathshala project a log of guardian OTPs. The six steps repeat the model, upsert, soft-delete and pruning moves of this page on a table the page never built:

1. Write a migration for a guardian_otp_log table with id, guardian_id (indexed), code_hash, expires_at, unique(['guardian_id', 'expires_at']), softDeletes() and timestamps(). Run it with php artisan migrate.
2. Create an App\Models\GuardianOtpLog model that lists guardian_id, code_hash and expires_at under #[Fillable([...])], uses SoftDeletes and casts expires_at to a datetime.
3. Add Model::shouldBeStrict(! $this->app->isProduction()) to AppServiceProvider::boot(). In Tinker, read a row with select('id') and then try to access code_hash to see the third guard fire.
4. Upsert a batch of 500 rows from a seed file, using (guardian_id, expires_at) as the unique columns. Enable DB::enableQueryLog() around the call and read count(DB::getQueryLog()): it should be 1.
5. Soft-delete one row, read it with withTrashed(), restore it, then forceDelete it. Count rows at each step.
6. Add Prunable to the model with a prunable() method that returns rows whose expires_at is more than a day old, and schedule model:prune --model=App\Models\GuardianOtpLog daily in routes/console.php.

The self-check below asks about strict mode, upserts, soft deletes, keys and pruning, starting with the idea you answer least well, and explains every answer:

Interview questions

Warm-up (fresher): why does strict mode belong in development and not on the production site?

Because the guards are there to make a developer see a slip early, at the first slow page or the first odd row on a laptop, not to break a live site that has run with a lazy-loaded relation or a stray array key for months. In development each exception is a one-line fix: eager-load with with(), add the key to Fillable, or add the column to the select(). In production the same exception would be an error page a visitor gets instead of the page they asked for. So the usual line is Model::shouldBeStrict(! $this->app->isProduction()): on everywhere except production. The test suite runs with the guards on as well, so most slips are found and fixed before a deploy, while production keeps the default behaviour.

Two longer questions grow out of the Fillable list and the ULID key above. Sketch how you would open each answer before you read the opening step written for it:

Key takeaways

• A model names one row of a table, and its Fillable list is the column boundary for an array that came from outside, so a request can never write a column no form offered.
• Model::shouldBeStrict() turns three default behaviours into exceptions in development: lazy loading inside a loop, writing an array key the model has not declared, and reading a column the query did not select.
• firstOrCreate, updateOrCreate and upsert write one row, one row and many rows respectively, and all three need a matching unique index to be idempotent.
• upsert($rows, $uniqueBy, $updateColumns) ran one query for 1,000 rows in the probe, which is why the import takes one trip through the driver instead of 1,000.
• SoftDeletes writes a deleted_at column instead of deleting the row; withTrashed, onlyTrashed, restore and forceDelete are the four methods that read, un-mark or really delete it.
• A UUID or ULID key is a fence that keeps the next id out of a URL; the authorization check is the lock that refuses a request from a visitor the row does not belong to.