Introduction

FieldGuard is a lightweight, non-intrusive Laravel package for field-level security on Eloquent models. It allows you to control which users can view or modify specific attributes using dynamic, database-driven rules.

Installation

Install the package via composer:

composer require sowailem/fieldguard

Run the migrations to create the required field_guard_rules table:

php artisan migrate

The FieldGuard Class

The Sowailem\FieldGuard\FieldGuard class is the heart of the package. It handles rule resolution, permission checking, and attribute filtering.

Security Rules

FieldGuard relies on rules created in the database. You can manage these rules using the FieldGuardRule model.

use Sowailem\FieldGuard\Models\FieldGuardRule;

FieldGuardRule::create([
    'model_class' => 'App\Models\User',
    'field_name' => 'salary',
    'read_policy' => ['roles' => ['admin', 'hr'], 'allow_self' => true],
    'write_policy' => ['roles' => ['admin']],
    'mask' => 'PROTECTED',
    'is_active' => true,
]);

Policy Types

Policies can be defined in multiple formats to suit your needs:

• Gate Name: Use any Laravel Gate name (e.g., 'view-salary').
• 'self': Allows access if the user's ID matches the model's primary key.
• 'role:name': Requires a specific role (expects a hasRole($role) method on the User model).
• 'true' / 'false': Strings that always allow or always deny access.
• JSON Array: For complex logic (e.g., {"roles": ["admin"], "allow_self": true, "gate": "extra-check"}).

Manual Enforcement (Read)

Use the FieldGuard facade to manually filter model attributes. This is perfect for controllers.

use Sowailem\FieldGuard\Facades\FieldGuard;

public function view(User $user)
{
    // Returns filtered attributes array
    return FieldGuard::apply($user, auth()->user());
}

API Resource Integration

The best way to use FieldGuard is within your API resources.

namespace App\Http\Resources;

use Illuminate\Http\Resources\Json\JsonResource;
use Sowailem\FieldGuard\Facades\FieldGuard;

class UserResource extends JsonResource
{
    public function toArray($request)
    {
        return FieldGuard::apply($this->resource, $request->user());
    }
}

Automatic Global Enforcement

FieldGuard can automatically enforce security rules across all models using Eloquent events. This eliminates the need for manual facade calls or traits.

Configuration

Enable it in config/fieldguard.php:

'automatic_enforcement' => true,

Automatic Middleware Enforcement (Write)

Register the middleware to automatically filter incoming request data before it reaches your controller logic.

Laravel 11+ (bootstrap/app.php)

->withMiddleware(function (Middleware $middleware) {
    $middleware->alias([
        'fieldguard' => \Sowailem\FieldGuard\Middleware\EnforceFieldSecurityMiddleware::class,
    ]);
})

Apply to Routes

Route::put('/users/{user}', [UserController::class, 'update'])
    ->middleware('fieldguard:App\Models\User');

The middleware will automatically remove unauthorized fields from $request->all() before they reach your controller.

API Endpoints

FieldGuard provides a set of RESTful API endpoints to manage security rules dynamically from your frontend or administrative dashboard.

GET /field-guard/rules

{
    "data": [
        {
            "id": 1,
            "model_class": "App\\Models\\User",
            "field_name": "salary",
            "read_policy": { "roles": ["hr"] },
            "write_policy": { "roles": ["admin"] },
            "mask": "CONFIDENTIAL",
            "is_active": true
        }
    ]
}

POST /field-guard/rules

{
    "model_class": "App\\Models\\Product",
    "field_name": "cost_price",
    "read_policy": ["admin"],
    "write_policy": ["super-admin"],
    "mask": null,
    "is_active": true
}

PUT /field-guard/rules/{id}

{
    "is_active": false,
    "mask": "HIDDEN"
}

DELETE /field-guard/rules/{id}

Detailed Usage Scenarios

FieldGuardRule::create([
    'model_class' => 'App\Models\User',
    'field_name' => 'salary',
    'read_policy' => ['roles' => ['hr'], 'allow_self' => true],
    'write_policy' => ['roles' => ['super-admin']],
    'mask' => 'CONFIDENTIAL'
]);

FieldGuardRule::create([
    'model_class' => 'App\Models\Product',
    'field_name' => 'wholesale_price',
    'read_policy' => 'role:b2b-customer',
    'mask' => null // Field will be removed from array
]);

FieldGuardRule::create([
    'model_class' => 'App\Models\Transaction',
    'field_name' => 'status',
    'write_policy' => ['gate' => 'update-transaction-status'],
]);

Caching & Performance

Database rules are cached forever to ensure maximum performance. The cache is automatically cleared when you use the FieldGuardRuleRepository to manage rules.

You can manually clear the cache via Artisan:

php artisan fieldguard:clear-cache

The cache tag can be configured in config/fieldguard.php.

Custom Policy Resolvers

Implement PolicyResolver for custom logic (e.g., integrating with Spatie Permissions).

namespace App\Security;

use Sowailem\FieldGuard\Contracts\PolicyResolver;
use Illuminate\Database\Eloquent\Model;

class MyCustomResolver implements PolicyResolver
{
    public function resolve(array $policy, Model $model, $user): bool
    {
        // Your custom logic for array policies
        return true; 
    }
}

Register in config/fieldguard.php:

'resolver' => \App\Security\MyCustomResolver::class,

Seeding Rules

Bootstrap your security rules using the provided seeder:

php artisan db:seed --class="Sowailem\FieldGuard\Database\Seeders\FieldGuardRuleSeeder"