PHPackages                             andrewdyer/actions - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [HTTP & Networking](/categories/http)
4. /
5. andrewdyer/actions

ActiveLibrary[HTTP & Networking](/categories/http)

andrewdyer/actions
==================

A framework-agnostic PHP library for building structured and predictable JSON API endpoints with standardised request and response handling

1.0.2(3w ago)0132[5 issues](https://github.com/andrewdyer/actions/issues)1MITPHPPHP ^8.3CI passing

Since Mar 31Pushed 1w agoCompare

[ Source](https://github.com/andrewdyer/actions)[ Packagist](https://packagist.org/packages/andrewdyer/actions)[ Docs](https://github.com/andrewdyer/settings)[ RSS](/packages/andrewdyer-actions/feed)WikiDiscussions main Synced 3w ago

READMEChangelog (10)Dependencies (15)Versions (17)Used By (1)

Actions
=======

[](#actions)

A framework-agnostic library for building structured and predictable JSON responses with standardised response handling.

[![Latest Stable Version](https://camo.githubusercontent.com/192bec387fe7a41c6b7641ee5f21c2864361503d530294d371183f8a07a5d52c/687474703a2f2f706f7365722e707567782e6f72672f616e64726577647965722f616374696f6e732f763f7374796c653d666c61742d737175617265)](https://packagist.org/packages/andrewdyer/actions)[![Total Downloads](https://camo.githubusercontent.com/5747378c1f6e9da56aafbd68095053a043cea62fd90c7193f8cf735fb4cc9d41/687474703a2f2f706f7365722e707567782e6f72672f616e64726577647965722f616374696f6e732f646f776e6c6f6164733f7374796c653d666c61742d737175617265)](https://packagist.org/packages/andrewdyer/actions)[![License](https://camo.githubusercontent.com/a71a8c254e507add2fcb78f1500c8d6cbeabee5397b34ef6ca8984bfb2db1ee1/687474703a2f2f706f7365722e707567782e6f72672f616e64726577647965722f616374696f6e732f6c6963656e73653f7374796c653d666c61742d737175617265)](https://packagist.org/packages/andrewdyer/actions)[![PHP Version Require](https://camo.githubusercontent.com/6a8a83a778fac2352eb3bf911ea301b75ea6a001f7e5ec278971ccf2e9691423/687474703a2f2f706f7365722e707567782e6f72672f616e64726577647965722f616374696f6e732f726571756972652f7068703f7374796c653d666c61742d737175617265)](https://packagist.org/packages/andrewdyer/actions)

Introduction
------------

[](#introduction)

This library offers a small set of utilities that standardise how actions handle requests and generate structured JSON responses, establishing clear patterns for success responses and error payloads. By keeping action classes focused on domain logic and giving clients well-structured, predictable JSON responses, it simplifies API development regardless of the framework or HTTP layer in use.

Prerequisites
-------------

[](#prerequisites)

- **[PHP](https://www.php.net/)**: Version 8.3 or higher is required.
- **[Composer](https://getcomposer.org/)**: Dependency management tool for PHP.

Installation
------------

[](#installation)

```
composer require andrewdyer/actions
```

Getting Started
---------------

[](#getting-started)

The examples below demonstrate how this library can be used with [Slim Framework 4](https://www.slimframework.com/).

> ⚠️ Slim and a PSR-7 implementation are not included as dependencies of this package and must be installed separately before running these examples.

### 1. Create an action

[](#1-create-an-action)

The action validates the request, retrieves data, and returns a JSON response.

```
declare(strict_types=1);

namespace App\Http\Actions;

use AndrewDyer\Actions\AbstractAction;
use Psr\Http\Message\ResponseInterface;

final class GetUserAction extends AbstractAction
{
    protected function handle(): ResponseInterface
    {
        $id = (string) $this->resolveArg('id');

        if (!ctype_digit($id)) {
            return $this->badRequest('User ID must be numeric.');
        }

        if ((int) $id !== 123) {
            return $this->notFound("User {$id} not found.");
        }

        return $this->ok([
            'id' => (int) $id,
            'name' => 'John Smith',
            'email' => 'john.smith@example.com',
        ]);
    }
}
```

### 2. Register the route

[](#2-register-the-route)

The action is wired into the Slim bootstrap so requests to `/users/{id}` are dispatched to the action class.

```
declare(strict_types=1);

use App\Http\Actions\GetUserAction;
use Slim\Factory\AppFactory;

require __DIR__ . '/../vendor/autoload.php';

$app = AppFactory::create();

// If using a container, ensure GetUserAction is resolvable there.
$app->get('/users/{id}', GetUserAction::class);

$app->run();
```

Usage
-----

[](#usage)

Once the route is registered, Slim invokes the action and returns the payload as JSON.

### Successful request

[](#successful-request)

```
GET /users/123
Accept: application/json

```

**Response: 200 OK**

```
{
  "data": {
    "id": 123,
    "name": "John Smith",
    "email": "john.smith@example.com"
  }
}
```

### Validation error

[](#validation-error)

```
GET /users/abc
Accept: application/json

```

**Response: 400 Bad Request**

```
{
  "error": {
    "type": "BAD_REQUEST",
    "description": "User ID must be numeric."
  }
}
```

### Resource not found

[](#resource-not-found)

```
GET /users/999
Accept: application/json

```

**Response: 404 Not Found**

```
{
  "error": {
    "type": "RESOURCE_NOT_FOUND",
    "description": "User 999 not found."
  }
}
```

Response helpers
----------------

[](#response-helpers)

Helper methods provided by `AbstractAction` generate structured JSON responses. Each builds the appropriate `ActionPayload` and writes it to the response.

MethodWhen to useStatusError type`ok(mixed $data, mixed $meta = null, int $statusCode = 200)`Successful operation with data payload200 (or custom)—`badRequest(?string $description = null)`Request is malformed or violates business rules400`BAD_REQUEST``unauthorized(?string $description = null)`Request lacks valid authentication credentials401`UNAUTHENTICATED``forbidden(?string $description = null)`Authenticated caller lacks required permissions403`INSUFFICIENT_PRIVILEGES``notFound(?string $description = null)`Requested resource does not exist404`RESOURCE_NOT_FOUND``notAllowed(?string $description = null)`HTTP method not allowed for the resource405`NOT_ALLOWED``serverError(?string $description = null)`Unexpected server error occurred500`SERVER_ERROR``notImplemented(?string $description = null)`Requested functionality has not been implemented501`NOT_IMPLEMENTED`> **Note:** When the `description` parameter is `null`, the `description` field is omitted entirely from the error response. API consumers should treat `description` as an optional field.

For full control over the payload, call `json(ActionPayloadInterface $payload)` directly.

Request helpers
---------------

[](#request-helpers)

Helper methods are available for accessing request data in a consistent and predictable manner.

### Route arguments

[](#route-arguments)

Route arguments are extracted from the URL pattern matched by your router (e.g., `/users/{id}`).

- **`getArgs(): array`** — Returns all route arguments as an associative array
- **`resolveArg(string $name): string|int`** — Retrieves a route argument by name. Throws a RuntimeException if the argument is missing.

#### Example: Fetching a resource by ID

[](#example-fetching-a-resource-by-id)

```
declare(strict_types=1);

namespace App\Http\Actions;

use AndrewDyer\Actions\AbstractAction;
use Psr\Http\Message\ResponseInterface;

final class GetOrderAction extends AbstractAction
{
    protected function handle(): ResponseInterface
    {
        // Extract the order ID from the route
        $orderId = (int) $this->resolveArg('id');

        // Your domain logic here...
        $order = $this->fetchOrder($orderId);

        return $this->ok($order);
    }
}
```

**Request:**

```
GET /orders/12345
Accept: application/json

```

### Request body

[](#request-body)

The request body can be accessed as an associative array using `getParsedBody()`.

- **`getParsedBody(): array`** — Returns the parsed request body as an array. Returns an empty array if no body is present. Throws a RuntimeException if the body cannot be parsed as an array.
- **`resolveBodyParam(string $name, mixed $default = null): mixed`** — Retrieves a body parameter by name. If a default value is provided, the parameter is optional and the default is returned when missing. If no default value is provided, the parameter is required and a RuntimeException is thrown when missing.

#### Example: Creating a resource

[](#example-creating-a-resource)

```
declare(strict_types=1);

namespace App\Http\Actions;

use AndrewDyer\Actions\AbstractAction;
use Psr\Http\Message\ResponseInterface;

final class CreateProductAction extends AbstractAction
{
    protected function handle(): ResponseInterface
    {
        // Required parameters (throw exception if missing)
        $name = $this->resolveBodyParam('name');
        $price = $this->resolveBodyParam('price');

        // Optional parameter with default
        $description = $this->resolveBodyParam('description', 'No description provided');

        // Your domain logic here...
        $product = $this->createProduct($name, (float) $price, $description);

        return $this->ok($product, null, 201);
    }
}
```

**Request:**

```
POST /products
Accept: application/json
Content-Type: application/json

{
  "name": "Wireless Mouse",
  "price": 29.99
}

```

**Response: 201 Created**

```
{
  "data": {
    "id": 456,
    "name": "Wireless Mouse",
    "description": "No description provided",
    "price": 29.99
  }
}
```

### Query parameters

[](#query-parameters)

Query parameters from the request URI can be accessed using two methods:

- **`getQueryParams(): array`** — Returns all query parameters as an associative array
- **`resolveQueryParam(string $name, mixed $default = null): mixed`** — Retrieves a query parameter by name. If a default value is provided, the parameter is optional and the default is returned when missing. If no default value is provided, the parameter is required and a RuntimeException is thrown when missing.

#### Example: Pagination and filtering

[](#example-pagination-and-filtering)

```
declare(strict_types=1);

namespace App\Http\Actions;

use AndrewDyer\Actions\AbstractAction;
use Psr\Http\Message\ResponseInterface;

final class ListProductsAction extends AbstractAction
{
    protected function handle(): ResponseInterface
    {
        // Required parameter (throws exception if missing)
        $category = $this->resolveQueryParam('category');

        // Optional parameters with defaults
        $page = max(1, (int) $this->resolveQueryParam('page', 1));
        $limit = max(1, (int) $this->resolveQueryParam('limit', 20));

        // Your domain logic here...
        $products = $this->fetchProducts($category, $page, $limit);
        $total = $this->countProducts($category);

        return $this->ok(
            $products,
            [
                'total' => $total,
                'page' => $page,
                'perPage' => $limit,
                'totalPages' => (int) ceil($total / $limit),
            ]
        );
    }
}
```

**Request**

```
GET /products?category=electronics&page=2&limit=10
Accept: application/json

```

**Response: 200 OK**

```
{
  "data": [...],
  "meta": {
    "total": 156,
    "page": 2,
    "perPage": 10,
    "totalPages": 16
  }
}
```

#### Example: Array query parameters

[](#example-array-query-parameters)

Query parameters may also contain array values (for example, `?tags[]=foo&tags[]=bar&tags[]=baz`):

```
protected function handle(): ResponseInterface
{
    // Resolves to ['foo', 'bar', 'baz']
    $tags = $this->resolveQueryParam('tags');

    // Your domain logic here...
    $items = $this->findByTags($tags);

    return $this->ok(['items' => $items]);
}
```

Exception handling
------------------

[](#exception-handling)

Domain exceptions are caught automatically by `AbstractAction` and mapped to appropriate HTTP responses. This is useful when exceptions are thrown from services, repositories, or other domain logic that should not be coupled to HTTP concerns. Extend the base exception classes to create domain-specific exceptions.

Base exceptionWhen to useStatusError type`BadRequestException`Request is malformed or violates business rules400`BAD_REQUEST``UnauthenticatedException`Request lacks valid authentication credentials401`UNAUTHENTICATED``ForbiddenException`Authenticated caller lacks required permissions403`INSUFFICIENT_PRIVILEGES``NotFoundException`Requested resource does not exist404`RESOURCE_NOT_FOUND``NotImplementedException`Requested functionality has not been implemented501`NOT_IMPLEMENTED`> **Note:** When an exception has an empty message, the `description` field is omitted from the error response. API consumers should treat `description` as an optional field.

Example:

```
declare(strict_types=1);

namespace App\Domain\Exceptions;

use AndrewDyer\Actions\Exceptions\NotFoundException;

final class UserNotFoundException extends NotFoundException
{
    public function __construct(int $id)
    {
        parent::__construct("User {$id} not found.");
    }
}
```

License
-------

[](#license)

Licensed under the [MIT license](https://opensource.org/licenses/MIT) and is free for private or commercial projects.

###  Health Score

47

—

FairBetter than 93% of packages

Maintenance97

Actively maintained with recent releases

Popularity14

Limited adoption so far

Community8

Small or concentrated contributor base

Maturity57

Maturing project, gaining track record

 Bus Factor1

Top contributor holds 100% of commits — single point of failure

How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window.

**Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores.

**Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement.

**Maturity (30%)** — Project age, version count, PHP version support, and release stability.

###  Release Activity

Cadence

Every ~5 days

Total

13

Last Release

26d ago

Major Versions

0.6.0 → 1.0.02026-05-20

### Community

Maintainers

![](https://www.gravatar.com/avatar/666597ea6e46748a89fe8764d1a45b4d0da97daf1bb1e9770ea34ae41f706d08?d=identicon)[andrewdyer](/maintainers/andrewdyer)

---

Top Contributors

[![andrewdyer](https://avatars.githubusercontent.com/u/8114523?v=4)](https://github.com/andrewdyer "andrewdyer (38 commits)")

---

Tags

actionsapiframework-agnosticjson-apiphppsr-7psr-7phpapiJSON-APIactionsframework agnostic

###  Code Quality

TestsPHPUnit

Code StylePHP CS Fixer

### Embed Badge

![Health badge](/badges/andrewdyer-actions/health.svg)

```
[![Health](https://phpackages.com/badges/andrewdyer-actions/health.svg)](https://phpackages.com/packages/andrewdyer-actions)
```

###  Alternatives

[guzzlehttp/psr7

PSR-7 message implementation that also provides common utility methods

7.9k1.1B3.7k](/packages/guzzlehttp-psr7)[telnyx/telnyx-php

Official Telnyx PHP SDK — APIs for Voice, SMS, MMS, WhatsApp, Fax, SIP Trunking, Wireless IoT, Call Control, and more. Build global communications on Telnyx's private carrier-grade network.

35729.6k2](/packages/telnyx-telnyx-php)[claude-php/claude-php-sdk

A universal, framework-agnostic PHP SDK for the Anthropic Claude API with PSR compliance

14640.4k2](/packages/claude-php-claude-php-sdk)[huaweicloud/huaweicloud-sdk-php

Huawei Cloud SDK for PHP

1830.2k2](/packages/huaweicloud-huaweicloud-sdk-php)[genkgo/archive-stream

Stream a ZIP file (memory efficient) as a PSR-7 message

3064.2k](/packages/genkgo-archive-stream)

PHPackages © 2026

[Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)