Scopes

Scopes define reusable conditions that limit resource access.

Overview

A scope compares a field on the entity with a field on the user to determine access.

Built-in scope pattern

The basic scope pattern:

entity.{entity_field} === user.{user_field}

Creating scopes

1. Go to /admin/auth/scopes.
2. Click Add Scope.
3. Enter:
   • Name — identifier (e.g. own, team, department)
   • Description — what this scope does
   • Entity Field — field on the entity to check
   • User Field — field on the user to compare

Common scopes

Name	Entity Field	User Field	Description
own	user_id	id	User owns the entity
team	team_id	team_id	User is on same team
department	department_id	department_id	User is in same department
company	company_id	company_id	User is in same company

Database schema

CREATE TABLE tinyauth_scopes (
    id INT AUTO_INCREMENT PRIMARY KEY,
    name VARCHAR(50) NOT NULL UNIQUE,
    description VARCHAR(200),
    entity_field VARCHAR(100) NOT NULL,
    user_field VARCHAR(100) NOT NULL,
    created DATETIME,
    modified DATETIME
);

Using scopes

When assigning resource permissions, you can optionally attach a scope:

Role	Ability	Scope	Effect
user	edit	own	Can edit own articles
moderator	edit	(none)	Can edit all articles
user	view	(none)	Can view all articles

Scope evaluation

// Scope: own
// entity_field: user_id
// user_field: id

// For an Article entity and a User identity:
$canAccess = $article->user_id === $user->id;

Advanced: custom scope logic

For complex conditions not covered by field comparison, extend the scope evaluation in your policy:

public function canEdit(IdentityInterface $user, Article $article): bool
{
    $service = new TinyAuthService();

    // Check base permission with scope
    if ($service->canAccessResource($user, $article, 'edit')) {
        return true;
    }

    // Custom logic: editors can edit unpublished articles
    if ($user->role === 'editor' && !$article->is_published) {
        return true;
    }

    return false;
}

Programmatic scope management

$scopesTable = $this->fetchTable('TinyAuthBackend.Scopes');

// Create a new scope
$scope = $scopesTable->newEntity([
    'name' => 'organization',
    'description' => 'Same organization as user',
    'entity_field' => 'organization_id',
    'user_field' => 'organization_id',
]);
$scopesTable->save($scope);

// Find scope by name
$ownScope = $scopesTable->find()
    ->where(['name' => 'own'])
    ->first();

Scope resolution

When checking permissions with a scope:

use TinyAuthBackend\Service\TinyAuthService;

$service = new TinyAuthService();

// This checks:
// 1. Does the user's role have 'edit' ability on the Article resource?
// 2. If a scope is attached, does the entity match the scope condition?
$canEdit = $service->canAccessResource($user, $article, 'edit');

Best practices

Keep scopes small

1. Keep scopes simple — one condition per scope.
2. Use descriptive names — own, team, not scope1.
3. Document scopes — clear descriptions help administrators.
4. Test scope conditions — verify field names are correct.
5. Handle null fields — consider what happens if entity_field is null.