README

安装

在创建 PhpSlides 项目后，导航到项目目录，并使用以下命令安装 PhpSlides-Status 包

composer require phpslides/status

或者直接从发布版本下载 zip 文件，解压文件并将其添加到 PhpSlides 项目的文件夹中。

下载 phpslides\status zip

说明

使用 Status() 类函数

为 API 响应创建一个 Status 实例。这用于 PhpSlides API 控制器类

<?php

namespace App\Controller\Api;

use PhpSlides\Status;
use PhpSlides\Http\Interface\ApiController;

final class UserController implements ApiController
{
   public function index() {
      $status = new Status();
   }
}

?>

您可以将字符串值传递给 Status() 函数参数，该参数默认为 ResponseType::JSON，使用 Response 命名空间 PhpSlides\Enums\ResponseType

在返回 JSON 格式的值中。参数包括此枚举值类型

use PhpSlides\Enums\ResponseType;

ResponseType::JSON;
ResponseType::HTML;
ResponseType::CSV;
ResponseType::XML;

new Status(ResponseType::JSON);

如果参数包含除 enum ResponseType 值 之外的任何值，它将返回默认值数组形式，这不被推荐。

一些函数和方法

success() 方法

使用 success() 方法返回默认成功消息。

<?php

namespace App\Controller\Api;

use PhpSlides\Status;
use PhpSlides\Enums\ResponseType;
use PhpSlides\Http\Interface\ApiController;

final class UserController implements ApiController {
   public function index() {
      $status = new Status(Response::JSON);
      return $status->success();
   }
}

?>

success() 方法接受 2 个参数，$data 用于渲染和 $status，这是状态码。

第一个参数可以是 Array 或 String，第二个参数是来自 StatusCode 静态类的 Integer。它返回 ResponseType::<type>，这是在 Status() 函数中传递的参数。

use PhpSlides\StatusCode;

$user = [
    "name": "John Doe",
    "email": "john@doe.com"
];
return (new Status())->success($user, StatusCode::OK);

error() 方法

使用 error() 方法返回错误 API 消息。它也接受 2 个参数，第一个是 Array 或 String，第二个是用于设置 http_response_code 的 Integer，其默认值为 StatusCode::INTERNAL_SERVER_ERROR，即 500

它也返回 ResponseType::<type>

return (new Status(ResponseType::JSON))->error('User not Found', StatusCode::NOT_FOUND);

success() 和 error() 方法的完整代码

如果没有指定 Status() 的参数，默认返回 ResponseType::JSON，用于以 JSON 格式返回响应

<?php

namespace App\Controller\Api;

use PhpSlides\Http\Interface\ApiController;
use PhpSlides\Http\ResponseType;
use PhpSlides\StatusCode;
use PhpSlides\Status;

final class UserController extends Controller
{
   public function index(int $user_id) {
      $status = new Status();

      if ($user_id === 1) {
         $user = [
             'name': 'John Doe',
             'email': 'john@doe.com',
             'user_id': $user_id
         ];

         $response = $status->success($user); // by default the second parameter is `StatusCode::OK`
      } else {
         // not found message
         $response = $status->error("User user_id=$user_id is not found", StatusCode::NOT_FOUND);
      }

      return $response; // return message as a JSON format `Response::JSON`
   }
}

?>

命名空间和 Status 接口

命名空间

\PhpSlides\Status()

\PhpSlides\StatusCode

\PhpSlides\StatusText

\PhpSlides\Http\Response

\PhpSlides\Enums\ResponseType

\PhpSlides\Interface\StatusInterface

\PhpSlides\Interface\ResponseInterface

\PhpSlides\Status\Exception\ApiException()

\PhpSlides\Status\Exception\ExceptionInterface

Status() 接口方法

__construct(string $response = ResponseType::JSON)

public function getStatus (): int;

public function getStatusText (): string;

public function getMessage (): mixed;

public function get (): string|array;

public function getJson (): string;

public function set (mixed $data, int $status = StatusCode::NO_CONTENT, string $statusText = StatusText::NO_CONTENT ): void;

public function setStatus (int $status): void;

public function setStatusText (string $statusText): void;

public function setMessage (mixed $message): void;

public function error (array|string $data, int $status = StatusCode::INTERNAL_SERVER_ERROR): string|array;

public function success (array|string $data, int $status = StatusCode::OK): string|array;

Response{} 接口方法

public static function json(array $data = [], int $status = StatusCode::OK): string;

public static function html(array $data = [], int $status = StatusCode::OK): string;

public static function csv(array $data = [], int $status = StatusCode::OK): string;

public static function xml(array $data = [], int $status = StatusCode::OK): string;

