README

Overview

This bundle provides a mini-framework for a Symfony application to be queried on it's current "health". The specifics of what "healthy" and "unhealthy" are depend on the application and must be defined. However, the boilerplate of creating Symfony Controllers and Console Commands to make a query (and provide a health report) are taken care of.

Installation

The only supported method of installing the bundle is via composer:

composer require cushon/health-bundle

Recommended Packages and Extensions

Several libraries and packages are included in the suggest section of the composer.jspn. The bundle utilises the Set class of PHP Data Structures. However, the DS polyfill is used to ensure that the bundle can run on a stack without the extension.

Configuration

API Error Response Code

When a service is deemed to be unhealthy, the API endpoint will return a 500 status code by default. This is configurable by adding the following to your Symfony config YAML file:

    cushon_health:
        error_response_code: !php/const Symfony\Component\HttpFoundation\Response::HTTP_SERVICE_UNAVAILABLE

Note that the above snippet illustrates an error response code of 503. You can specify any status code here, including a 200 if you wish.

The Console Command

Usage

bin/console cushon:health

An example of the output:

The JSON Api Endpoint:

The default endpoint is available at /health.

Getting Started

Please see the section on creating a Dependency Check.

Structure

Directories used in production builds

/src: Contains the bundle code. With minor deviations, this follows the standard design for the Symfony Bundle System.

/docs: Collation of documentation and metrics for the project.

Directories & Files Not Included In Releases

The following files and directories are not included in the release to reduce archive complexity. Should you want to see the entire project, you should either clone the project locally or choose not to prefer the distribution in your composer file.

/app - Contains a Symfony 6 app for running integration and behavioural tests, and to provide examples

/docker - Contains Dockerfiles and nginx configuration to run the API example and used for testing against PHP versions. The docker-compose.yml in the root of the project is similarly removed.

/features - Contains Gherkin simplified scenarions to drive behavioural testing and provide specification by example.

/tests - The tests are excluded when using a release.

Additionally, files to run testing and quality tooling (e.g. infection.json, phpunit.xml.dist) are also omitted.

Testing & Quality

The bundle is tested with both unit testing and behavioural testing with phpUnit and behat respectively.