silverstripe-environmentcheck/README.md

106 lines
5.5 KiB
Markdown
Raw Normal View History

# 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.
2012-01-10 07:31:03 +01:00
* `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.
2012-01-20 18:25:02 +01:00
* **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 a unit test into the environment checker!
## Installation
Register checks in your own `_config.php` - see the `_config.php` in this module for some defaults.
:::php
EnvironmentCheckSuite::register('health', 'DatabaseCheck', "Can we connect to the database?");
EnvironmentCheckSuite::register('check', 'URLCheck("")', "Is the homepage accessible?");
## Available checks
* `DatabaseCheck`: Check that the connection to the database is working, by ensuring that the table exists and that the table contain some records.
* `URLCheck`: Check that a given URL is functioning, by default, the homepage.
* `HasFunctionCheck`: Check that the given function exists.
This can be used to check that PHP modules or features are installed.
* `HasClassCheck`: Check that the given class exists.
This can be used to check that PHP modules or features are installed.
* `FileWriteableCheck`: Check that the given file is writeable.
* `FileAgeCheck`: Checks for the maximum age of one or more files or folders.
Useful for files which should be frequently auto-generated,
like static caches, as well as for backup files and folders.
* `ExternalURLCheck`: Checks that one or more URLs are reachable via HTTP.
* `SMTPConnectCheck`: Checks if the SMTP connection configured through PHP.ini works as expected.
## Adding more checks
2012-01-20 18:24:11 +01:00
To add more checks, you should put additional `EnvironmentCheckSuite::register` calls into your `_config.php`. See the `_config.php` file of this module 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.
2012-01-10 07:31:03 +01:00
The module comes bundled with a few checks in `DefaultHealthChecks.php`. However, to test your own application, you probably want to write custom checks.
2012-01-10 07:31:03 +01:00
* 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
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
2012-01-10 07:31:03 +01:00
* `$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.
2012-01-20 18:33:45 +01:00
See `EnvironmentChecker.ss` to see how these can be used to build a UI.