Add docs, improve working with arguments (#41)

* Add docs for ItemsStorage

* Apply fixes from StyleCI

* Fix unit tests

* Sync structure of tests with src

* Add docs for AssignmentsStorage

* Apply fixes from StyleCI

* Add docs for RbacCycleInit

* Apply fixes from StyleCI

* Fix mutant with primary keys

* Update README

---------

Co-authored-by: StyleCI Bot <bot@styleci.io>

README.md

@@ -34,6 +34,15 @@ composer require yiisoft/rbac-cycle-db
 rbac/cycle/init
 ```
 
+By default, when called repeatedly, the creation of tables will be skipped if they are already exist. The `--force` flag 
+can be added to force dropping of existing tables and recreate them:
+
+```shell
+rbac/cycle/init --force
+```
+
+> **Note:** All existing data will be erased as well.
+
 ## Testing
 
 ### Unit testing

src/AssignmentsStorage.php

@@ -5,13 +5,14 @@
 namespace Yiisoft\Rbac\Cycle;
 
 use Cycle\Database\DatabaseInterface;
-use Cycle\Database\DatabaseProviderInterface;
 use Cycle\Database\Injection\Fragment;
 use Cycle\Database\Table;
 use Yiisoft\Rbac\Assignment;
 use Yiisoft\Rbac\AssignmentsStorageInterface;
 
 /**
+ * Storage for RBAC assignments in the form of database table. Operations are performed using Cycle ORM.
+ *
  * @psalm-type RawAssignment = array{
  *     itemName: string,
  *     userId: string,
@@ -20,16 +21,16 @@
  */
 final class AssignmentsStorage implements AssignmentsStorageInterface
 {
-    private DatabaseInterface $database;
-
     /**
+     * @param string $tableName A name of the table for storing RBAC assignments.
      * @psalm-param non-empty-string $tableName
+     *
+     * @param DatabaseInterface $database Cycle database instance.
      */
     public function __construct(
         private string $tableName,
-        DatabaseProviderInterface $dbal,
+        private DatabaseInterface $database,
     ) {
-        $this->database = $dbal->database();
     }
 
     public function getAll(): array
@@ -45,7 +46,7 @@ public function getAll(): array
             $assignments[$row['userId']][$row['itemName']] = new Assignment(
                 $row['userId'],
                 $row['itemName'],
-                (int) $row['createdAt']
+                (int) $row['createdAt'],
             );
         }
 

src/Command/RbacCycleInit.php

@@ -4,7 +4,7 @@
 
 namespace Yiisoft\Rbac\Cycle\Command;
 
-use Cycle\Database\DatabaseProviderInterface;
+use Cycle\Database\DatabaseInterface;
 use Cycle\Database\ForeignKeyInterface;
 use Cycle\Database\Table;
 use InvalidArgumentException;
@@ -14,27 +14,42 @@
 use Symfony\Component\Console\Output\OutputInterface;
 use Yiisoft\Rbac\Item;
 
+/**
+ * Command for creating RBAC related database tables using Cycle ORM.
+ */
 final class RbacCycleInit extends Command
 {
     protected static $defaultName = 'rbac/cycle/init';
 
     /**
+     * @var string A name of the table for storing RBAC items (roles and permissions).
      * @psalm-var non-empty-string
      */
     private string $itemsTable;
     /**
+     * @var string A name of the table for storing RBAC assignments.
      * @psalm-var non-empty-string
      */
     private string $assignmentsTable;
     /**
+     * @var string A name of the table for storing relations between RBAC items.
      * @psalm-var non-empty-string
      */
     private string $itemsChildrenTable;
 
+    /**
+     * @param string $itemsTable A name of the table for storing RBAC items (roles and permissions).
+     * @param string $assignmentsTable A name of the table for storing RBAC assignments.
+     * @param DatabaseInterface $database Cycle database instance.
+     * @param string|null $itemsChildrenTable A name of the table for storing relations between RBAC items. When set to
+     * `null`, it will be automatically generated using {@see $itemsTable}.
+     *
+     * @throws InvalidArgumentException When a table name is set to the empty string.
+     */
     public function __construct(
         string $itemsTable,
         string $assignmentsTable,
-        private DatabaseProviderInterface $dbal,
+        private DatabaseInterface $database,
         string|null $itemsChildrenTable = null,
     ) {
         if ($itemsTable === '') {
@@ -84,10 +99,15 @@ protected function execute(InputInterface $input, OutputInterface $output): int
         return Command::SUCCESS;
     }
 
+    /**
+     * Creates table for storing RBAC items (roles and permissions).
+     *
+     * @see $itemsTable
+     */
     private function createItemsTable(): void
     {
         /** @var Table $table */
-        $table = $this->dbal->database()->table($this->itemsTable);
+        $table = $this->database->table($this->itemsTable);
         $schema = $table->getSchema();
 
         $schema->string('name', 128)->nullable(false);
@@ -102,10 +122,15 @@ private function createItemsTable(): void
         $schema->save();
     }
 
+    /**
+     * Creates table for storing relations between RBAC items.
+     *
+     * @see $itemsChildrenTable
+     */
     private function createItemsChildrenTable(): void
     {
         /** @var Table $table */
-        $table = $this->dbal->database()->table($this->itemsChildrenTable);
+        $table = $this->database->table($this->itemsChildrenTable);
         $schema = $table->getSchema();
 
         $schema->string('parent', 128)->nullable(false);
@@ -125,10 +150,15 @@ private function createItemsChildrenTable(): void
         $schema->save();
     }
 
+    /**
+     * Creates table for storing RBAC assignments.
+     *
+     * @see $assignmentsTable
+     */
     private function createAssignmentsTable(): void
     {
         /** @var Table $table */
-        $table = $this->dbal->database()->table($this->assignmentsTable);
+        $table = $this->database->table($this->assignmentsTable);
         $schema = $table->getSchema();
 
         $schema->string('itemName', 128)->nullable(false);
@@ -145,13 +175,19 @@ private function createAssignmentsTable(): void
     }
 
     /**
+     * Basic method for creating RBAC related table. When a table already exists, creation is skipped. Operations are
+     * accompanied by explanations printed to console.
+     *
+     * @param string $tableName A name of created table.
      * @psalm-param non-empty-string $tableName
+     *
+     * @param OutputInterface $output Output for writing messages.
      */
     private function createTable(string $tableName, OutputInterface $output): void
     {
         $output->writeln("<fg=blue>Checking existence of `$tableName` table...</>");
 
-        if ($this->dbal->database()->hasTable($tableName) === true) {
+        if ($this->database->hasTable($tableName) === true) {
             $output->writeln("<bg=yellow>`$tableName` table already exists. Skipped creating.</>");
 
             return;
@@ -169,13 +205,19 @@ private function createTable(string $tableName, OutputInterface $output): void
     }
 
     /**
+     * Basic method for dropping RBAC related table. When a table already exists, dropping is skipped. Operations are
+     * accompanied by explanations printed to console.
+     *
+     * @param string $tableName A name of created table.
      * @psalm-param non-empty-string $tableName
+     *
+     * @param OutputInterface $output Output for writing messages.
      */
     private function dropTable(string $tableName, OutputInterface $output): void
     {
         $output->writeln("<fg=blue>Checking existence of `$tableName` table...</>");
 
-        if ($this->dbal->database()->hasTable($tableName) === false) {
+        if ($this->database->hasTable($tableName) === false) {
             $output->writeln("<bg=yellow>`$tableName` table doesn't exist. Skipped dropping.</>");
 
             return;
@@ -184,7 +226,7 @@ private function dropTable(string $tableName, OutputInterface $output): void
         $output->writeln("<fg=blue>`$tableName` table exists. Dropping...</>");
 
         /** @var Table $table */
-        $table = $this->dbal->database()->table($tableName);
+        $table = $this->database->table($tableName);
         $schema = $table->getSchema();
         $schema->declareDropped();
         $schema->save();