Merge pull request #140 from dotkernel/issue-137-139

Issue #137-#139: Documented Doctrine table prefix feature and updated v6 evolution pattern page on MethodDeprecations

Author: arhimede

docs/book/v6/installation/doctrine-orm.md

@@ -13,14 +13,15 @@ Below is the item you need to focus on:
 ```php
 $databases = [
     'default' => [
-        'host'     => 'localhost',
-        'dbname'   => 'my_database',
-        'user'     => 'my_user',
-        'password' => 'my_password',
-        'port'     => 3306,
-        'driver'   => 'pdo_mysql',
-        'charset'  => 'utf8mb4',
-        'collate'  => 'utf8mb4_general_ci',
+        'host'         => 'localhost',
+        'dbname'       => 'my_database',
+        'user'         => 'my_user',
+        'password'     => 'my_password',
+        'port'         => 3306,
+        'driver'       => 'pdo_mysql',
+        'charset'      => 'utf8mb4',
+        'collate'      => 'utf8mb4_general_ci',
+        'table_prefix' => '',
     ],
     // you can add more database connections into this array
 ];
@@ -97,3 +98,58 @@ php ./bin/doctrine fixtures:execute --class=FixtureClassName
 ```
 
 More details on how fixtures work can be found on [dot-data-fixtures documentation](https://github.com/dotkernel/dot-data-fixtures#creating-fixtures)
+
+### Prefixing table names
+
+Note in the database configuration array the key called `table_prefix`.
+By default, it is an empty string, which means that all the tables will be named exactly the way they are configured in the entities.
+
+```text
+├─ admin
+├─ admin_login
+├─ admin_role
+├─ admin_roles
+├─ doctrine_migration_versions
+├─ oauth_access_tokens
+├─ oauth_access_token_scopes
+├─ oauth_auth_codes
+├─ oauth_auth_code_scopes
+├─ oauth_clients
+├─ oauth_refresh_tokens
+├─ oauth_scopes
+├─ settings
+├─ user
+├─ user_avatar
+├─ user_detail
+├─ user_reset_password
+├─ user_role
+└─ user_roles 
+```
+
+Adding a prefix, for example `dot_`, all the table will be composed of the prefix and the original table name.
+
+```text
+├─ dot_admin
+├─ dot_admin_login
+├─ dot_admin_role
+├─ dot_admin_roles
+├─ doctrine_migration_versions
+├─ dot_oauth_access_tokens
+├─ dot_oauth_access_token_scopes
+├─ dot_oauth_auth_codes
+├─ dot_oauth_auth_code_scopes
+├─ dot_oauth_clients
+├─ dot_oauth_refresh_tokens
+├─ dot_oauth_scopes
+├─ dot_settings
+├─ dot_user
+├─ dot_user_avatar
+├─ dot_user_detail
+├─ dot_user_reset_password
+├─ dot_user_role
+└─ dot_user_roles 
+```
+
+> The configured prefix is prepended as is, no intermediary character will be added.
+
+> `doctrine_migration_versions` is an exception, being a special table handled by Doctrine Migrations.

docs/book/v6/transition-from-api-tools/api-tools-vs-dotkernel-api.md

@@ -17,5 +17,5 @@
 | Authentication      | HTTP Basic/Digest   OAuth2.0                   | OAuth2.0                                                                                                                                               |
 | CI/CD               | Yes                                            | Yes                                                                                                                                                    |
 | Unit Tests          | Yes                                            | Yes                                                                                                                                                    |
-| Endpoint Generator  | Yes                                            | Under development                                                                                                                                      |
+| Code Generator      | Yes                                            | [dotkernel/dot-maker](https://www.dotkernel.com/headless-platform/dotmaker-generate-common-code-in-dotkernel/)                                         |
 | PSR                 | PSR-7                                          | PSR-7, PSR-15                                                                                                                                          |

docs/book/v6/tutorials/api-evolution.md

@@ -5,7 +5,7 @@ API evolution: Updating an API while keeping it compatible for existing consumer
 ## How it works
 
 In Dotkernel API we can mark an entire endpoint or a single method as deprecated using attributes on handlers.
-We use response headers to inform the consumers about the future changes by using 2 new headers:
+We use response headers to inform the consumers about the future changes by using two new headers:
 
 - `Link` - it's a link to the official documentation pointing out the changes that will take place.
 - `Sunset` - this header is a date, indicating when the deprecated resource will potentially become unresponsive.
@@ -17,7 +17,7 @@ We use response headers to inform the consumers about the future changes by usin
 
 ## Marking an entire endpoint as deprecated
 
-When you want to mark an entire resource as deprecated you have to use the `ResourceDeprecation` attribute.
+When you want to mark an entire resource as deprecated, you have to use the `ResourceDeprecation` attribute.
 
 ```php
 ...
@@ -56,60 +56,17 @@ Vary: Origin
 
 ## Marking a method as deprecated
 
-Most of the time you want to deprecate only an endpoint, so you will need to use the `MethodDeprecation` attribute which has the same parameters, but it attaches to a handler method.
-
-```php
-...
-class HomeHandler implements RequestHandlerInterface
-{
-    ...
-    use Api\App\Attribute\MethodDeprecation;
-
-    #[MethodDeprecation(
-        sunset: '2038-01-01',
-        link: 'https://docs.dotkernel.org/api-documentation/v6/tutorials/api-evolution/',
-        deprecationReason: 'Method deprecation example.',
-        rel: 'sunset',
-        type: 'text/html'
-    )]
-    public function get(): ResponseInterface
-    {
-        ...
-    }
-}
-```
-
-Attaching the `MethodDeprecation` can only be done to HTTP verb methods (`GET`, `POST`, `PUT`, `PATCH` and `DELETE`).
-
-If you followed along you can run the below curl:
-
-```shell
-curl --head -X GET http://0.0.0.0:8080 -H "Content-Type: application/json"
-```
-
-The response lists the **Sunset** and **Link** headers.
-
-```shell
-HTTP/1.1 200 OK
-Host: 0.0.0.0:8080
-Date: Mon, 24 Jun 2024 10:54:57 GMT
-Connection: close
-X-Powered-By: PHP/6.4.20
-Content-Type: application/json
-Permissions-Policy: interest-cohort=()
-Sunset: 2038-01-01
-Link: https://docs.dotkernel.org/api-documentation/v6/tutorials/api-evolution/;rel="sunset";type="text/html"
-Vary: Origin
-```
+Since version 6, in Dotkernel API each handler is PSR-15 middleware responsible for handling a single request method.
+This means that each resource operation will have its own handler class.
+Therefore, `MethodDeprecation` no longer has a class method to attach to.
+Instead, you should use the `ResourceDeprecation` attribute on the handler class.
 
 ## NOTES
 
 > If `Link` or `Sunset` do not have a value they will not appear in the response headers.
 
 > `Sunset` has to be a **valid** date, otherwise it will throw an error.
 
-> You **cannot** use both `ResourceDeprecation` and `MethodDeprecation` in the same handler.
-
 > Deprecations can only be attached to handler classes that implement `RequestHandlerInterface`.
 
 > The `rel` and `type` arguments are optional, they default to `sunset` and `text/html` if no value was provided and are `Link` related parts.