yiisoft/rbac-cycle-db

Yii RBAC Cycle Database storage

2.0.0 2023-04-20 10:50 UTC

Requires

• php: ^8.0
• cycle/database: ^2.1
• symfony/console: ^5.3|^6.0
• yiisoft/rbac: ^1.0.2

Requires (Dev)

• ext-pdo_sqlite: *
• maglnet/composer-require-checker: ^4.3
• phpunit/phpunit: ^9.5
• rector/rector: ^0.15.0
• roave/infection-static-analysis-plugin: ^1.25
• spatie/phpunit-watcher: ^1.23
• vimeo/psalm: ^4.30|^5.2

BSD-3-Clause

• storage
• yii
• rbac
• cycle
• cycle-db

README

Yii RBAC Cycle Database

The package provides Cycle Database storage for Yii RBAC.

Requirements

• PHP 8.0 or higher.
• In case of using with SQLite, minimal required version is 3.8.3.

Installation

The package could be installed with composer:

composer require yiisoft/rbac-cycle-db

General usage

Configuring database connection

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

use Cycle\Database\Config\DatabaseConfig;
use Cycle\Database\Config\Postgres\DsnConnectionConfig;
use Cycle\Database\Config\PostgresDriverConfig;
use Cycle\Database\DatabaseManager;

$dbConfig = new DatabaseConfig(
    [
        'default' => 'default',
        'databases' => [
            'default' => ['connection' => 'pgsql'],
        ],
        'connections' => [
            'pgsql' => new PostgresDriverConfig(new DsnConnectionConfig(
                'pgsql:host=127.0.0.1;dbname=yiitest;port=5432',
                'user',
                'password',
            )),
        ],
    ]
);
$database = (new DatabaseManager($dbConfig))->database();

More comprehensive examples can be found at Cycle Database docs.

Working with schema

In order to keep less dependencies, this package doesn't provide any CLI for working with schema. There are multiple options to choose from:

• Use migration tool like Yii DB Migration. Migrations are dumped as plain SQL in sql/migrations folder.
• Without migrations, DbSchemaManager class can be used. An example of CLI command containing it can be found here.
• Use plain SQL that is actual at the moment of installing rbac-db package (located at the root of sql folder).

The structure of plain SQL files:

• pgsql-up.sql - apply the changes for PostgreSQL driver.
• pgsql-down.sql - revert the changes for PostgreSQL driver.

Plain SQL assumes using default names for all 3 tables (yii_rbac_ prefix is used):

• yii_rbac_item.
• yii_rbac_assignment.
• yii_rbac_item_child.

DbSchemaManager allows to customize table names:

use Yiisoft\Db\Connection\ConnectionInterface;
use Yiisoft\Rbac\Db\DbSchemaManager;

/** @var ConnectionInterface $database */
$schemaManager = new DbSchemaManager(
    database: $database,
    itemsTable: 'custom_items',
    assignmentsTable: 'custom_assignments',    
    itemsChildrenTable: 'custom_items_children',
);
$schemaManager->ensureTables();
$schemaManager->ensureNoTables(); // Note: All existing data will be erased.

Using storages

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

use Cycle\Database\DatabaseInterface;
use Yiisoft\Rbac\Cycle\AssignmentsStorage;
use Yiisoft\Rbac\Cycle\ItemsStorage;
use Yiisoft\Rbac\Cycle\TransactionalManagerDecorator;
use Yiisoft\Rbac\Manager;
use Yiisoft\Rbac\Permission;
use Yiisoft\Rbac\RuleFactoryInterface;

/** @var DatabaseInterface $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 other 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 store assignments in database.

More examples can be found in Yii RBAC documentation.

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