Document the Validator class to make Serenata happy

This commit is contained in:
Starbeamrainbowlabs 2019-06-13 21:46:30 +01:00
parent 890418c42e
commit bbf3d02b5d
Signed by: sbrl
GPG Key ID: 1BE5172E637709C2
1 changed files with 94 additions and 7 deletions

View File

@ -1,15 +1,35 @@
<?php
namespace AirQuality;
/**
* Makes validating user input easy.
*/
class Validator {
/**
* The data that we test against.
* @var array
*/
private $target_data;
/**
* An array of tests that we should run against the above target data.
* @var callable[]
*/
private $tests = [];
/**
* Creates a new validator instance.
* @param array $in_target_data The target data to test against.
*/
public function __construct($in_target_data) {
$this->target_data = $in_target_data;
}
public function exists($key) {
/**
* Checks that the given key exists.
* @param string $key The key that should exist.
* @return void
*/
public function exists(string $key) {
$this->add_test(
$key,
function($data) { return isset($data); },
@ -18,7 +38,12 @@ class Validator {
);
}
public function is_numberish($key) {
/**
* Ensures that the value associated with the specified key is a number.
* @param string $key The key to check the value of.
* @return void
*/
public function is_numberish(string $key) {
$this->add_test(
$key,
function($data) { return is_numeric($data); },
@ -26,7 +51,15 @@ class Validator {
"Error: The field $key in your request isn't a number."
);
}
public function is_min_length($key, $min_length) {
/**
* Checks that the value associated with the given key is a least a given
* number of characters long.
* This test is unicode aware.
* @param string $key The key to check the value of.
* @param int $min_length The minimum length required.
* @return void
*/
public function is_min_length(string $key, int $min_length) {
$this->add_test(
$key,
function($data) use ($min_length) { return mb_strlen($data) >= $min_length; },
@ -34,7 +67,15 @@ class Validator {
"Error: The field $key is too short - it must be a minimum of $min_length characters."
);
}
public function is_max_length($key, $max_length) {
/**
* Checks that the value associated with the given key is at most a given
* number of characters long.
* This test is unicode aware.
* @param string $key The key to check the value of.
* @param int $max_length The maximum length allowed.
* @return void
*/
public function is_max_length(string $key, int $max_length) {
$this->add_test(
$key,
function($data) use ($max_length) { return mb_strlen($data) <= $max_length; },
@ -42,6 +83,13 @@ class Validator {
"Error: The field $key is too long - it must be a maximum of $max_length characters."
);
}
/**
* Ensures that the value associated with the given key is one of a
* predefined set of values.
* @param string $key The key to check the associated value of.
* @param array $values The array of values to test against.
* @param int $error_code The HTTP response code to return if the test fails.
*/
public function is_preset_value(string $key, array $values, int $error_code) {
$this->add_test(
$key,
@ -53,6 +101,13 @@ class Validator {
);
}
/**
* Ensures that 2 keys have the same value.
* @param string $key_a The first key.
* @param string $key_b The second key.
* @param string $message The message to return if the test fails.
* @return void
*/
public function are_equal($key_a, $key_b, $message) {
$key_b_data = $this->target_data[$key_b];
$this->add_test(
@ -65,6 +120,14 @@ class Validator {
);
}
/**
* Ensures the value attached to a given key matches the specified regular
* expression.
* @param string $key The key to check the value of.
* @param string $regex The regular expression to test the value with.
* @param string $message Thee message to return if the test fails.
* @return void
*/
public function matches_regex($key, $regex, $message) {
$this->add_test(
$key,
@ -76,7 +139,11 @@ class Validator {
);
}
/**
* Ensures the value associated with the specified key is a valid datetime.
* @param string $key The key of the value to check.
* @return void
*/
public function is_datetime($key) {
$this->add_test(
$key,
@ -88,7 +155,16 @@ class Validator {
);
}
public function add_test($key, $test, $response_code, $message) {
/**
* Add a custom test directly.
* It's suggested that you don't call this directly - insteaad edit this
* class' code to allow everyone to benefit from the improvement :-)
* @param string $key The key to test the value of.
* @param callable $test The test to run.
* @param int $response_code The HTTP response code to return if the test fails.
* @param string $message The message to send if the test fails.
*/
public function add_test(string $key, callable $test, int $response_code, string $message) {
$new_test = [
"key" => $key,
"test" => $test,
@ -99,12 +175,23 @@ class Validator {
$this->tests[] = $new_test;
}
protected function send_error($code, $message) {
/**
* Sends an error to the client and then exits.
* Don't put code after calling this method - it won't get executed!
* @param int $code The HTTP response code to send.
* @param string $message The plain-text message to send.
*/
protected function send_error(int $code, string $message) {
http_response_code($code);
header("content-type: text/plain");
exit($message);
}
/**
* Runs all the tests added to the validator so far.
* Note that this won't return if a test fails.
* @return void
*/
public function run() {
foreach($this->tests as $test) {