README

Configurable district-based query scoping and access control for Laravel applications.

Requirements

PHP 8.1+
Laravel 10, 11, 12, or 13
illuminate/contracts, illuminate/database, and illuminate/support

Installation

composer require boss/laravel-district-access

Laravel package discovery registers the service provider automatically.

Publish configuration:

php artisan vendor:publish --tag=district-access-config

Basic usage

use Boss\DistrictAccess\Facades\DistrictAccess;
use Illuminate\Support\Facades\DB;

$query = DB::table('vendors');

DistrictAccess::apply($query, 'district');

$vendors = $query->get();

The service returns the query unchanged for a configured super admin. For normal users it adds a whereIn for their allowed districts. By default, a normal user with no districts receives a query that can return no rows (1 = 0).

Configuration

The default configuration assumes a user property named district_role containing either a comma-separated string or an array. This is only a default: applications can replace the resolver callbacks.

return [
    'user_resolver' => static fn () => auth()->user(),

    'districts_resolver' => static function ($user): array {
        return explode(',', $user->district_role ?? '');
    },

    'super_admin_resolver' => static fn ($user): bool => (int) $user->id === 1,

    'deny_without_districts' => true,
    'deny_raw_condition' => '1 = 0',
];

For applications using a custom session-based user lookup, configure user_resolver in the application's published config instead of changing the package.

Dependency injection

use Boss\DistrictAccess\Contracts\DistrictAccessContract;

public function index(DistrictAccessContract $districtAccess)
{
    $query = DB::table('vendors');

    $districtAccess->apply($query, 'district');

    return $query->paginate(10);
}

Middleware

The package registers this middleware alias:

district.access

Use it on routes when the endpoint requires a resolved authenticated district-access user:

Route::middleware('district.access')->group(function () {
    // protected routes
});

This middleware does not perform query filtering itself. It only ensures that the package can resolve an authenticated user. Query scoping should be explicitly applied to every relevant query.

Security model

This package follows deny-by-default behavior for normal users with no assigned districts. Super-admin behavior is delegated to the configurable resolver. Never rely on a controller-only filter if sensitive records can be accessed through another endpoint; apply the scope at every data access boundary or introduce your own repository/query abstraction.

Testing

composer install
composer validate --strict
composer test

Versioning

Use semantic version tags:

git tag v1.0.0
git push origin v1.0.0

Do not add a version field to composer.json; Packagist detects package versions from VCS tags.

Publishing to Packagist

Push this repository to a public GitHub repository.
Run composer validate --strict.
Create a release tag such as v1.0.0.
Submit the public repository URL on Packagist.
Packagist will crawl the repository and detect future VCS tags.

License

MIT.

boss / laravel-district-access

Package info

Security

Statistics