efureev/response-actions

Single Action structure for HTTP-Response

v2.1.2 2025-09-26 17:53 UTC

Requires

• php: ^8.4
• ext-mbstring: *

Requires (Dev)

• phpstan/phpstan: ^2.1
• phpunit/phpunit: ^12.3
• squizlabs/php_codesniffer: ^3.13.4
• symfony/var-dumper: ^7.3

MIT

• Eugene Fureev

• php
• response
• actions

README

Install

For php >= 8.4

composer require efureev/response-actions "^2.0"

Action Message Response Structure

{
  // Action Message block (can be overwritten with a custom key)
  "_responseAction": {
    // Request Execution Status. See: ResponseActions\\StatusEnum
    "status": "success",
    // list of actions: array of ResponseActions\\Actions\\Action
    "actions": [
      {
        // ... some action's body
      }
    ],
    // optional extra payload attached to the response action
    "extra": { }
  }
}

Actions

• Message
• Command
• Download
• Event
• Redirect

Common Action's Props

{
  // Action's Name
  "name": "message",
  // Action order to perform. Default = 0
  "order": 1,
  // Private action. boolean true or string channel name
  "private": true
}

Action Message

{
  // message to show to user
  "message": "It's done!",
  // Type of the message (optional when type is empty)
  "type": "info"
}

use ResponseActions\ResponseAction;
use ResponseActions\Actions\Message;

ResponseAction::successMessage('Operation has success!');

// Multi-message with different types
ResponseAction::errorMessage('Operation has failed!')
    ->addAction(Message::info('Try to restart page'));

Action Command

{
  // pending | done | failed
  "status": "failed",
  // optional description
  "description": "Reason..."
}

Helpers:

• ResponseAction::cmd() // pending
• ResponseAction::cmdDone() // done
• ResponseAction::cmdFailed() // failed

Action Download

{
  "url": "https://example.com/file.pdf",
  "file": "Readme.pdf",
  // optional params passed to the client handler
  "params": {}
}

Action Event

{
  "event": "uploadData",
  "params": {}
}

Action Redirect

{
  "url": "https://example.com",
  "target": "_blank",
  // native | router
  "type": "native",
  // HTTP code (when applicable)
  "code": 302
}

You can also use helpers:

• ResponseAction::redirect('https://example.com')
• ResponseActions\Actions\Redirect::router('/route')
• ResponseActions\Actions\Redirect::native('https://example.com')

Private

You can use private props and order:

use ResponseActions\ResponseAction;
use ResponseActions\Actions\{Event, Redirect, Download};

$responseAction = ResponseAction::successMessage('Operation has done!')
    ->addAction(
        new Event('log', ['saved!', 'continue watching...']),
        (new Event('uploadModuleData'))->private(),
        (new Event('uploadData'))->private('menu'),
        (new Event('refreshUser'))->private('authUser')->withOrder(1),
        (new Redirect('https://example.com'))->withOrder(5),
        (new Download('https://example.com/file.pdf', 'Readme.pdf'))->withOrder(2),
    );

ExtraData

You can attach extra data to the whole ResponseAction or to Message actions:

use ResponseActions\ResponseAction;

$responseAction = ResponseAction::cmdDone()
    ->withExtra(['any' => 'thing']);