README

此软件包提供JsonApiError和JsonApiErrorResponse类，方便处理符合JSON:API规范的错误。

JsonApiErrorResponse扩展了来自symfony/http-foundation的JsonResponse，因此此软件包适用于使用该库的项目。

目录

• 安装
• 使用
  • 返回简单的错误响应
  • 返回多个错误
  • 从JsonApiError对象构建响应
• 本地开发
• 致谢

安装

通过composer安装此软件包

composer require wunderwerkio/jsonapi-error

使用

返回简单的错误响应

<?php

use Symfony\Component\HttpFoundation\Response;
use Wunderwerk\JsonApiError\JsonApiErrorResponse;

function someRequestHandler(): Response {
  return JsonApiErrorResponse::fromArray([
    'code' => 'application_error_code',
    'title' => 'An error occured!',
    'status' => 500,
  ]);
}

上述代码将生成以下有效载荷的JSON响应

{
  "errors": [{
    "status": 500,
    "code": "application_error_code",
    "title": "An error occured!"
  }]
}

返回多个错误

<?php

use Symfony\Component\HttpFoundation\Response;
use Wunderwerk\JsonApiError\JsonApiErrorResponse;

function someRequestHandler(): Response {
  return JsonApiErrorResponse::fromArrayMultiple([
    [
      'status' => 422,
      'code' => 'validation_failed',
      'title' => 'Invalid request payload',
      'detail' => 'The "name" field is required.',
      'source' => [
        'pointer' => '/data/name'
      ]
    ],
    [
      'status' => 422,
      'code' => 'validation_failed',
      'title' => 'Invalid request payload',
      'detail' => 'The "description" field is required.',
      'source' => [
        'pointer' => '/data/description'
      ]
    ],
  ]);
}

上述代码将生成以下有效载荷的JSON响应

{
  "errors": [{
    "status": 422,
    "code": "validation_failed",
    "title": "Invalid request payload",
    "detail": "The \"name\" field is required.",
    "source": {
      "pointer": "/data/name"
    }
  }, {
    "status": 422,
    "code": "validation_failed",
    "title": "Invalid request payload",
    "detail": "The \"description\" field is required.",
    "source": {
      "pointer": "/data/description"
    }
  }]
}

从JsonApiError对象构建响应

为了简化构建多个错误的响应，也可以通过传递一个包含JsonApiError对象的数组来构造响应。

<?php

use Symfony\Component\HttpFoundation\Request;
use Symfony\Component\HttpFoundation\JsonResponse;
use Symfony\Component\HttpFoundation\Response;
use Wunderwerk\JsonApiError\JsonApiError;
use Wunderwerk\JsonApiError\JsonApiErrorResponse;

function someRequestHandler(Request $request): Response {
  /** @var JsonApiError[] $errors */
  $errors = [];

  $payload = $request->getContent();
  $entity = json_decode($payload, TRUE);

  // Make sure 'name' field is set.
  if (!array_key_exists('name', $entity['data'])) {
    $errors[] = JsonApiError::fromArray([
      'status' => 422,
      'code' => 'validation_failed',
      'title' => 'Invalid request payload',
      'detail' => 'The "name" field is required.',
      'source' => [
        'pointer' => '/data/name',
      ],
    ]);
  }

  // Make sure 'description' field is set.
  if (!array_key_exists('description', $entity['data'])) {
    $errors[] = JsonApiError::fromArray([
      'status' => 422,
      'code' => 'validation_failed',
      'title' => 'Invalid request payload',
      'detail' => 'The "description" field is required.',
      'source' => [
        'pointer' => '/data/description',
      ],
    ]);
  }

  if (!empty($errors)) {
    return new JsonApiErrorResponse($errors);
  }

  return new JsonResponse([
    'status' => 'success',
  ]);
}

本地开发

可以通过DDEV创建一个无需本地安装PHP的本地开发环境。

ddev start

运行测试

ddev composer test

使用PHPStan进行代码检查

ddev composer analyze

致谢

本项目受到了以下优秀项目的启发

• SineMah/json-api-error