Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
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
4 changes: 2 additions & 2 deletions docs/book/v7/introduction/introduction.md
Original file line number Diff line number Diff line change
Expand Up @@ -2,11 +2,11 @@

## Summary

A tour of Dotkernel API: a PSR-15 middleware REST framework on PHP 8.2+ acting as a Headless Platform, with OAuth2 authentication, RBAC authorization, content negotiation, Doctrine ORM persistence, HAL payloads, CORS handling, email through `dot-mail`, OpenAPI and Bruno documentation, per-module routing and configuration, CLI commands with a file locker, and unit and functional test suites — closing with the pitfalls to avoid and where to go next.
A tour of Dotkernel API: a PSR-15 middleware REST framework on PHP 8.3+ acting as a Headless Platform, with OAuth2 authentication, RBAC authorization, content negotiation, Doctrine ORM persistence, HAL payloads, CORS handling, email through `dot-mail`, OpenAPI and Bruno documentation, per-module routing and configuration, CLI commands with a file locker, and unit and functional test suites — closing with the pitfalls to avoid and where to go next.

## What is Dotkernel API?

Dotkernel API is a modern, PSR-15 middleware-based REST API framework built on PHP 8.2+.
Dotkernel API is a modern, PSR-15 middleware-based REST API framework built on PHP 8.3+.
It is a Headless Platform with built-in OAuth2 authentication, RBAC authorization, and content negotiation.

## When to Use Dotkernel API
Expand Down
72 changes: 54 additions & 18 deletions docs/book/v7/introduction/server-requirements.md
Original file line number Diff line number Diff line change
Expand Up @@ -2,7 +2,7 @@

## Summary

What Dotkernel API v7 needs to run: a Linux host in production (Windows via WSL2 for development), Apache with `mod_rewrite` or an Nginx equivalent, PHP 8.2 or newer with `mbstring` and CLI SAPI, Composer 2.0 or newer, and MariaDB or PostgreSQL — MySQL is not supported because it lacks native UUID types.
What Dotkernel API v7 needs to run: a Linux host in production (Windows via WSL2 for development), Apache with `mod_rewrite` or an Nginx equivalent, PHP 8.3, 8.4 or 8.5 with the `gd`, `json` and `mbstring` extensions and CLI SAPI, Composer 2.0 or newer, and MariaDB or PostgreSQL — MySQL is not supported because it lacks native UUID types.
Recommended extensions and baseline server hardening are listed as well.

## Details
Expand Down Expand Up @@ -38,33 +38,64 @@ Windows is supported for development via WSL2.

You need to convert the provided Apache related `.htaccess` file into Nginx configuration instructions.

## PHP >= 8.2
## PHP 8.3, 8.4 or 8.5

Dotkernel API v7 requires PHP 8.3, 8.4 or 8.5, as declared in `composer.json`:

```json
"require": {
"php": "~8.3.0 || ~8.4.0 || ~8.5.0"
}
```

Dotkernel API v7 requires PHP 8.2 or higher.
Earlier PHP versions are not supported.
Support for PHP 8.2 was dropped in Dotkernel API 7.2.0.

> The constraint uses `~` per minor version rather than `>=`, so each supported branch is listed
> explicitly and a newly released PHP version is not assumed to work until it has been tested.

### Supported PHP Configurations

- FPM (FastCGI Process Manager) - Recommended for production, better performance and security isolation
- FastCGI - Obsolete but still in use by some hosting providers
- CLI SAPI (Command Line Interface) - Required for Cron jobs, migrations, and fixtures

### Why PHP 8.2+?
### Why PHP 8.3+?

The floor is set by **typed class constants**, a PHP 8.3 feature used throughout the codebase — for
example in `Api\App\Middleware\ContentNegotiationMiddleware`:

```php
public const string DEFAULT_HEADERS = 'default';
```

The project will not even parse on PHP 8.2.

Dotkernel API leverages modern PHP features:
Beyond that, Dotkernel API leverages these modern PHP features:

