Docs folder standardization and other fixes (#257)

yiisoft · Apr 24, 2024 · 8de2712 · 8de2712
1 parent c9f4ac9
commit 8de2712
Show file tree

Hide file tree

Showing 11 changed files with 221 additions and 45 deletions.
diff --git a/LICENSE.md b/LICENSE.md
@@ -1,17 +1,17 @@
-Copyright © 2008 by Yii Software (https://www.yiiframework.com/)
+Copyright © 2008 by Yii Software (<https://www.yiiframework.com/>)
 All rights reserved.
 
 Redistribution and use in source and binary forms, with or without
 modification, are permitted provided that the following conditions
 are met:
 
- * Redistributions of source code must retain the above copyright
+* Redistributions of source code must retain the above copyright
    notice, this list of conditions and the following disclaimer.
- * Redistributions in binary form must reproduce the above copyright
+* Redistributions in binary form must reproduce the above copyright
    notice, this list of conditions and the following disclaimer in
    the documentation and/or other materials provided with the
    distribution.
- * Neither the name of Yii Software nor the names of its
+* Neither the name of Yii Software nor the names of its
    contributors may be used to endorse or promote products derived
    from this software without specific prior written permission.
 

diff --git a/README.md b/README.md
@@ -22,7 +22,7 @@ Supports the following databases out of the box:
 - [MySQL](https://www.mysql.com/) of versions **5.7–8.0**.
 - [MariaDB](https://mariadb.org/) of versions **10.4–10.9**.
 - [Oracle](https://www.oracle.com/database/) of versions **12c–21c**.
-- [PostgreSQL](https://www.postgresql.org/) of versions **9.6–15**. 
+- [PostgreSQL](https://www.postgresql.org/) of versions **9.6–15**.
 - [SQLite](https://www.sqlite.org/index.html) of version **3.3 and above**.
 
 ## Requirements
@@ -32,31 +32,23 @@ Supports the following databases out of the box:
 
 ## Installation
 
-The preferred way to install this extension is through [composer](http://getcomposer.org/download/).
+The preferred way to install this extension is through [composer](https://getcomposer.org/download/).
 
-Either run
+Either run:
 
 ```shell
 composer require yiisoft/db-migration
 ```
 
-or add
+or add to the `require` section of your `composer.json`:
 
 ```json
 "yiisoft/db-migration": "^1.0"
 ```
 
-to the `require` section of your `composer.json`.
-
-## Usage
-
-- [Yii Console](/docs/en/usage-with-yii-console.md).
-- [Symfony application](/docs/en/usage-with-symfony.md).
-- [Standalone](/docs/en/usage-standalone.md).
-
 ## Command list
 
-```
+```shell
 migrate:create   Creates a new migration.
 migrate:down     Reverts the specified number of latest migrations.
 migrate:history  Displays the migration history.
@@ -67,21 +59,19 @@ migrate:up       Applies new migrations.
 
 The create command allows defining fields for the table being created.
 
-## Support
+## Documentation
 
-If you need help or have a question, the [Yii Forum](https://forum.yiiframework.com/c/yii-3-0/db/68) is a good place for that.
-You may also check out other [Yii Community Resources](https://www.yiiframework.com/community).
-
-## Testing
+- [English](docs/guide/en/readme.md)
+- [Português - Brasil](docs/guide/pt-BR/readme.md)
 
-[Check the testing instructions](/docs/en/testing.md) to learn about testing.
+Testing:
 
-## License
+- [Internals](docs/internals.md)
 
-The Yii Db Migration is free software. It is released under the terms of the BSD License.
-Please see [`LICENSE`](./LICENSE.md) for more information.
+## Support
 
-Maintained by [Yii Software](https://www.yiiframework.com/).
+If 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.
+You may also check out other [Yii Community Resources](https://www.yiiframework.com/community).
 
 ## Support the project
 
@@ -94,3 +84,10 @@ Maintained by [Yii Software](https://www.yiiframework.com/).
 [![Telegram](https://img.shields.io/badge/telegram-join-1DA1F2?style=flat&logo=telegram)](https://t.me/yii3en)
 [![Facebook](https://img.shields.io/badge/facebook-join-1DA1F2?style=flat&logo=facebook&logoColor=ffffff)](https://www.facebook.com/groups/yiitalk)
 [![Slack](https://img.shields.io/badge/slack-join-1DA1F2?style=flat&logo=slack)](https://yiiframework.com/go/slack)
+
+## License
+
+The Yii Db Migration is free software. It is released under the terms of the BSD License.
+Please see [`LICENSE`](./LICENSE.md) for more information.
+
+Maintained by [Yii Software](https://www.yiiframework.com/).
diff --git a/docs/guide/en/readme.md b/docs/guide/en/readme.md
@@ -0,0 +1,5 @@
+# Yii DB Migration
+
+- [Yii Console](usage-with-yii-console.md)
+- [Symfony application](usage-with-symfony.md)
+- [Standalone](usage-standalone.md)
diff --git a/docs/en/usage-standalone.md → docs/guide/en/usage-standalone.md b/docs/en/usage-standalone.md → docs/guide/en/usage-standalone.md
@@ -8,23 +8,24 @@
     cp ./vendor/yiisoft/db-migration/bin/yii-db-migration.php ./yii-db-migration.php
     ```
 
-2. Define DB connection in configuration file (see 
+2. Define DB connection in configuration file (see
    [Yii DB documentation](https://github.com/yiisoft/db/blob/master/docs/en/README.md#create-connection)).
-   For example, MySQL connection: 
+   For example, MySQL connection:
+
     ```php
     'db' => new \Yiisoft\Db\Mysql\Connection(
         new \Yiisoft\Db\Mysql\Driver('mysql:host=mysql;dbname=mydb', 'user', 'q1w2e3r4'),
         new \Yiisoft\Db\Cache\SchemaCache(new \Yiisoft\Cache\ArrayCache()),
     ),
     ```
-   
+
 3. Optionally, modify other options in the configuration file. Each option has a comment with description.
 4. Run the console command without arguments to see the list of available migration commands:
 
     ```shell
     ./vendor/bin/yii-db-migration
     ```
-   
+
 ## Without configuration file
 
 This can be useful in testing environment and/or when multiple RDBMS are used.

diff --git a/docs/en/usage-with-symfony.md → docs/guide/en/usage-with-symfony.md b/docs/en/usage-with-symfony.md → docs/guide/en/usage-with-symfony.md
@@ -2,7 +2,7 @@
 
 Require migrations and DB driver. Let's use SQLite for this example:
 
-```
+```shell
 composer require yiisoft/db-migration
 composer require yiisoft/db-sqlite
 ```

diff --git a/docs/en/usage-with-yii-console.md → docs/guide/en/usage-with-yii-console.md b/docs/en/usage-with-yii-console.md → docs/guide/en/usage-with-yii-console.md
@@ -5,10 +5,6 @@ In this example, we use [yiisoft/app](https://github.com/yiisoft/app).
 First, configure DI container. Create `config/common/db.php` with the following content:
 
 ```php
-<?php
-
-declare(strict_types=1);
-
 use Yiisoft\Db\Connection\ConnectionInterface;
 use Yiisoft\Db\Sqlite\Connection as SqliteConnection;
 

diff --git a/docs/guide/pt-BR/readme.md b/docs/guide/pt-BR/readme.md
@@ -0,0 +1,5 @@
+# Yii DB Migration
+
+- [Yii Console](usage-with-yii-console.md)
+- [Symfony application](usage-with-symfony.md)
+- [Standalone](usage-standalone.md)
diff --git a/docs/guide/pt-BR/usage-standalone.md b/docs/guide/pt-BR/usage-standalone.md
@@ -0,0 +1,70 @@
+# Standalone usage
+
+## With configuration file
+
+1. Copy configuration file `./vendor/yiisoft/db-migration/bin/yii-db-migration.php` to root folder of your project:
+
+    ```shell
+    cp ./vendor/yiisoft/db-migration/bin/yii-db-migration.php ./yii-db-migration.php
+    ```
+
+2. Define DB connection in configuration file (see
+   [Yii DB documentation](https://github.com/yiisoft/db/blob/master/docs/en/README.md#create-connection)).
+   For example, MySQL connection:
+
+    ```php
+    'db' => new \Yiisoft\Db\Mysql\Connection(
+        new \Yiisoft\Db\Mysql\Driver('mysql:host=mysql;dbname=mydb', 'user', 'q1w2e3r4'),
+        new \Yiisoft\Db\Cache\SchemaCache(new \Yiisoft\Cache\ArrayCache()),
+    ),
+    ```
+
+3. Optionally, modify other options in the configuration file. Each option has a comment with description.
+4. Run the console command without arguments to see the list of available migration commands:
+
+    ```shell
+    ./vendor/bin/yii-db-migration
+    ```
+
+## Without configuration file
+
+This can be useful in testing environment and/or when multiple RDBMS are used.
+
+Configure all dependencies manually:
+
+```php
+use Yiisoft\Db\Connection\ConnectionInterface;
+use Yiisoft\Db\Migration\Informer\NullMigrationInformer;
+use Yiisoft\Db\Migration\Migrator;
+use Yiisoft\Db\Migration\Service\MigrationService;
+use Yiisoft\Injector\Injector;
+
+/** @var ConnectionInterface $database */
+$migrator = new Migrator($database, new NullMigrationInformer());
+$migrationService = new MigrationService($database, new Injector(), $migrator);
+$migrationService->setSourcePaths([dirname(__DIR__, 2), 'migrations']);
+```
+
+Then initialize the command for using without CLI. For example, for applying migrations it will be `UpdateCommand`:
+
+```php
+use Symfony\Component\Console\Helper\HelperSet;
+use Symfony\Component\Console\Helper\QuestionHelper;
+use Yiisoft\Db\Migration\Command\UpdateCommand;
+use Yiisoft\Db\Migration\Runner\UpdateRunner;
+
+$command = new UpdateCommand(new UpdateRunner($migrator), $migrationService, $migrator);
+$command->setHelperSet(new HelperSet(['queestion' => new QuestionHelper()]));
+```
+
+And, finally, run the command:
+
+```php
+use Symfony\Component\Console\Input\ArrayInput;
+use Symfony\Component\Console\Output\NullOutput;
+
+$input = new ArrayInput([]);
+$input->setInteractive(false);
+
+$this->getMigrateUpdateCommand()->run($input, new NullOutput());
+```
diff --git a/docs/guide/pt-BR/usage-with-symfony.md b/docs/guide/pt-BR/usage-with-symfony.md
@@ -0,0 +1,55 @@
+# Usage with Symfony
+
+Require migrations and DB driver. Let's use SQLite for this example:
+
+```shell
+composer require yiisoft/db-migration
+composer require yiisoft/db-sqlite
+```
+
+Configure migrations and database connection in your `config/services.yml`:
+
+```yaml
+Yiisoft\Db\Migration\:
+    resource: '../vendor/yiisoft/db-migration/src/'
+
+Yiisoft\Db\Migration\Informer\MigrationInformerInterface:
+    class: 'Yiisoft\Db\Migration\Informer\ConsoleMigrationInformer'
+
+Yiisoft\Injector\Injector:
+    arguments:
+        - '@service_container'
+
+Yiisoft\Db\Migration\Service\MigrationService:
+    calls:
+      - setNewMigrationNamespace: ['App\Migrations']
+      - setNewMigrationPath: ['']
+      - setSourceNamespaces: [['App\Migrations']]
+      - setSourcePaths: [[]]
+
+Yiisoft\Db\:
+  resource: '../vendor/yiisoft/db/src/'
+  exclude:
+    - '../vendor/yiisoft/db/src/Debug/'
+
+cache.app.simple:
+  class: 'Symfony\Component\Cache\Psr16Cache'
+  arguments:
+    - '@cache.app'
+
+Yiisoft\Db\Cache\SchemaCache:
+  arguments:
+    - '@cache.app.simple'
+
+Yiisoft\Db\Connection\ConnectionInterface:
+  class: '\Yiisoft\Db\Sqlite\Connection'
+  arguments:
+    - '@sqlite_driver'
+
+sqlite_driver:
+  class: '\Yiisoft\Db\Sqlite\Driver'
+  arguments:
+    - 'sqlite:./var/migrations.sq3'
+```
+
+That's it. Now you can use `bin/console migrate:*` commands.
diff --git a/docs/guide/pt-BR/usage-with-yii-console.md b/docs/guide/pt-BR/usage-with-yii-console.md
@@ -0,0 +1,42 @@
+# Usage with Yii Console
+
+In this example, we use [yiisoft/app](https://github.com/yiisoft/app).
+
+First, configure DI container. Create `config/common/db.php` with the following content:
+
+```php
+use Yiisoft\Db\Connection\ConnectionInterface;
+use Yiisoft\Db\Sqlite\Connection as SqliteConnection;
+
+return [
+    ConnectionInterface::class => [
+        'class' => SqliteConnection::class,
+        '__construct()' => [
+            'dsn' => 'sqlite:' . __DIR__ . '/Data/yiitest.sq3'
+        ]
+    ]
+];
+```
+
+Add to `config/params.php`:
+
+```php
+...
+'yiisoft/db-migration' => [
+    'newMigrationNamespace' => 'App\\Migration',
+    'sourceNamespaces' => ['App\\Migration'],
+],
+...
+```
+
+Now the `MigrationService::class` uses the `View` of the application that is already registered in `yiisoft/view`.
+
+Execute `composer du` in console to rebuild the configuration.
+
+Now we have the `yiisoft/db-migration` package configured and it can be called in the console.
+
+View the list of available commands with `./yii list`:
+
+```shell
+./yii list
+```
diff --git a/docs/en/testing.md → docs/internals.md b/docs/en/testing.md → docs/internals.md
@@ -1,4 +1,4 @@
-# Testing
+# Internals
 
 This package can be tested globally or individually for each DBMS.
 
@@ -32,10 +32,6 @@ For running the Docker containers, you can use the following command:
 docker compose up -d
 ```
 
-## Unit testing
-
-The package is tested with [PHPUnit](https://phpunit.de/).
-
 ### Global testing
 
 The following steps are required to run the tests.
@@ -68,7 +64,15 @@ Suites available:
 - Pgsql
 - Sqlite
 
-### Mutation testing
+## Unit testing
+
+The package is tested with [PHPUnit](https://phpunit.de/). To run tests:
+
+```shell
+./vendor/bin/phpunit
+```
+
+## Mutation testing
 
 The package tests are checked with [Infection](https://infection.github.io/) mutation framework with
 [Infection Static Analysis Plugin](https://github.com/Roave/infection-static-analysis-plugin). To run it:
@@ -85,15 +89,16 @@ The code is statically analyzed with [Psalm](https://psalm.dev/). To run static
 ./vendor/bin/psalm
 ```
 
-## Rector
+## Code style
 
-Use [Rector](https://github.com/rectorphp/rector) to make codebase follow some specific rules or use either newest or any specific version of PHP: 
+Use [Rector](https://github.com/rectorphp/rector) to make codebase follow some specific rules or
+use either newest or any specific version of PHP:
 
 ```shell
 ./vendor/bin/rector
 ```
 
-## Composer require checker
+## Dependencies
 
 This package uses [composer-require-checker](https://github.com/maglnet/ComposerRequireChecker) to check if all dependencies are correctly defined in `composer.json`.