🔄 Understanding Soft Deletes in CodeIgniter 4 Models (With Examples)

In modern applications, it’s often safer to hide data rather than delete it permanently. This is where Soft Deletes come into play. CodeIgniter 4 makes this easy by integrating soft delete functionality directly into its Model layer.

In this post, we’ll explore how to enable soft deletes in your models, retrieve deleted records, restore or purge them, and some common gotchas.

🧩 What Are Soft Deletes?

Instead of removing a database row with a DELETE statement, a soft delete sets a timestamp in a deleted_at column. This allows the row to remain in the database while appearing deleted to the application.

⚙️ Step 1: Enable Soft Deletes in Your Model

namespace App\Models;

use CodeIgniter\Model;

class BrandModel extends Model
{
    protected $table            = 'brands';
    protected $primaryKey       = 'id';
    protected $useSoftDeletes   = true;
    protected $allowedFields    = ['name', 'order_id'];
    protected $useTimestamps    = true;
    protected $deletedField     = 'deleted_at'; // defaults to 'deleted_at'
}

• ✅ useSoftDeletes = true enables soft deletion.
• ✅ deletedField specifies the column that tracks deletion.

🗑️ Soft Deleting a Record

$brandModel = new \App\Models\BrandModel();
$brandModel->delete(5); // soft delete

SQL generated:

UPDATE brands SET deleted_at = NOW() WHERE id = 5

🔎 Retrieving Non-Deleted Records (Default Behavior)

$activeBrands = $brandModel->findAll(); // excludes soft-deleted rows

📦 Retrieving Soft-Deleted Records

To include soft-deleted records:

$allBrands = $brandModel->withDeleted()->findAll();

To retrieve only soft-deleted records:

$deletedBrands = $brandModel->onlyDeleted()->findAll();

♻️ Restoring Soft-Deleted Records

$brandModel->update(5, ['deleted_at' => null]);

Or use the query builder:

$db = \Config\Database::connect();
$db->table('brands')->where('id', 5)->update(['deleted_at' => null]);

☠️ Purging (Permanently Deleting) Soft-Deleted Records

To permanently remove a record:

$brandModel->delete(5, true); // true = purge delete

To purge multiple records with a condition:

$brandModel->withDeleted()
           ->where('status', 'archived')
           ->delete(null, true);

⚠️ Common Mistake: Using purgeDeleted()

CodeIgniter 4 does not have a method called purgeDeleted(). Instead, use:

delete(null, true);

🔍 Summary of Key Methods

🧠 Final Thoughts

Soft deletes are a powerful way to protect your data and avoid accidental loss. Whether you’re building an admin panel, audit system, or simply want an undo option, CodeIgniter 4’s soft delete support is simple and effective.

Make sure you test your conditions thoroughly before purging any data permanently.