- Named Arguments: Clearer function calls
- Match Expressions: More readable than switch statements
- Attributes: Metadata for dependency injection and OpenAPI documentation
- Union Types: Better type safety
- Nullsafe Operator: Safer null handling
- Constructor Property Promotion: Cleaner code
- Typed Class Constants (8.3): Constants carry a declared type
- Readonly Classes (8.2): Immutable value objects such as the deprecation attributes
- Enums (8.1): Roles and statuses are backed enums rather than class constants
- Attributes (8.0): Metadata for dependency injection and OpenAPI documentation
- Named Arguments (8.0): Clearer function calls, used when creating problem-details exceptions
- Match Expressions (8.0): More readable than switch statements
- Constructor Property Promotion (8.0): Cleaner code
- Union Types (8.0) and the Nullsafe Operator (8.0): Better type safety and safer null handling

## Required Settings and Modules & Extensions

These extensions are declared in the `require` section of `composer.json` as `ext-gd` and
`ext-json`, so Composer refuses to install the project without them:

- `gd` - must be enabled; this is the one to check on a new server
- `json` - ships enabled and cannot be disabled on any supported PHP version, so in practice it needs no action

Also required:

- mbstring
- the PDO driver for your database - `pdo_mysql` for MariaDB or `pdo_pgsql` for PostgreSQL
- memory_limit >= 128M
- upload_max_filesize and post_max_size >= 100 M (depending on your data)
- mbstring
- CLI SAPI (for Cron Jobs)
- Composer (added to $PATH)

Expand Down Expand Up @@ -99,11 +130,13 @@ When creating databases, use:

## Recommended extensions

These are optional and depend on what your application does.
For the extensions the project itself requires, see the "Required Settings and Modules & Extensions" section above.

- `opcache`
- `pdo_mysql`, `pdo_pgsql` or `mysqli` (if using MariaDB or PostgreSQL as RDBMS)
- `dom` - if working with markup files structure (HTML, XML, etc.)
- `simplexml` - working with XML files
- `gd`, `exif` - if working with images
- `exif` - additional image metadata handling (`gd` itself is required, not optional)
- `zlib`, `zip`, `bz2` - if compressing files
- `curl` (required if APIs are used)
- `sqlite3` - for tests
Expand Down Expand Up @@ -138,8 +171,10 @@ A: `utf8mb4_general_ci` or `utf8mb4_unicode_ci` on MariaDB, and `C.UTF-8` or `en

**Q: What is the minimum PHP version?**

A: PHP 8.2.
Earlier versions are not supported, because the project relies on named arguments, match expressions, attributes, union types, the nullsafe operator and constructor property promotion.
A: PHP 8.3.
`composer.json` requires `~8.3.0 || ~8.4.0 || ~8.5.0`, so 8.3, 8.4 and 8.5 are supported and earlier versions are not.
PHP 8.2 support was dropped in Dotkernel API 7.2.0.
The hard blocker is typed class constants, a PHP 8.3 feature used throughout the codebase, so the project will not parse on 8.2.

**Q: Do I need the CLI SAPI as well as FPM?**

Expand All @@ -156,8 +191,9 @@ A: Yes, through WSL2. macOS and Linux are also supported for development; produc

**Q: Which PHP extensions are actually required?**

A: `mbstring` plus the PDO driver for your database.
The rest — `opcache`, `gd`, `curl`, `zip`, `dom`, `simplexml`, `sqlite3` and others — depend on what your application does, with `sqlite3` needed to run the tests.
A: `gd` and `json` are declared in `composer.json` as `ext-gd` and `ext-json`, so Composer will not install the project without them.
Add `mbstring` and the PDO driver for your database — `pdo_mysql` or `pdo_pgsql`.
The rest — `opcache`, `curl`, `zip`, `dom`, `simplexml`, `exif`, `sqlite3` and others — depend on what your application does, with `sqlite3` needed to run the tests.

**Q: What are the baseline hardening steps?**

Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -11,7 +11,7 @@ API Tools is archived and MVC/event-driven; Dotkernel API is actively maintained
|---------------------|------------------------------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------|
| URL | [api-tools](https://api-tools.getlaminas.org/) | [Dotkernel API](https://www.dotkernel.org) |
| First Release | 2012 | 2018 |
| PHP Version | <= 8.2 | >= 8.2 |
| PHP Version | <= 8.2 | 8.3, 8.4, 8.5 |
| Architecture | MVC, Event Driven | Middleware |
| OSS Lifecycle | Archived | ![OSS Lifecycle](https://img.shields.io/osslifecycle?style=flat&label=&file_url=https%3A%2F%2Fgithub.com%2Fdotkernel%2Fapi%2Fblob%2F7.0%2FOSSMETADATA) |
| Style | REST, RPC | REST |
Expand Down