README

Part of the ndapi package. Provides discovery of HTTP response formats as well as a variety of responses for reporting Laravel exceptions in meaningful ways.

Usage

Responses

When enabled, a variety of response macros will be added to Laravel's ResponseFactory class, making them accessible across your project.

response()->success($data, Paginator|CursorPaginator|null $paginator = null)
	response()->accepted($data, ?string $url = null)
	response()->created($data, ?string $url = null)
response()->fail(string $message, $data = null)
response()->error(string $message, $data = null)

All of the responses will generated in a format that acts as a slight superset of JSend. The appropriate HTTP status codes will be set.

The accepted/created responses allow passing a URL and you are encouraged to provide the URL to the resource that was created or to an endpoint to fetch the status of the accepted request.

Exceptions

This package automatically adds an exception renderer which handles returning appropriately formatted responses for a variety of common Laravel exceptions with the correct HTTP status code.

This includes:

• AuthenticationException
• AuthorizationException
• ModelNotFoundException
• NotFoundHttpException
• ValidationException

Additionally, a more general response is registered to report any other exception as an error.

Extending

You can register new response types with the factory by adding the Nucleardog\Api\Http\Attributes\Response attribute. The attribute should specify a key which is used as the method name. When the method is called on the response factory, your class will be instantiated with all passed arguments as constructor parameters, and the response() method called to return a response object.

You can register new exception handlers by adding the Nucleardog\Api\Http\Attributes\ExceptionResponse attribute to your response. The attribute requires you to specify the exception class your response handles. Your response class will be instantiated with the exception passed as its only constructor argument, and the response() method called to return a response object.

Tests

Phpunit is included in a separate composer file and must be explicitly installed:

$ cd tools/phpunit/
$ composer install

Once installed, the tests can be run from the root package folder with:

$ composer test

Legal

Copyright 2024 Adam Pippin hello@adampippin.ca

Licensed under the Apache License, Version 2.0 (the "License"); you may not use this project except in compliance with the License. You may obtain a copy of the License at

http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.