Download the PHP package strictlyphp/dolphpin without Composer

Dolphin Framework

Dolphin is a lightweight PHP framework designed for running serverless functions on DigitalOcean. It provides attribute-based routing, automatic DTO mapping, role-based access control, and dependency injection out of the box.

For a detailed look at the internals, see ARCHITECTURE.md.

Requirements

• PHP >= 8.2
• Extensions: intl, bcmath, simplexml, curl, mbstring

Installation

Quick Start

1. Define a Controller

Controllers are invokable classes annotated with #[Route]. The framework automatically deserializes the JSON request body into typed DTOs:

2. Define a DTO

DTOs are plain readonly classes. The framework maps JSON fields to constructor parameters, supporting scalars, value objects, nested DTOs, backed enums, and typed arrays:

3. Bootstrap the Application

Use App::build() in your DigitalOcean function entry point. Pass the namespace(s) containing your controllers — routes are discovered automatically from #[Route] attributes:

Features

Attribute-Based Routing

Routes are declared directly on controller classes using #[Route]:

Supported HTTP methods: GET, POST, PUT, PATCH, DELETE, OPTIONS, HEAD.

Automatic DTO Mapping

Controller parameters that are class types are automatically deserialized from the JSON request body. The mapper supports:

• Scalar types — string, int, float, bool
• Value objects — Single-constructor-argument classes (e.g. new EmailAddress($value))
• Nested DTOs — Recursively mapped from nested JSON objects
• Backed enums — Resolved via ::tryFrom()
• Typed arrays — Element type declared via @param array<Type> docblock annotations
• Nullable parameters — Mapped to null when absent

Role-Based Access Control

Protect controllers with #[RequiresRoles]. The framework checks the authenticated user's roles before invoking the controller:

This requires middleware that sets a user attribute on the request implementing AuthenticatedUserInterface:

The AuthenticatedUserInterface requires getId(): string and getRoles(): array.

#[RequiresRoles] also accepts enum cases implementing RoleInterface (alongside plain strings) — they are normalised to their backing string values:

#[RequiresRole] is an enum-only, repeatable alternative. Each instance contributes one role, and multiple instances combine with ANY-of (logical OR) semantics — equivalent to the array form above but without the brackets:

Permission-Based Access Control

For finer-grained authorisation, protect controllers with #[RequiresPermission]. Dolphin owns the vocabulary and the attribute-driven enforcement; the authorisation policy itself lives in your app.

1. Define enums for your user families and permissions using the marker interfaces:

2. Implement AuthorizationServiceInterface with your app's policy (matrix lookups, bypass rules for back-office roles, etc.) and bind it in the container:

3. Decorate route handlers:

The framework calls isAllowed($user, $userKind, $permission) before invoking the controller and returns 403 Forbidden when it returns false (or 401 Unauthorized when no user is on the request).

The attribute is repeatable with ANY-of (logical OR) semantics — the user needs at least one of the listed permissions:

If a controller declares #[RequiresPermission] but no AuthorizationServiceInterface is bound, the framework throws a RuntimeException — a misconfigured app fails loudly rather than silently allowing or denying.

Allowing a role through a permission gate

#[AllowsRole] widens access: a user holding one of the listed roles passes regardless of the #[RequiresPermission] (or #[RequiresRole]) gates on the same controller, and the permission check — including the AuthorizationServiceInterface call — is skipped for them. Use it to gate a route on a fine-grained permission while letting a back-office role straight through:

It is repeatable with ANY-of semantics. #[AllowsRole] is purely additive — it grants, it never restricts. A controller carrying only #[AllowsRole] declares no gate and is therefore effectively open; to restrict access to a role, use #[RequiresRole] or #[RequiresRoles].

Dependency Injection

Dolphin uses PHP-DI for dependency injection. Pass container definitions to App::build():

Controllers are resolved through the container, so constructor dependencies are injected automatically.

Middleware

Register PSR-15 middleware globally via App::build():

Debug Mode

Enable debug mode to include exception details (message, request body, stack trace) in error responses:

Custom Throwable Handler

By default, Dolphin catches all exceptions and returns JSON error responses with appropriate status codes. You can provide your own throwable handler middleware to customize this behavior:

Custom handlers are PSR-15 middleware implementing MiddlewareInterface. They are responsible for their own logging, error formatting, and configuration.

App-Level Exception Handler

In addition to the route-level throwableHandler, you can provide an exceptionHandler closure to customize error handling at the application level (e.g. for errors that occur outside the middleware stack). This is useful for integrating error reporting services like Sentry, Bugsnag, or Datadog:

The exceptionHandler closure receives the \Throwable and can:

• Return an array (['statusCode' => ..., 'body' => ..., 'headers' => ...]) to fully control the response
• Return null to use the default 500 error response (logging is suppressed to avoid duplicates)

When no exceptionHandler is provided, the existing default behavior is preserved.

JSON Responses

Use JsonResponse for convenience:

Development

The project uses Docker for a consistent development environment. Available Make commands:

License

This project is licensed under the MIT License.