error.inc

Index

• ensure
• plague
• append_debug_info
• variable_violation_message
• ensure_bool
• ensure_int
• ensure_float
• ensure_numeric
• ensure_string
• ensure_scalar
• ensure_resource
• ensure_array
• ensure_callable
• ensure_non_null
• ensure_non_empty
• ensure_positive_int
• ensure_non_negative_int
• ensure_between
• ensure_in_array
• ensure_not_in_array
• ensure_instance_of

Detail

ensure

void ensure(bool $bool, string $message)

• Throw the LogicException with $message if $bool is false.
• Example:

function concatenate($key, $value)
{
   ensure(is_int($former) || is_string($latter), '$former must be "int" or "string"');

   return "$key => " . (is_scalar($value) ? $latter : gettype($latter));
}

plague

void plague(string $message)

• Throw the RuntimeException with $message.
• Example:

$file    = 'example.txt';
$handler = fopen($file, 'r') or plague("\"$file\" probably doesn't exist!");

append_debug_info

string append_debug_info(string $message, int $added_depth = 0)

• Return the $message with debug information.
• Notice: This function calls debug_backtrace(). $added_depth indicates the added depth for the stack trace.
• Example: example.php

<?php

require PATH_TO_PHP_UTILS . 'php-utils.php';

function square($int)
{
   var_dump(append_debug_info('type of \$int: ' . gettype($int)));
   return $int * $int;
}

square(1);
square('1');

• Result:

$ php example.php
string(94) "square(): type of $int: integer [FILE: example.php, LINE: 11]"
string(93) "square(): type of $int: string [FILE: example.php, LINE: 12]"

variable_violation_message

string variable_violation_message(string $subject, string $expected, string $actual, int $added_depth = 0)

• Return the violation message for the variable.
• Notice This function calls append_debug_info(). $added_depth indicates the added depth for the stack trace.
• Example: example.php

<?php

require PATH_TO_PHP_UTILS . 'php-utils.php';

function filter(array $array, $closure)
{
   if (!(is_null($closure) || is_callable($closure))) {
      throw new LogicException(variable_violation_message('$closure', '"null" or an object of "Closure"', gettype($closure)));
   }
   return array_values(array_filter($array, $closure));
}

filter([1, 2, 3], 'is_three'); // is_three() isn't defined!

• Result:

$ php example.php
PHP Fatal error:  Uncaught exception 'LogicException' with message 'filter(): $closure must be "null" or an object of "Closure", actually string [FILE: example.php, LINE: 13]' in example.php:8
Stack trace:
#0 example.php(13): filter(Array, 'is_three')
#1 {main}
  thrown in example.php on line 8

ensure_bool

void ensure_bool(mixed &$var, string $subject)

• Throw the DomainException with the error message which has $subject as its subject if $var is not boolean.
• Example:

function set_error_report($exclude_notice = false)
{
   ensure_bool($exclude_notice, 'The 1st argument');

   error_reporting(E_ALL & ~($exclude_notice ? E_NOTICE : 0));
}

ensure_int

void ensure_int(mixed &$var, string $subject)

• integer version of ensure_bool

ensure_float

void ensure_float(mixed &$var, string $subject)

• float version of ensure_bool

ensure_numeric

void ensure_numeric(mixed &$var, string $subject)

• numeric version of ensure_bool

ensure_string

void ensure_string(mixed &$var, string $subject)

• string version of ensure_bool

ensure_scalar

void ensure_scalar(mixed &$var, string $subject)

• scalar version of ensure_bool

ensure_resource

void ensure_resource(mixed &$var, string $subject)

• resource version of ensure_bool

ensure_array

void ensure_array(mixed &$var, string $subject)

• array version of ensure_bool

ensure_callable

void ensure_callable(mixed &$var, string $subject)

• callable version of ensure_bool

ensure_non_null

void ensure_non_null(mixed &$var, string $subject)

• Throw DomainException with the error message which has $subject as its subject if $var is null.
• Example: see ensure_bool.

ensure_non_empty

void ensure_non_empty(mixed &$var, string $subject)

• empty version of ensure_non_null

ensure_positive_int

void ensure_positive_int(mixed &$var, string $subject)

• Throw DomainException with the error message which has $subject as its subject if $var is not int or non-positive int.
• Example: see ensure_bool.

ensure_non_negative_int

void ensure_non_negative_int(mixed &$var, string $subject)

• non-negative version of ensure_positive

ensure_between

void ensure_between(mixed &$var, mixed $min, mixed $max, string $subject)

• Throw DomainException with the error message which has $subject as its subject if $var is greater than or equal to $min and less than or equal to $max.
• Example:

$min = 0;
$max = 5;
ensure_between($_POST['review'], $min, $max, 'The review value');

ensure_in_array

void ensure_in_array(mixed &$var, array &$white_list, string $subject)

• Throw DomainException with the error message which has $subject as its subject if $var is not in $white_list.
• Example:

$valid_choices = ['Windows 8.1', 'Windows 8', 'Windows 7'];
ensure_in_array($_POST['choice'], $valid_choices, 'The choice of Windows version');

ensure_not_in_array

void ensure_not_in_array(mixed &$var, array &$black_list, string $subject)

• Throw DomainException with the error message which has $subject as its subject if $var is in $black_list.
• Example:

$invalid_emails = ['example@gmail.com', 'example@yahoo.co.jp', 'example@outlook.com'];
ensure_not_in_array($_POST['email'], $invlid_emails, 'The email');

ensure_instance_of

void ensure_instance_of(mixed &$var, string $subject, string ...$classes)

• Throw DomainException with the error message which has $subject as its subject if $var is not any object of $classes.
• Example:

function echo_error_message($e)
{
   ensure_instance_of($e, 'The first argument', 'LogicException', 'RuntimeException');

   echo $e->getMessage(), PHP_EOL;
}