Skip to content

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

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 3 commits into from
Nov 25, 2025
Merged

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

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
405e1a1
Issue #137: Documented Doctrine table prefix feature
alexmerlin Nov 25, 2025
0adaeaf
Issue #137: Documented Doctrine table prefix feature
alexmerlin Nov 25, 2025
0c69a87
Issue #137: Documented Doctrine table prefix feature
alexmerlin Nov 25, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
72 changes: 64 additions & 8 deletions docs/book/v6/installation/doctrine-orm.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
];
Expand Down Expand Up @@ -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.
2 changes: 1 addition & 1 deletion docs/book/v6/transition-from-api-tools/api-tools-vs-dotkernel-api.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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 |
55 changes: 6 additions & 49 deletions docs/book/v6/tutorials/api-evolution.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand All @@ -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
...
Expand Down Expand Up @@ -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.