Forem: Abdullah Sowailem

FieldGuard Dynamic Field-Level Security for Laravel

Abdullah Sowailem — Mon, 02 Feb 2026 13:13:28 +0000

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.

Features

Database-Driven Rules: Create and manage security rules in the database for runtime configuration.
Non-Intrusive: No traits, base classes, or attributes required for your models.
Automatic Enforcement: Optionally enforce security via model events (retrieved, saving) without any code changes.
Read & Write Protection: Separate rules for viewing and updating fields.
Data Masking: Automatically mask sensitive fields (e.g., ***-***-***).
Middleware Integration: Automatically filter unauthorized fields from incoming requests.
Caching: Performance-optimized with Laravel cache support for database rules.
No-Code Friendly: Centralized control without altering your core models.

Installation

composer require sowailem/fieldguard

Run the migrations to create the rules table:

php artisan migrate

Usage

1. Creating Security Rules

All field-level permissions are managed through the field_guard_rules table. You can use the FieldGuardRule model to create rules.

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,
]);

Rule Structure

model_class: Fully qualified class name of the Eloquent model.
field_name: The name of the attribute to secure.
read_policy: (Optional) Permission for viewing the field. Can be a string or JSON object.
write_policy: (Optional) Permission for creating or updating the field. Can be a string or JSON object.
mask: (Optional) Value to return if read permission is denied (instead of removing the field).
is_active: Boolean to enable/disable the rule (defaults to true).

Policy Types

Policies can be:

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

2. Enforcing Security

Automatic Enforcement (Global)

You can enable automatic enforcement for all models by setting automatic_enforcement to true in your config/fieldguard.php. This uses Eloquent events to filter fields automatically.

'automatic_enforcement' => true,

Read: Automatically hides or masks fields when a model is retrieved from the database.
Write: Automatically prevents unauthorized fields from being saved (reverts to original values).

Manual Enforcement (Read)

Use the FieldGuard facade to filter model attributes. This is useful in controllers or API resources.

use Sowailem\FieldGuard\Facades\FieldGuard;

public function view(User $user)
{
    // Returns the model attributes as an array, filtered by security rules
    return FieldGuard::apply($user, auth()->user());
}

API Resource Integration

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

Automatic Enforcement (Middleware - Write)

// Laravel 11+ example in bootstrap/app.php
->withMiddleware(function (Middleware $middleware) {
    $middleware->alias([
        'fieldguard' => \Sowailem\FieldGuard\Middleware\EnforceFieldSecurityMiddleware::class,
    ]);
})

Apply it to routes to filter request data before it reaches your controller:

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 logic.

3. Caching

Database rules are cached for performance. By default, they are cached using the tag fieldguard:rules (configurable in config/fieldguard.php). When you update rules via the provided FieldGuardRuleRepository, the cache is automatically cleared.

You can also manually clear the cache:

php artisan fieldguard:clear-cache

4. Custom Policy Resolvers

If you need custom logic for interpreting database policies (e.g., integrating with a specific RBAC system), implement the PolicyResolver interface and register it in config/fieldguard.php.

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 here
        return true;
    }
}

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

5. Seeding Initial Rules

The package includes a seeder example to help you bootstrap rules. You can publish and run the seeder or use the provided example:

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

6. Administrative API

FieldGuard comes with built-in RESTful API endpoints for managing security rules.

GET /field-guard/rules – List all rules (supports pagination and filtering)
POST /field-guard/rules – Create a new rule
GET /field-guard/rules/{id} – View a specific rule
PUT/PATCH /field-guard/rules/{id} – Update an existing rule
DELETE /field-guard/rules/{id} – Delete a rule

Configuration

You can customize the API prefix and middleware in config/fieldguard.php:

'api' => [
    'enabled' => true,
    'prefix' => 'field-guard',
    'middleware' => ['api', 'auth:sanctum'],
],

Authorization

The API uses a gate named manage-field-guard to authorize requests. Ensure you define this gate in your AuthServiceProvider or AppServiceProvider:

use Illuminate\Support\Facades\Gate;

Gate::define('manage-field-guard', function ($user) {
    return $user->isAdmin(); // Your authorization logic
});

Publishing Routes

If you want to customize the routes, you can publish them:

php artisan vendor:publish --tag="fieldguard-routes"

Then disable the automatic loading in config/fieldguard.php and manually register them in your routes/api.php.

Testing

vendor/bin/phpunit

License

The MIT License (MIT). Please see License File for more information.

Laravel Ownable — A Smart Solution for Polymorphic Ownership

Abdullah Sowailem — Tue, 12 Aug 2025 17:36:52 +0000

Introduction: Why Ownership Management Matters

