yiisoft/rbac-db

Yii RBAC Database storage

2.0.0 2024-03-07 10:54 UTC

This package is auto-updated.

Last update: 2024-03-07 10:56:30 UTC


README

yiisoft.png

Yii RBAC Database


The package provides Yii Database storage for Yii RBAC.

Latest Stable Version Total Downloads Build status codecov Mutation testing badge static analysis type-coverage

Detailed build statuses:

RDBMS Status
SQLite SQLite status
MySQL MYSQL status
PostgreSQL MYSQL status
Microsoft SQL Server MYSQL status
Oracle MYSQL status

Requirements

  • PHP 8.1 or higher.
  • PDO PHP extension.
  • One of the following drivers:
  • PDO PHP extension for the selected driver.
  • In the case of using with SQL Server, a minimal required version of PDO is 5.11.1.

Installation

The package could be installed with composer:

composer require yiisoft/rbac-db

General usage

Configuring database connection

Configuration depends on a selected driver. Here is an example for PostgreSQL:

use Yiisoft\Cache\ArrayCache; // Requires https://github.com/yiisoft/cache
use Yiisoft\Db\Cache\SchemaCache;
use Yiisoft\Db\Pgsql\Connection;
use Yiisoft\Db\Pgsql\Driver;

$pdoDriver = new Driver('pgsql:host=127.0.0.1;dbname=yiitest;port=5432', 'user', 'password');
$pdoDriver->charset('UTF8');
$connection = Connection(
    $pdoDriver, 
    new SchemaCache(
        new ArrayCache(), // Any other PSR-16 compatible cache can be used.
    )
);

More comprehensive examples can be found at Yii Database docs.

Working with migrations

This package uses Yii DB Migration for managing database tables required for storages. There are three tables in total (yii_rbac_ prefix is used).

Items storage:

  • yii_rbac_item.
  • yii_rbac_item_child.

Assignments storage:

  • yii_rbac_assignment.

Configuring migrations

Make sure to include these directories as source paths:

When using Yii Console, add this to config/params.php:

'yiisoft/db-migration' => [
    // ...
    'sourcePaths' => [
        dirname(__DIR__) . '/vendor/yiisoft/rbac-db/migrations/items',
        dirname(__DIR__) . '/vendor/yiisoft/rbac-db/migrations/assignments',
    ],
],

and database connection configuration from previous section to DI container (config/common/db.php):

<?php

declare(strict_types=1);

use Yiisoft\Db\Connection\ConnectionInterface;
use Yiisoft\Db\Pgsql\Connection as PgsqlConnection;

return [
    ConnectionInterface::class => [
        'class' => PgsqlConnection::class,
        '__construct()' => [
            // ...
        ],
    ]
];

Because item and assignment storages are completely independent, migrations are separated as well to prevent the creation of unused tables. So, for example, if you only want to use assignment storage, add only migrations/assignments to source paths.

Other ways of using migrations are covered here.

Applying migrations

Using with Yii Console:

./yii migrate:up

Other ways of using migrations are covered here.

Reverting migrations

Using with Yii Console:

./yii migrate:down --limit=2

Other ways of using migrations are covered here.

Using storages

The storages are not intended to be used directly. Instead, use them with Manager from Yii RBAC package:

use Yiisoft\Db\Connection\ConnectionInterface;
use Yiisoft\Rbac\Db\AssignmentsStorage;
use Yiisoft\Rbac\Db\ItemsStorage;
use Yiisoft\Rbac\Db\TransactionalManagerDecorator;
use Yiisoft\Rbac\Manager;
use Yiisoft\Rbac\Permission;
use Yiisoft\Rbac\RuleFactoryInterface;

/** @var ConnectionInterface $database */
$itemsStorage = new ItemsStorage($database);
$assignmentsStorage = new AssignmentsStorage($database);
/** @var RuleFactoryInterface $rulesContainer */
$manager = new TransactionalManagerDecorator(
    new Manager(
        itemsStorage: $itemsStorage, 
        assignmentsStorage: $assignmentsStorage,
        // Requires https://github.com/yiisoft/rbac-rules-container or another compatible factory.
        ruleFactory: $rulesContainer,
    ),
);
$manager->addPermission(new Permission('posts.create'));

Note wrapping manager with decorator—it additionally provides database transactions to guarantee data integrity.

Note that it's not necessary to use both DB storages. Combining different implementations is possible. A quite popular case is to manage items via PHP files while storing assignments in a database.

More examples can be found in Yii RBAC documentation.

Syncing storages manually

The storages stay synced thanks to manager, but there can be situations where you need to sync them manually. One of them is using combination with PHP file based storage and editing it manually.

Let's say PHP file is used for items, while database - for assignments, and some items were deleted:

return [
    [
        'name' => 'posts.admin',        
        'type' => 'role',        
        'created_at' => 1683707079,
        'updated_at' => 1683707079,
        'children' => [
            'posts.redactor',
            'posts.delete',
            'posts.update.all',
        ],
    ],
-   [
-       'name' => 'posts.redactor',
-       'type' => 'role',        
-       'created_at' => 1683707079,
-       'updated_at' => 1683707079,
-       'children' => [
-           'posts.viewer',
-           'posts.create',
-           'posts.update',
-       ],
-   ],
    [
        'name' => 'posts.viewer',
        'type' => 'role',        
        'created_at' => 1683707079,
        'updated_at' => 1683707079,
        'children' => [
            'posts.view',
        ],
    ],
    [
        'name' => 'posts.view',
        'type' => 'permission',        
        'created_at' => 1683707079,
        'updated_at' => 1683707079,
    ],
    [
        'name' => 'posts.create',
        'type' => 'permission',        
        'created_at' => 1683707079,
        'updated_at' => 1683707079,
    ],
-   [
-       'name' => 'posts.update',
-       'rule_name' => 'is_author',
-       'type' => 'permission',
-       'created_at' => 1683707079,
-       'updated_at' => 1683707079,
-   ],
    [
        'name' => 'posts.delete',        
        'type' => 'permission',        
        'created_at' => 1683707079,
        'updated_at' => 1683707079,
    ],
    [
        'name' => 'posts.update.all',
        'type' => 'permission',        
        'created_at' => 1683707079,
        'updated_at' => 1683707079,
    ],
];

Then related entries in other storage needs to be deleted as well. This can be done within a migration:

use Yiisoft\Db\Migration\MigrationBuilder;
use Yiisoft\Db\Migration\RevertibleMigrationInterface;
use Yiisoft\Db\Migration\TransactionalMigrationInterface;

final class M240229184400DeletePostUpdateItems implements RevertibleMigrationInterface, TransactionalMigrationInterface
{
    private const TABLE_PREFIX = 'yii_rbac_';
    private const ASSIGNMENTS_TABLE = self::TABLE_PREFIX . 'assignment';
    
    public function up(MigrationBuilder $b): void
    {
        $b
            ->getDb()
            ->createCommand()
            ->delete(self::ASSIGNMENTS_TABLE, ['item_name' => ['posts.redactor', 'posts.update']])
            ->execute();
    }
    
    public function down(MigrationBuilder $b): void; 
    {        
    }   
}

Testing

Unit testing

The package is tested with PHPUnit. To run tests:

./vendor/bin/phpunit

Mutation testing

The package tests are checked with Infection mutation framework. To run it:

./vendor/bin/infection

Static analysis

The code is statically analyzed with Psalm. To run static analysis:

./vendor/bin/psalm