Table of Contents
On this page

Exceptions

What are exceptions?

Exceptions are a powerful mechanism for handling errors and other exceptional conditions that may occur during the execution of a script. They provide a way to manage errors in a structured and controlled manner, separating error-handling code from regular code.

How we use exceptions

When it comes to handling exceptions, Dotkernel API relies on the usage of easy-to-understand, problem-specific exceptions. Below we will list the available custom exceptions.

BadRequestException thrown when

  • The Client tries to create/update resource, but the request data is invalid/incomplete (example: client tries to create an account, but does not send the required identity field)

ConflictException thrown when

  • The resource cannot be created because a different resource with the same identifier already exists (example: cannot change existing user's identity because another user with the same identity already exists)
  • The resource cannot change its state because it is already in the specified state (example: user cannot be activated because it is already active)

ExpiredException thrown when

  • The resource cannot be accessed
    • because it has expired (example: account activation link)
    • because it has been consumed (example: one-time password)

ForbiddenException thrown when

  • The resource cannot be accessed by the authenticated client's role (example: client authenticated as regular user sends a GET /admin request)

MethodNotAllowedException thrown when

  • The client tries to interact with a resource via an invalid HTTP request method (example: client sends a PATCH /avatar request)

NotFoundException thrown when

  • The client tries to interact with a resource that does not exist on the server (example: client sends a GET /resource-does-not-exist request)

UnauthorizedException thrown when

  • The resource cannot be accessed because the client is not authenticated (example: unauthenticated client sends a GET /admin request)

How it works

During a request, if there is no uncaught exception, Dotkernel API will return a JSON response with the data provided by the handler that processed the request.

Otherwise, it will build and send a response based on the exception thrown:

  • BadRequestException will return a 400 Bad Request response
  • UnauthorizedException will return a 401 Unauthorized response
  • ForbiddenException will return a 403 Forbidden response
  • OutOfBoundsException and NotFoundException will return a 404 Not Found response
  • MethodNotAllowedException will return a 405 Method Not Allowed response
  • ConflictException will return a 409 Conflict response
  • ExpiredException will return a 410 Gone response
  • MailException, RuntimeException and the generic Exception will return a 500 Internal Server Error response

How to extend

In this example we will

  • Create a custom exception called CustomException
  • Place it next to the already existing custom exceptions (you can use your preferred location)
  • Return a custom HTTP status code when CustomException is encountered.

Step 1: Create exception file

Navigate to the directory src/App/src/Handler/Exception and create a PHP class called CustomException.php. Open CustomException.php and add the following content:

<?php

declare(strict_types=1);

namespace Api\App\Exception;

use Exception;

class CustomException extends Exception
{
}

Save and close the file.

Step 2: Use exception file

Open the file src/App/src/Handler/HomeHandler.php and at the beginning of the get method, place the following code:

throw new \Api\App\Exception\CustomException('some message');

Save and close the file.

Step 3: Test for failure

Access your API's home page URL and make sure it returns 500 Internal Server Error HTTP status code and the following content:

{
    "error": {
        "messages": [
            "some message"
        ]
    }
}

Step 4: Prepare for success

Open the file src/App/src/Handler/HandlerTrait.php and locate the handle method. Insert the following lines of code before the first catch statement:

        } catch (\Api\App\Exception\CustomException $exception) {
            return $this->errorResponse($exception->getMessage(), StatusCodeInterface::STATUS_IM_A_TEAPOT);

Save and close the file.

Step 5: Test for success

Access your API's home page URL, which should return the same content. Notice that this time it returns 418 I'm a teapot HTTP status code.