Upgrading to 0.2
0.2 has one breaking code change and two changed defaults. Apps written for 0.1.3 or earlier have one more rename to make (step 3). Most apps upgrade in a few minutes.
1. Update the packages
Section titled “1. Update the packages”All Antares packages share one version number, so update them together:
composer require fatjon-lleshi/antares:^0.2^0.1 constraints do not accept 0.2, because on 0.x versions a minor bump is a breaking release. If you require any standalone package directly (antares-container, antares-router, antares-validation, or a bridge), bump it to ^0.2 as well.
2. ResponseDto(case:) takes an enum
Section titled “2. ResponseDto(case:) takes an enum”The case argument of #[ResponseDto] is now a CaseStyle enum instead of a string.
#[ResponseDto(case: 'snake_case')]use Antares\Serialization\CaseStyle;
#[ResponseDto(case: CaseStyle::SnakeCase)]| 0.1 string | 0.2 enum |
|---|---|
'camel_case' (default) | CaseStyle::CamelCase |
'snake_case' | CaseStyle::SnakeCase |
'pascal_case' | CaseStyle::PascalCase |
'kebab_case' | CaseStyle::KebabCase |
A string now fails with a TypeError when the response is serialized, so search your app for case: ' to find every place to change. Classes without a case argument need no changes.
If you call CaseConverter::convert() directly, pass a CaseStyle there too.
3. Guards were renamed (only if you’re coming from 0.1.3 or earlier)
Section titled “3. Guards were renamed (only if you’re coming from 0.1.3 or earlier)”0.1.4 renamed the guard attribute and moved the guard interface. If your app still uses the old names, PHP fails with Class “Antares\Http\Attributes\Guards” not found:
| Old (0.1.3 and earlier) | New (0.1.4 and later) |
|---|---|
use Antares\Http\Attributes\Guards; | use Antares\Http\Attributes\Guard; |
#[Guards(AuthGuard::class)] | #[Guard(AuthGuard::class)] |
use Antares\Http\Guards\Guard; (in your guard classes) | use Antares\Http\ResolverInterfaces\Guard; |
A find-and-replace of those three lines is enough; the guard classes themselves don’t change.
4. OpenAPI docs are off in production by default
Section titled “4. OpenAPI docs are off in production by default”In 0.1, /openapi.json and /docs were registered in every environment. In 0.2 they are off when APP_ENV=production, so your production API no longer publishes its own map.
To keep them on in production, add this to the server’s .env:
APP_DOCS=trueNothing changes locally. See OpenAPI for every option.
5. Unexpected errors are hidden in production
Section titled “5. Unexpected errors are hidden in production”In 0.1, every error response showed the exception’s message, so a database error could reach your users. In 0.2, only errors meant for the client show their message: HttpException, validation and hydration errors, unknown routes, and anything you mark as safe. Every other exception becomes 500 Internal Server Error with no details, and is logged.
What to check:
- If you throw plain exceptions (
RuntimeException,DomainException, …) and rely on their message reaching the client, throw anHttpExceptioninstead, implementHttpExceptionInterface, or map them with->exceptions([...]). See Error Handling. - Locally nothing is hidden:
APP_DEBUGis on by default outsideAPP_ENV=production, and adds the real error to500responses. - Clients checking for a
500on unknown routes now get404(or405for a wrong HTTP method).
Also new in 0.2
Section titled “Also new in 0.2”These need no changes on your side:
-
404and405for unknown routes and wrong HTTP methods. In 0.1 both returned500. -
Error logging. Every
5xxis logged with the full exception, to the container’s PSR-3 logger if there is one, otherwise toerror_log(). -
Stricter request bodies. Malformed input that used to cause a
500, or was silently accepted, is now a400with a clear message: a JSON body that isn’t an object, a string where a nested DTO is expected, an array for astringfield,nullfor a non-nullable field,?page[]=1for a scalar query parameter, and several files under one field name. -
boolfields now read"false","no"and"off"asfalse. In 0.1 they becametrue. -
FrankenPHP worker mode keeps the app booted between requests. In 0.1,
runWorker()handled one request per worker start. -
#[DateTimeImmutable]can be used; in 0.1 it couldn’t be autoloaded. -
make:guardgenerates a guard that implements the right interface. -
Real environment variables are respected. In 0.1, a variable set outside
.env(by Docker, systemd, or your shell) was invisible to the framework. In particular, a realAPP_ENV=productionis now seen, which also turns off docs and debug output by default. -
The CLI loads
.env, somigrateuses yourDB_*settings. -
Migrations connect to SQL Server, Oracle and SQLite, not only MySQL and PostgreSQL, and
DB_DSNaccepts any PDO connection string. -
Query parameters are documented in the OpenAPI spec.
-
#[Computed]fields appear in response schemas. -
A request body is detected by
#[Dto]. In 0.1 it also required the class to bereadonly. -
A DTO without a constructor no longer breaks
/openapi.json.