thefeqy/laravel-model-status

A Laravel package to automate adding configurable status columns to models and migrations, and enforce user activity through middleware.

v1.5.0 2025-03-04 14:46 UTC

Requires

• php: ^8.3|^8.4
• illuminate/console: ^11.0|^12.0
• illuminate/http: ^11.0|^12.0
• illuminate/routing: ^11.0|^12.0
• illuminate/support: ^11.0|^12.0

Requires (Dev)

• laravel/pint: ^1.20
• orchestra/testbench: ^9.0
• phpunit/phpunit: ^11.0

MIT

• Muhammed Elfeqy

README

A Laravel package that simplifies status management for Eloquent models.

Table of Contents

• Features

• Installation

  • Step 1: Run the Installation Command

• Configuration

  • Using .env Variables

• Usage

  • Using the HasActiveScope Trait
  • Querying Models
  • Using Status Casting
  • Cascade Deactivation
  • Using the Middleware
  • Add Middleware to Routes

• Admin Bypass for Active Scope

• Advanced Configuration

• Testing

• Security

• Contributing

• License

Features

• HasActiveScope Trait: Automatically filters models with active status.
• Admin Bypass: Admin users can see all models, including inactive ones.
• Helper Methods: $model->status->isActive() and $model->status->isInactive().
• Dynamic Configuration: Define custom statuses & column names via .env.
• Installation Command: php artisan model-status:install for easy setup.
• PHP 8.3 Support.

Installation

You can install the package via Composer:

composer require thefeqy/laravel-model-status

Step 1: Run the Installation Command

php artisan model-status:install

This will:

• Publish the config file (config/model-status.php).
• Set up required environment variables in .env and .env.example.
• Ensure your project is ready to use the package.

Configuration

You can customize the package settings in:

config/model-status.php

return [
    'column_name' => env('MODEL_STATUS_COLUMN', 'status'),
    'default_value' => env('MODEL_STATUS_ACTIVE', 'active'),
    'inactive_value' => env('MODEL_STATUS_INACTIVE', 'inactive'),

    'admin_detector' => function () {
        return auth()->check() && auth()->user()->is_admin;
    },
];

Using .env Variables

Instead of modifying config/model-status.php, you can override values in .env:

.env

MODEL_STATUS_COLUMN=state
MODEL_STATUS_ACTIVE=enabled
MODEL_STATUS_INACTIVE=disabled

Now, the package will automatically adapt to your setup.

Usage

Using the HasActiveScope Trait

To enable status management in a model:

use Thefeqy\ModelStatus\Traits\HasActiveScope;

class Product extends Model
{
    use HasActiveScope;

    protected $fillable = ['name'];
}

Now, inactive models are automatically excluded from queries.

Querying Models

Get Active Models (Default Behavior)

$activeProducts = Product::all(); // Returns only active products

Get All Models (Including Inactive)

$allProducts = Product::inActive()->get();

Manually Activating / Deactivating a Model

$product = Product::find(1);

$product->activate(); // Set status to "active"
$product->deactivate(); // Set status to "inactive"

Checking a Model's Status

if ($product->status->isActive()) {
    echo "Product is active!";
}

if ($product->status->isInactive()) {
    echo "Product is inactive!";
}

Using Status Casting

To ensure status is always cast to a Status object, use the StatusCast class.

Apply Status Casting in Models

use Thefeqy\ModelStatus\Casts\StatusCast;

class Product extends Model
{
    use HasActiveScope;

    protected $fillable = ['name', 'status', 'category_id'];

    protected $casts = [
        'status' => StatusCast::class,
    ];
}

Example Usage

$product = Product::find(1);

if ($product->status->isActive()) {
    echo "Product is active!";
}

Now, $product->status is an instance of Status, allowing method calls like isActive() and isInactive().

Cascade Deactivation

If a model is deactivated, its related models can also be automatically deactivated.

Example

class Category extends Model
{
    use HasActiveScope;

    protected $fillable = ['name', 'status'];

    protected array $cascadeDeactivate = ['products'];

    public function products()
    {
        return $this->hasMany(Product::class);
    }
}

Now, deactivating a category will also deactivate all products under it:

$category = Category::find(1);
$category->deactivate();

Using the Middleware

The package includes the EnsureAuthenticatedUserIsActive middleware, which enforces that only users with an active status can access certain routes.

Add Middleware to Routes

Instead of registering a string alias for the middleware, you can reference it by class name in your route definition:

use Illuminate\Support\Facades\Route;
use Thefeqy\ModelStatus\Middleware\EnsureAuthenticatedUserIsActive;

Route::middleware(['auth', EnsureAuthenticatedUserIsActive::class])->group(function () {
    Route::get('/dashboard', function () {
        return 'Welcome to your dashboard!';
    });
});

Admin Bypass for Active Scope

By default, admin users can see inactive models.

This behavior is controlled in config/model-status.php:

'admin_detector' => function () {
    return auth()->check() && auth()->user()->is_admin;
},

Advanced Configuration

If you need a different column name or status values, update .env:

MODEL_STATUS_COLUMN=state
MODEL_STATUS_ACTIVE=enabled
MODEL_STATUS_INACTIVE=disabled

Now, models will use:

$table->string('state', 10)->default('enabled');

instead of:

$table->string('status', 10)->default('active');

Testing

Run tests using Pest PHP:

composer test
or
vendor/bin/phpunit

Security

If you discover a security vulnerability, please report it via email: 📩 [e-mail]

Contributing

Want to improve this package? Check out CONTRIBUTING for contribution guidelines.

License

This package is open-source software licensed under the MIT License.