silverstripe-environmentcheck/README.md

# SilverStripe Environment Checker Module

Developed by Sam Minnée, thanks to Will Rossiter.

This module adds an API for running environment checks to your API.

 * `dev/health`` - A public URL that performs a quick check that this environment is functioning.  This could be tied to a load balancer, for example.
 * `dev/check` - An admin-only URL that performs a more comprehensive set of checks.  This could be tied to a deployment system, for example.

## Aren't these just unit tests?

Almost, but not really. Environment checks differ from unit tests in two important ways:

 * **They test environment specific settings.** Unit tests are designed to use dummy data and mock interfaces to external system.  Environment checks check the real systems and data that the given environment is actually connected to.
 * **They can't modify data.** Because these checks will run using production databases, they can't go modifying the data in there. This is the biggest reason why we haven't used the same base class as a unit test for writing environment checks - we wanted to make it impossible to accidentally plug the a unit test into the environment checker!

## Adding more checks

To add more checks, you should put additional `EnvironmentCheckSuite::register` calls into your `_config.php`.  See the `_config.php` file of this mode for examples.

	:::php
	EnvironmentCheckSuite::register('check', 'HasFunctionCheck("curl_init")', "Does PHP have CURL support?");
	EnvironmentCheckSuite::register('check', 'HasFunctionCheck("imagecreatetruecolor")', "Does PHP have GD2 support?");
	
The first argument is the name of the check suite.  There are two built-in check suites, "health", and "check", corresponding to the `dev/health` and `dev/check` URLs.  If you wish, you can create your own check suites and execute them on other URLs.

The module comes bundled with a few checks in DefaultHealthChecks.php.  However, to test your own application, you probably want to write custom checks.

 * Implement the EnvironmentCheck interface
 * Define the check() function, which returns a 2 element array:
   * The first element is one of `EnvironmentCheck::OK`, `EnvironmentCheck::WARNING`, `EnvironmentCheck::ERROR`, depending on the status of the check
   * The second element is a string describing the response.

Here is a simple example of how you might create a check to test your own code.  In this example, we are checking that an instance of the `MyGateway` class will return "foo" when `call()` is called on it.  Testing interfaces with 3rd party systems is a common use case for custom environment checks.

	:::php
	class MyGatewayCheck implements EnvironmentCheck {
		protected $checkTable;

		function check() {
			$g = new MyGateway;
			
			$response = $g->call();
			$expectedResponse = "foo";
			
			if($response == null) {
				return array(EnvironmentCheck::ERROR, "MyGateway didn't return a response");
			} else if($response != $expectedResponse) {
				return array(EnvironmentCheck::WARNING, "MyGateway returned unexpected response $response");
			} else {
				return array(EnvironmentCheck::OK, "");
			}
		}
	}
	
Once you have created your custom check class, don't forget to register it in a check suite
	
	:::php
	EnvironmentCheckSuite::register('check', 'MyGatewayCheck', "Can I connect to the gateway?");

### Using other environment check suites

"health" and "check" are the only environment check suites that we use because they aren

If you want to use the same UI as dev/health and dev/check, you can create an `EnvironmentChecker` object.  This class is a `RequestHandler` and so can be returned from an action handler.  The first argument to the `EnvironmentChecker` constructor is the suite name.  For example:

	class DevHealth extends Controller {
		function index() {
			$e = new EnvironmentChecker('health', 'Site health');
			return $e;
		}
	}
	
If you wish to embed an environment check suite in another, you can use the following call.

	$result = EnvironmentCheckSuite::inst("health")->run();
	
`$result` will contain a `EnvironmentCheckSuiteResult` object

 * **`$result->ShouldPass()`:** Return a boolean of whether or not the tests passed.
 * **`$result->Status()`:** The string "OK", "WARNING", or "ERROR", depending on the worst failure.
 * **`$result->Details()`:** A `DataObjectSet` of details about the result of each check in the suite.

See `EnvironmentChecker.ss` to see how these can be used to build a UI.