Ownership logic—where one model "owns" another—is ubiquitous in web apps: task assignments, document custody, product sellers, and delegated resources. While Laravel makes modeling relationships easy, it doesn't provide a simple, reusable pattern for robust ownership management, ownership transfer, and history tracking.

Laravel Ownable fills that gap by offering a minimal, consistent API that lets any Eloquent model act as an owner or be owned (polymorphic), while providing convenient methods and a facade for everyday ownership operations.

What Is Laravel Ownable?

Laravel Ownable is a lightweight package that enables polymorphic ownership between Eloquent models. You get:

Polymorphic ownership — any model can own any other model.
Fluid, expressive methods for assigning, checking, and transferring ownership.
An easy-to-use facade for centralized actions.
A foundation you can extend for auditing, events, and bulk operations.

Project docs: sowailem.github.io/Ownable

Key Features

Polymorphism: Model A can own Model B, or Model C — no rigid owner types.
Convenience API: Methods like giveOwnershipTo, ownedBy, owns, etc.
Facade: Use a central Owner facade for consistent calls.
Extendable: Add audit logs, events, or bulk operations on top of the package.

Installation Guide

Quick install steps — make sure your project uses PHP 8+ and a supported Laravel version (9–12):

composer require sowailem/ownable

php artisan vendor:publish --provider="Sowailem\Ownable\OwnableServiceProvider" --tag="ownable-migrations"

php artisan migrate

After migration you'll have the tables required by the package (see docs for exact schema).

Getting Hands-On: Example Usage

Below are typical steps to make a User an owner and Post an ownable entity.

Model Setup

// app/Models/User.php

use Sowailem\Ownable\Traits\HasOwnables;

use Sowailem\Ownable\Contracts\Owner as OwnerContract;

class User extends Model implements OwnerContract {

    use HasOwnables;

}

// app/Models/Post.php

use Sowailem\Ownable\Traits\IsOwnable;

use Sowailem\Ownable\Contracts\Ownable as OwnableContract;

class Post extends Model implements OwnableContract {

    use IsOwnable;

}

Assigning & Checking Ownership

// Assign ownership

$user->giveOwnershipTo($post);

$post->ownedBy($user);

// Or use the facade

Owner::give($user, $post);


// Check ownership


if ($user->owns($post)) {


    // do something


}


if ($post->isOwnedBy($user)) {


    // do something else


}


Owner::check($user, $post); // returns boolean

Transfer Ownership

Transferring ownership is a simple combination of revoke and give actions (or provided transfer helper if package supports it). Example:

// Example transfer


$oldOwner->revokeOwnershipOf($post);


$newOwner->giveOwnershipTo($post);

Real-World Use Cases

Task management systems: Assign, reassign and audit tasks across team members.
Marketplaces & e-commerce: Sellers own product listings; transfer ownership on sales or administrative actions.
Document management: Track custody of documents through reviews and approvals.
Multi-tenant platforms: Map ownership to organizations, teams, or users for access and billing.

Advanced Ideas & Best Practices

The package offers a strong base. Here are suggested extensions and practices to make ownership production-ready:

Ownership History: Keep an audit table to record every assigned, revoked, and transferred event. This is invaluable for debugging and compliance.
Events & Listeners: Fire events like OwnershipAssigned and OwnershipTransferred so other systems (notifications, webhooks, analytics) can react.
Bulk/Batched Transfers: For mass migrations, use queued jobs or bulk DB operations to avoid timeouts and keep data consistent.
Soft Deletes: Decide how soft-deleted owners/ownables should behave. Consider cascading ownership or reassigning automatically.
Testing: Create unit tests for common flows: give, revoke, transfer, and permission checks.

Implementation Tips & Gotchas

Be explicit about ownership uniqueness: can multiple owners own the same resource? If not, enforce DB constraints or app logic.
Design your UI to confirm transfers and explain consequences (especially for destructive operations).
When integrating with permissions, separate "ownership" from "authorization": owning a resource is not automatically equivalent to having all permissions over it unless you design it so.

Why Developers Should Care

Adopting Laravel Ownable reduces boilerplate and enforces a standard ownership pattern across projects. It helps teams move faster, reduces bugs around ownership logic, and creates a clear place to extend for audits, reports, and business rules.

Quick checklist to adopt Ownable in your project

Install and migrate the package.
Annotate Owner and Ownable models with the provided traits & contracts.
Write tests for ownership actions (give, check, revoke, transfer).
Optionally add events & an audit table for history.
Document ownership semantics in your codebase README.

Final Thoughts

Laravel Ownable solves a recurring problem in application design: mapping and managing ownership relationships. It's intentionally minimal and approachable, and it's a great base to build richer ownership features (audit, events, bulk operations). If you want a consistent, testable, and reusable ownership layer across your Laravel apps, Ownable is worth trying.