{"id":14966411,"url":"https://github.com/yiisoft/rbac-cycle-db","last_synced_at":"2025-05-07T20:12:38.907Z","repository":{"id":42446298,"uuid":"280630146","full_name":"yiisoft/rbac-cycle-db","owner":"yiisoft","description":"RBAC Cycle Database storage","archived":false,"fork":false,"pushed_at":"2025-03-25T06:19:22.000Z","size":230,"stargazers_count":17,"open_issues_count":5,"forks_count":6,"subscribers_count":15,"default_branch":"master","last_synced_at":"2025-05-07T20:12:32.647Z","etag":null,"topics":["cycle","database","hacktoberfest","rbac","spiral","yii3"],"latest_commit_sha":null,"homepage":"","language":"PHP","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"bsd-3-clause","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/yiisoft.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":".github/CONTRIBUTING.md","funding":".github/FUNDING.yml","license":"LICENSE.md","code_of_conduct":".github/CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":".github/SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null},"funding":{"open_collective":"yiisoft","github":["yiisoft"]}},"created_at":"2020-07-18T10:09:10.000Z","updated_at":"2025-03-25T06:19:26.000Z","dependencies_parsed_at":"2024-01-15T18:44:32.396Z","dependency_job_id":"93cec48d-6533-4790-ad23-6c491212068d","html_url":"https://github.com/yiisoft/rbac-cycle-db","commit_stats":{"total_commits":99,"total_committers":12,"mean_commits":8.25,"dds":0.5656565656565656,"last_synced_commit":"26b530f91f07ebf2f2a7790af0c615690b1e3161"},"previous_names":[],"tags_count":3,"template":false,"template_full_name":"yiisoft/package-template","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/yiisoft%2Frbac-cycle-db","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/yiisoft%2Frbac-cycle-db/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/yiisoft%2Frbac-cycle-db/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/yiisoft%2Frbac-cycle-db/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/yiisoft","download_url":"https://codeload.github.com/yiisoft/rbac-cycle-db/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":252949285,"owners_count":21830153,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["cycle","database","hacktoberfest","rbac","spiral","yii3"],"created_at":"2024-09-24T13:36:20.777Z","updated_at":"2025-05-07T20:12:38.886Z","avatar_url":"https://github.com/yiisoft.png","language":"PHP","funding_links":["https://opencollective.com/yiisoft","https://github.com/sponsors/yiisoft"],"categories":[],"sub_categories":[],"readme":"\u003cp align=\"center\"\u003e\n    \u003ca href=\"https://github.com/yiisoft\" target=\"_blank\"\u003e\n        \u003cimg src=\"https://yiisoft.github.io/docs/images/yii_logo.svg\" height=\"100px\" alt=\"Yii\"\u003e\n    \u003c/a\u003e\n    \u003ch1 align=\"center\"\u003eYii RBAC Cycle Database\u003c/h1\u003e\n    \u003cbr\u003e\n\u003c/p\u003e\n\n[![Latest Stable Version](https://poser.pugx.org/yiisoft/rbac-cycle-db/v)](https://packagist.org/packages/yiisoft/rbac-cycle-db)\n[![Total Downloads](https://poser.pugx.org/yiisoft/rbac-cycle-db/downloads)](https://packagist.org/packages/yiisoft/rbac-cycle-db)\n[![codecov](https://codecov.io/gh/yiisoft/rbac-cycle-db/graph/badge.svg?token=OAABFCCC7A)](https://codecov.io/gh/yiisoft/rbac-cycle-db)\n[![Mutation testing badge](https://img.shields.io/endpoint?style=flat\u0026url=https%3A%2F%2Fbadge-api.stryker-mutator.io%2Fgithub.com%2Fyiisoft%2Frbac-cycle-db%2Fmaster)](https://dashboard.stryker-mutator.io/reports/github.com/yiisoft/rbac-cycle-db/master)\n[![static analysis](https://github.com/yiisoft/rbac-cycle-db/workflows/static%20analysis/badge.svg)](https://github.com/yiisoft/rbac-cycle-db/actions?query=workflow%3A%22static+analysis%22)\n[![type-coverage](https://shepherd.dev/github/yiisoft/rbac-cycle-db/coverage.svg)](https://shepherd.dev/github/yiisoft/rbac-cycle-db)\n\nThe package provides [Cycle Database](https://github.com/cycle/database) storage for [Yii RBAC](https://github.com/yiisoft/rbac).\n\nDetailed build statuses:\n\n| RDBMS                | Status                                                                                                                                                                        |\n|----------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|\n| SQLite               | [![SQLite status](https://github.com/yiisoft/rbac-cycle-db/workflows/sqlite/badge.svg)](https://github.com/yiisoft/rbac-cycle-db/actions?query=workflow%3Asqlite)             |\n| MySQL                | [![MYSQL status](https://github.com/yiisoft/rbac-cycle-db/workflows/mysql/badge.svg)](https://github.com/yiisoft/rbac-cycle-db/actions?query=workflow%3Amysql)                |\n| PostgreSQL           | [![PostgreSQL status](https://github.com/yiisoft/rbac-cycle-db/workflows/pgsql/badge.svg)](https://github.com/yiisoft/rbac-cycle-db/actions?query=workflow%3Apgsql)           |\n| Microsoft SQL Server | [![Microsoft SQL Server status](https://github.com/yiisoft/rbac-cycle-db/workflows/mssql/badge.svg)](https://github.com/yiisoft/rbac-cycle-db/actions?query=workflow%3Amssql) |\n\n## Requirements\n\n- PHP 8.1 or higher.\n- In the case of using with SQLite, a minimal required version is 3.8.3.\n- In the case of using with SQL Server, a minimal required version of PDO is 5.11.1. \n\n## Installation\n\nThe package could be installed with composer:\n\n```shell\ncomposer require yiisoft/rbac-cycle-db\n```\n\n## General usage\n\n### Configuring database connection\n\nConfiguration depends on a selected driver. Here is an example for PostgreSQL:\n\n```php\nuse Cycle\\Database\\Config\\DatabaseConfig;\nuse Cycle\\Database\\Config\\Postgres\\DsnConnectionConfig;\nuse Cycle\\Database\\Config\\PostgresDriverConfig;\nuse Cycle\\Database\\DatabaseManager;\n\n$dbConfig = new DatabaseConfig(\n    [\n        'default' =\u003e 'default',\n        'databases' =\u003e [\n            'default' =\u003e ['connection' =\u003e 'pgsql'],\n        ],\n        'connections' =\u003e [\n            'pgsql' =\u003e new PostgresDriverConfig(new DsnConnectionConfig(\n                'pgsql:host=127.0.0.1;dbname=yiitest;port=5432',\n                'user',\n                'password',\n            )),\n        ],\n    ]\n);\n$databaseManager = new DatabaseManager($dbConfig);\n$database = $databaseManager-\u003edatabase();\n```\n\nMore comprehensive examples can be found at\n[Cycle Database docs](https://cycle-orm.dev/docs/database-configuration#declare-connection).\n\n### Working with migrations\n\nThis package uses [Cycle Migrations](https://github.com/cycle/migrations) for managing database tables required for \nstorages. There are three tables in total (`yii_rbac_` prefix is used).\n\nItems storage:\n\n- `yii_rbac_item`.\n- `yii_rbac_item_child`.\n\nAssignments storage:\n\n- `yii_rbac_assignment`.\n\n#### Configuring migrator and capsule\n\n```php\nuse Cycle\\Database\\DatabaseManager;\nuse Cycle\\Migrations\\Capsule;\nuse Cycle\\Migrations\\Config\\MigrationConfig;\nuse Cycle\\Migrations\\FileRepository;\nuse Cycle\\Migrations\\Migrator;\n\n$migrationsSubfolders = ['items', 'assignments'];\n$directories = array_map(\n    static fn (): string =\u003e dirname(__DIR__. 2),  \"/vendor/yiisoft/rbac-cycle-db/migrations/$subfolder\",\n    $migrationsSubfolders, \n);\n$config = new MigrationConfig([\n    'directory' =\u003e $directories[0],\n    // \"vendorDirectories\" are specified because the \"directory\" option doesn't support multiple directories. In the\n    // end, it makes no difference because they all will be merged into a single array.\n    'vendorDirectories' =\u003e $directories[1] ?? [],\n    'table' =\u003e 'cycle_migration',\n    'safe' =\u003e true,\n]);\n/** @var DatabaseManager $databaseManager */\n$migrator = new Migrator($config, $databaseManager, new FileRepository($config));\n$migrator-\u003econfigure();\n\n$capsule = new Capsule($databaseManager-\u003edatabase());\n```\n\nFor configuring `$databaseManager`, see [previous section](#configuring-database-connection).\n\nBecause item and assignment storages are completely independent, migrations are separated as well to prevent \nthe creation of unused tables. So, for example, if you only want to use assignment storage, adjust \n`$migrationsSubfolders` variable like this:\n\n```php\n$migrationsSubfolders = ['assignments'];\n```\n\n#### Applying migrations\n\n```php\nuse Cycle\\Migrations\\Capsule;\nuse Cycle\\Migrations\\Migrator;\n\n/**\n * @var Migrator $migrator\n * @var Capsule $capsule \n */\nwhile ($migrator-\u003erun($capsule) !== null) {\n    echo \"Migration {$migration-\u003egetState()-\u003egetName()} applied successfully.\\n\";\n}\n```\n\n#### Reverting migrations\n\n```php\nuse Cycle\\Migrations\\Capsule;\nuse Cycle\\Migrations\\Migrator;\n\n/**\n * @var Migrator $migrator\n * @var Capsule $capsule \n */\nwhile ($migrator-\u003erollback($capsule) !== null) {\n    echo \"Migration {$migration-\u003egetState()-\u003egetName()} reverted successfully.\\n\";\n}\n```\n\n### Using storages\n\nThe storages are not intended to be used directly. Instead, use them with `Manager` from\n[Yii RBAC](https://github.com/yiisoft/rbac) package:\n\n```php\nuse Cycle\\Database\\DatabaseInterface;\nuse Yiisoft\\Rbac\\Cycle\\AssignmentsStorage;\nuse Yiisoft\\Rbac\\Cycle\\ItemsStorage;\nuse Yiisoft\\Rbac\\Cycle\\TransactionalManagerDecorator;\nuse Yiisoft\\Rbac\\Manager;\nuse Yiisoft\\Rbac\\Permission;\nuse Yiisoft\\Rbac\\RuleFactoryInterface;\n\n/** @var DatabaseInterface $database */\n$itemsStorage = new ItemsStorage($database);\n$assignmentsStorage = new AssignmentsStorage($database);\n/** @var RuleFactoryInterface $rulesContainer */\n$manager = new TransactionalManagerDecorator(\n    new Manager(\n        itemsStorage: $itemsStorage, \n        assignmentsStorage: $assignmentsStorage,\n        // Requires https://github.com/yiisoft/rbac-rules-container or another compatible factory.\n        ruleFactory: $rulesContainer,\n    ),\n);\n$manager-\u003eaddPermission(new Permission('posts.create'));\n```\n\n\u003e Note wrapping manager with decorator—it additionally provides database transactions to guarantee data integrity.\n\n\u003e Note that it's not necessary to use both DB storages. Combining different implementations is possible. A quite popular \n\u003e case is to manage items via [PHP file](https://github.com/yiisoft/rbac-php) while store assignments in a database.\n\nMore examples can be found in [Yii RBAC](https://github.com/yiisoft/rbac) documentation.\n\n### Syncing storages manually\n\nThe storages stay synced thanks to manager, but there can be situations where you need to sync them manually. One of \nthem is using combination with PHP file based storage and \n[editing it manually](https://github.com/yiisoft/rbac-php/?tab=readme-ov-file#file-structure).\n\nLet's say PHP file is used for items, while database - for assignments, and some items were deleted:\n\n```diff\nreturn [\n    [\n        'name' =\u003e 'posts.admin',        \n        'type' =\u003e 'role',        \n        'created_at' =\u003e 1683707079,\n        'updated_at' =\u003e 1683707079,\n        'children' =\u003e [\n            'posts.redactor',\n            'posts.delete',\n            'posts.update.all',\n        ],\n    ],\n-   [\n-       'name' =\u003e 'posts.redactor',\n-       'type' =\u003e 'role',        \n-       'created_at' =\u003e 1683707079,\n-       'updated_at' =\u003e 1683707079,\n-       'children' =\u003e [\n-           'posts.viewer',\n-           'posts.create',\n-           'posts.update',\n-       ],\n-   ],\n    [\n        'name' =\u003e 'posts.viewer',\n        'type' =\u003e 'role',        \n        'created_at' =\u003e 1683707079,\n        'updated_at' =\u003e 1683707079,\n        'children' =\u003e [\n            'posts.view',\n        ],\n    ],\n    [\n        'name' =\u003e 'posts.view',\n        'type' =\u003e 'permission',        \n        'created_at' =\u003e 1683707079,\n        'updated_at' =\u003e 1683707079,\n    ],\n    [\n        'name' =\u003e 'posts.create',\n        'type' =\u003e 'permission',        \n        'created_at' =\u003e 1683707079,\n        'updated_at' =\u003e 1683707079,\n    ],\n-   [\n-       'name' =\u003e 'posts.update',\n-       'rule_name' =\u003e 'is_author',\n-       'type' =\u003e 'permission',\n-       'created_at' =\u003e 1683707079,\n-       'updated_at' =\u003e 1683707079,\n-   ],\n    [\n        'name' =\u003e 'posts.delete',        \n        'type' =\u003e 'permission',        \n        'created_at' =\u003e 1683707079,\n        'updated_at' =\u003e 1683707079,\n    ],\n    [\n        'name' =\u003e 'posts.update.all',\n        'type' =\u003e 'permission',        \n        'created_at' =\u003e 1683707079,\n        'updated_at' =\u003e 1683707079,\n    ],\n];\n```\n\nThen related entries in other storage needs to be deleted as well. This can be done within a migration:\n\n```php\nuse Cycle\\Migrations\\Migration;\n\nfinal class DeletePostUpdateItems extends Migration\n{\n    private const TABLE_PREFIX = 'yii_rbac_';\n    private const ASSIGNMENTS_TABLE = self::TABLE_PREFIX . 'assignment';\n\n    public function up()\n    {\n        $this\n            -\u003edatabase()\n            -\u003edelete()\n            -\u003efrom(self::ASSIGNMENTS_TABLE)\n            -\u003ewhere('item_name', 'IN', ['posts.redactor', 'posts.update']);\n    }\n\n    public function down()\n    {\n    }\n}\n```\n\n## Documentation\n\n- [Internals](docs/internals.md)\n\nIf you need help or have a question, the [Yii Forum](https://forum.yiiframework.com/c/yii-3-0/63) is a good place for that.\nYou may also check out other [Yii Community Resources](https://www.yiiframework.com/community).\n\n## License\n\nThe Yii RBAC Cycle Database is free software. It is released under the terms of the BSD License.\nPlease see [`LICENSE`](./LICENSE.md) for more information.\n\nMaintained by [Yii Software](https://www.yiiframework.com/).\n\n## Support the project\n\n[![Open Collective](https://img.shields.io/badge/Open%20Collective-sponsor-7eadf1?logo=open%20collective\u0026logoColor=7eadf1\u0026labelColor=555555)](https://opencollective.com/yiisoft)\n\n## Follow updates\n\n[![Official website](https://img.shields.io/badge/Powered_by-Yii_Framework-green.svg?style=flat)](https://www.yiiframework.com/)\n[![Twitter](https://img.shields.io/badge/twitter-follow-1DA1F2?logo=twitter\u0026logoColor=1DA1F2\u0026labelColor=555555?style=flat)](https://twitter.com/yiiframework)\n[![Telegram](https://img.shields.io/badge/telegram-join-1DA1F2?style=flat\u0026logo=telegram)](https://t.me/yii3en)\n[![Facebook](https://img.shields.io/badge/facebook-join-1DA1F2?style=flat\u0026logo=facebook\u0026logoColor=ffffff)](https://www.facebook.com/groups/yiitalk)\n[![Slack](https://img.shields.io/badge/slack-join-1DA1F2?style=flat\u0026logo=slack)](https://yiiframework.com/go/slack)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fyiisoft%2Frbac-cycle-db","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fyiisoft%2Frbac-cycle-db","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fyiisoft%2Frbac-cycle-db/lists"}