public static function array(array $data = [], int $status = StatusCode::UNSUPPORTED_MEDIA_TYPE): array;

枚举 ResponseType{} 接口

const JSON = 'JSON';

const HTML = 'HTML';

const CSV = 'CSV';

const XML = 'XML';

文档

状态类方法

Status 类提供了几种方法来管理和格式化不同格式的 API 响应，例如 JSON、HTML、CSV 或 XML。以下是使用它们的快速指南。

`__construct(string $response = ResponseType::JSON)`

构造函数初始化一个新的 Status 实例。您可以通过传递一个 ResponseType 枚举值来指定响应格式。如果没有传递值，则默认为 ResponseType::JSON。

$status = new Status(); // Defaults to JSON
$status = new Status(ResponseType::HTML); // Initializes with HTML response type

`getStatus(): int`

此方法检索当前 HTTP 状态码。

$httpStatus = $status->getStatus(); // Returns the current HTTP status code

`getStatusText(): string`

检索与 HTTP 状态码相对应的状态文本。

$statusText = $status->getStatusText(); // Returns status text, e.g., "OK" for 200

`getMessage(): mixed`

获取用于响应的消息。这可能是一个数组、字符串或任何数据类型，具体取决于响应。

$message = $status->getMessage(); // Returns the message set in the response

`get(): string|array`

以原始形式检索响应数据，可以是字符串或数组。

$response = $status->get(); // Returns the raw response data

`getJson(): string`

将响应数据转换为 JSON 字符串。此方法在您需要显式获取 JSON 格式的响应时很有用。

$jsonResponse = $status->getJson(); // Returns the response as a JSON string

`set(mixed $data, int $status = StatusCode::NO_CONTENT, string $statusText = StatusText::NO_CONTENT): void`

设置响应数据、状态码和状态文本。此方法用于手动定义响应属性。

$status->set(['key' => 'value'], StatusCode::OK, StatusText::OK); // Sets custom response data

`setStatus(int $status): void`

设置 HTTP 状态码。

$status->setStatus(StatusCode::OK); // Manually set the status code

`setStatusText(string $statusText): void`

设置与 HTTP 状态码相对应的状态文本。

$status->setStatusText(StatusText::OK); // Manually set the status text

`setMessage(mixed $message): void`

设置响应的消息。此消息可以是数组、字符串或任何其他数据类型。

$status->setMessage('Success message'); // Manually set the response message

`error(array|string $data, int $status = StatusCode::INTERNAL_SERVER_ERROR): string|array`

创建一个错误响应。您可以传递错误消息和一个可选的状态码。默认情况下，它将状态码设置为 500（内部服务器错误）。

$errorResponse = $status->error('An error occurred', StatusCode::BAD_REQUEST); // Returns error response in JSON

`success(array|string $data, int $status = StatusCode::OK): string|array`

创建一个成功响应。您可以传递响应数据和一个可选的状态码。默认情况下，它将状态码设置为 200（OK）。

$successResponse = $status->success(['message' => 'Operation successful']); // Returns success response in JSON

响应类方法

Response 类提供了静态方法来直接以不同格式返回响应。这些方法在您想要快速输出数据而不创建 Status 实例时特别有用。

`json(array $data = [], int $status = StatusCode::OK): string`

以指定的 HTTP 状态码返回数据格式为 JSON。

$response = Response::json(['key' => 'value'], StatusCode::CREATED); // Outputs JSON response

`html(array $data = [], int $status = StatusCode::OK): string`

以 HTML 格式返回数据。

$response = Response::html(['key' => 'value'], StatusCode::OK); // Outputs HTML response

`csv(array $data = [], int $status = StatusCode::OK): string`

以 CSV 格式返回数据。

$response = Response::csv(['key' => 'value'], StatusCode::OK); // Outputs CSV response

`xml(array $data = [], int $status = StatusCode::OK): string`

以 XML 格式返回数据。

$response = Response::xml(['key' => 'value'], StatusCode::OK); // Outputs XML response

`array(array $data = [], int $status = StatusCode::UNSUPPORTED_MEDIA_TYPE): array`

以 PHP 数组的形式返回数据。这是在没有指定其他格式时的后备选项。

$response = Response::array(['key' => 'value']); // Outputs data as an array

enum ResponseType

ResponseType 枚举提供了用于支持响应格式的预定义常量。这些包括

ResponseType::JSON - 用于 JSON 格式
ResponseType::HTML - 用于 HTML 格式
ResponseType::CSV - 用于 CSV 格式
ResponseType::XML - 用于 XML 格式

在 Status 类中指定响应类型时使用这些常量。

$status = new Status(ResponseType::XML); // Initializes the Status class with XML response type

phpslides / status

维护者

详情