You are here

Home » API reference » Common Functionality 7

cf_error.module in Common Functionality 7

Same filename and directory in other branches
  1. 7.2 modules/cf_error/cf_error.module

File

modules/cf_error/cf_error.module
View source 
<?php

/**
 * Implements hook_cf_permission_alter().
 *
 * @see cf_permission()
 */
function cf_error_cf_permission_alter(&$permissions) {
  if (!is_array($permissions)) {
    $permissions = array();
  }
  $permissions['view cf emergency messages'] = array(
    'title' => t("View Emergency Messages"),
    'description' => t("Grants permissions to view emergency messages presented by cf_error module."),
  );
  $permissions['view cf error messages'] = array(
    'title' => t("View Error Messages"),
    'description' => t("Grants permissions to view error messages presented by cf_error module."),
  );
  $permissions['view cf warning messages'] = array(
    'title' => t("View Warning Messages"),
    'description' => t("Grants permissions to view warning messages presented by cf_error module."),
  );
  $permissions['view cf information messages'] = array(
    'title' => t("View Information Messages"),
    'description' => t("Grants permissions to view information messages presented by cf_error module."),
  );
  $permissions['view cf debug messages'] = array(
    'title' => t("View Debug Messages"),
    'description' => t("Grants permissions to view debug messages presented by cf_error module."),
  );
}

/**
 * Appends the function name to the function_history.
 *
 * Why:
 *   This facilitates validating that the function_history is an array without
 *   having each and every usage need to manually do so.
 *
 * @param array $function_history
 *   An array of function names, ie: array('0' => 'my_function_name').
 * @param string $function_name
 *   The function name to append to the function_history.
 */
function cf_error_append_history(&$function_history, $function_name) {
  if (!is_array($function_history)) {
    $function_history = array();
  }
  if (!is_string($function_name)) {
    $function_history[] = __FUNCTION__;
    cf_error_empty_string($function_history, 'function_name');
    return;
  }
  $function_history[] = $function_name;
}

/**
 * Prints error messages to the screen.
 *
 * This uses drupal_set_message() and watchdog() to print the messages.
 *
 * Why:
 *   This facilitates printing the error messages without having each and every
 *   usage need to manually do so.
 *
 * @param string $message
 *   A string to display.
 * @param array $variables_array
 *   An array of string substitutions for anything in the $message string.
 * @param string $type
 *   The category to which this message belongs.
 *   Can be any string, but the general practice is to use the name of the
 *   module calling watchdog().
 * @param int $severity
 *   The severity of the message, as per RFC 3164. Possible values are
 *   WATCHDOG_ERROR, WATCHDOG_WARNING, etc.
 * @param array $function_history
 *   (optional) An array of function names, ie:
 *   array('0' => 'my_function_name').
 *
 * @see drupal_set_message()
 * @see watchdog()
 * @see watchdog_severity_levels()
 */
function cf_error_print_message($message, $variables_array, $type, $severity, array $function_history = array()) {
  cf_error_append_history($function_history, __FUNCTION__);
  if (!is_string($message)) {
    cf_error_empty_string($function_history, 'message');
    return;
  }
  if (!is_array($variables_array)) {
    cf_error_invalid_array($function_history, 'variables_array');
    return;
  }
  if (!is_string($type)) {
    cf_error_empty_string($function_history, 'type');
    return;
  }
  if (!is_numeric($severity)) {
    cf_error_empty_string($function_history, 'severity');
    return;
  }
  watchdog($type, $message . ", function history: %function_history", $variables_array, $severity);
  switch ($severity) {
    case WATCHDOG_EMERGENCY:
      if (user_access('view cf emergency messages')) {
        drupal_set_message(t($message, $variables_array), 'error', FALSE);
      }
      break;
    case WATCHDOG_ALERT:
    case WATCHDOG_CRITICAL:
    case WATCHDOG_ERROR:
      if (user_access('view cf error messages')) {
        drupal_set_message(t($message, $variables_array), 'error', FALSE);
      }
      break;
    case WATCHDOG_WARNING:
      if (user_access('view cf warning messages')) {
        drupal_set_message(t($message, $variables_array), 'warning', FALSE);
      }
      break;
    case WATCHDOG_NOTICE:
    case WATCHDOG_INFO:
      if (user_access('view cf information messages')) {
        drupal_set_message(t($message, $variables_array), 'status', FALSE);
      }
      break;
    case WATCHDOG_DEBUG:
      if (user_access('view cf debug messages')) {
        drupal_set_message(t($message, $variables_array), 'status', FALSE);
      }
      break;
  }
}

/**
 * Reports variables as invalid to the watchdog system.
 *
 * Why:
 *   Many drupal modules lack validation of parameter arguments.
 *   Checking these arguments is important for both integrity and security.
 *   Silently failing on these arguments will only hide the problem.
 *
 * @param array $function_history
 *   An array of function names, ie: array('0' => 'my_function_name').
 * @param string $argument_name
 *   The variable name of the argument in question.
 * @param string $why
 *   The specific reason for this watchdog report.
 * @param array $variables
 *   (optional) Locale safe parameter handling for all text found in the 'why'
 *   parameter.
 * @param int $severity
 *   (optional) This is passed directly to watchdog and represents the
 *   severity of the report.
 */
function cf_error_invalid_variable($function_history, $argument_name, $why, array $variables = array(), $severity = WATCHDOG_ERROR) {
  cf_error_append_history($function_history, __FUNCTION__);
  if ($argument_name == '') {
    cf_error_empty_string($function_history, 'argument_name');
  }
  if (!is_string($why)) {
    $why = "";
  }
  $variables_array = array_merge($variables, array(
    '%argument_name' => $argument_name,
    '%function_history' => print_r($function_history, TRUE),
  ));
  $message = "The argument '%argument_name' is invalid or has a problem, reason: " . $why;
  cf_error_print_message($message, $variables_array, 'bad variable', $severity, $function_history);
}

/**
 * Reports that a given argument is supposed to be a string but is not.
 *
 * Why:
 *   See reason from cf_error_invalid_variable() function.
 *
 * @param array $function_history
 *   An array of function names, ie: array('0' => 'my_function_name').
 * @param string $argument_name
 *   The variable name of the argument in question.
 * @param int $severity
 *   (optional) This is passed directly to watchdog and represents the
 *   severity of the report.
 */
function cf_error_not_string($function_history, $argument_name, $severity = WATCHDOG_ERROR) {
  cf_error_append_history($function_history, __FUNCTION__);
  if ($argument_name == '') {
    cf_error_empty_string($function_history, 'argument_name');
  }
  cf_error_invalid_variable($function_history, $argument_name, "Must be a string.", array(), $severity);
}

/**
 * Reports that a given argument is supposed to be non-empty string but is not.
 *
 * Why:
 *   See reason from cf_error_invalid_variable() function.
 *
 * @param array $function_history
 *   An array of function names, ie: array('0' => 'my_function_name').
 * @param string $argument_name
 *   The variable name of the argument in question.
 * @param int $severity
 *   (optional) This is passed directly to watchdog and represents the severity
 *    of the report.
 */
function cf_error_empty_string($function_history, $argument_name, $severity = WATCHDOG_ERROR) {
  cf_error_append_history($function_history, __FUNCTION__);
  if ($argument_name == '') {
    cf_error_empty_string($function_history, 'argument_name');
  }
  cf_error_invalid_variable($function_history, $argument_name, "Must not be an empty string.", array(), $severity);
}

/**
 * Reports that a given argument is supposed to be an array but is not.
 *
 * Why:
 *   See reason from cf_error_invalid_variable() function.
 *
 * @param array $function_history
 *   An array of function names, ie: array('0' => 'my_function_name').
 * @param string $argument_name
 *   The variable name of the argument in question.
 * @param int $severity
 *   (optional) This is passed directly to watchdog and represents the severity
 *   of the report.
 */
function cf_error_invalid_array($function_history, $argument_name, $severity = WATCHDOG_ERROR) {
  cf_error_append_history($function_history, __FUNCTION__);
  if ($argument_name == '') {
    cf_error_empty_string($function_history, 'argument_name', $severity);
  }
  cf_error_invalid_variable($function_history, $argument_name, "Not a valid array.", array(), $severity);
}

/**
 * Reports that a given argument is supposed to be an object but is not.
 *
 * Why:
 *   See reason from cf_error_invalid_variable() function.
 *
 * @param array $function_history
 *   An array of function names, ie: array('0' => 'my_function_name').
 * @param string $argument_name
 *   The variable name of the argument in question.
 * @param int $severity
 *   (optional) This is passed directly to watchdog and represents the severity
 *   of the report.
 */
function cf_error_invalid_object($function_history, $argument_name, $severity = WATCHDOG_ERROR) {
  cf_error_append_history($function_history, __FUNCTION__);
  if ($argument_name == '') {
    cf_error_empty_string($function_history, 'argument_name', $severity);
  }
  cf_error_invalid_variable($function_history, $argument_name, "Not a valid object.", array(), $severity);
}

/**
 * Reports that a given array is missing a specific array key.
 *
 * Why:
 *   See reason from cf_error_invalid_variable() function.
 *
 * @param array $function_history
 *   An array of function names, ie: array('0' => 'my_function_name').
 * @param string $argument_name
 *   The variable name of the argument in question.
 * @param string $key_name
 *   Name of the array key that is missing.
 * @param int $severity
 *   (optional) This is passed directly to watchdog and represents the severity
 *   of the report.
 */
function cf_error_missing_array_key($function_history, $argument_name, $key_name, $severity = WATCHDOG_ERROR) {
  cf_error_append_history($function_history, __FUNCTION__);
  if ($argument_name == '') {
    cf_error_empty_string($function_history, 'argument_name');
  }
  if ($key_name == '') {
    return cf_error_empty_string($function_history, 'key_name', $severity);
  }
  cf_error_invalid_variable($function_history, $argument_name, "The array key '%key_name' is missing.", array(
    '%key_name' => $key_name,
  ), $severity);
}

/**
 * Reports that a given object is missing a property.
 *
 * Why:
 *   See reason from cf_error_invalid_variable() function.
 *
 * @param array $function_history
 *   An array of function names, ie: array('0' => 'my_function_name').
 * @param string $argument_name
 *   The variable name of the argument in question.
 * @param string $property_name
 *   Name of the array key that is missing.
 * @param int $severity
 *   (optional) This is passed directly to watchdog and represents the severity
 *   of the report.
 */
function cf_error_missing_object_property($function_history, $argument_name, $property_name, $severity = WATCHDOG_ERROR) {
  cf_error_append_history($function_history, __FUNCTION__);
  if ($argument_name == '') {
    cf_error_empty_string($function_history, 'argument_name');
  }
  if ($property_name == '') {
    return cf_error_empty_string($function_history, 'property_name', $severity);
  }
  cf_error_invalid_variable($function_history, $argument_name, "The object property '%property_name' is missing.", array(
    '%property_name' => $property_name,
  ), $severity);
}

/**
 * Reports that a given argument is supposed to be numeric but is not.
 *
 * Why:
 *   See reason from cf_error_invalid_variable() function.
 *
 * @param array $function_history
 *   An array of function names, ie: array('0' => 'my_function_name').
 * @param string $argument_name
 *   The variable name of the argument in question.
 * @param int $severity
 *   (optional) This is passed directly to watchdog and represents the severity
 *   of the report.
 */
function cf_error_not_numeric($function_history, $argument_name, $severity = WATCHDOG_ERROR) {
  cf_error_append_history($function_history, __FUNCTION__);
  if ($argument_name == '') {
    cf_error_empty_string($function_history, 'argument_name');
  }
  cf_error_invalid_variable($function_history, $argument_name, "Not a numeric value.", array(), $severity);
}

/**
 * Reports query execution failures to the watchdog system.
 *
 * Why:
 *   All query execution calls should be wrapped in 'try' and 'catch' calls.
 *   Therefore, provide a function to be re-used in every catch for reporting
 *   the error.
 *
 * @param array $function_history
 *   An array of function names, ie: array('0' => 'my_function_name').
 * @param object $exception
 *   The query exception object.
 * @param int $severity
 *   (optional) This is passed directly to watchdog and represents the severity
 *   of the report.
 *
 */
function cf_error_on_query_execution($function_history, $exception, $severity = WATCHDOG_ERROR) {
  cf_error_append_history($function_history, __FUNCTION__);
  if (is_object($exception)) {
    $exception_message = $exception
      ->getMessage();
  }
  else {
    cf_error_invalid_object($function_history, 'exception');
    $exception_message = "";
  }
  $message = "Database Query Execution Failure: @exception";
  $variables_array = array(
    '@exception' => $exception_message,
    '%function_history' => print_r($function_history, TRUE),
  );
  cf_error_print_message($message, $variables_array, 'database', $severity, $function_history);
}

/**
 * Reports that a given argument is supposed to be an boolean but is not.
 *
 * Why:
 *   See reason from cf_error_invalid_variable() function.
 *
 * @param array $function_history
 *   An array of function names, ie: array('0' => 'my_function_name').
 * @param string $argument_name
 *   The variable name of the argument in question.
 * @param int $severity
 *   (optional) This is passed directly to watchdog and represents the severity
 *   of the report.
 */
function cf_error_invalid_bool($function_history, $argument_name, $severity = WATCHDOG_ERROR) {
  cf_error_append_history($function_history, __FUNCTION__);
  if ($argument_name == '') {
    cf_error_empty_string($function_history, 'argument_name', $severity);
  }
  cf_error_invalid_variable($function_history, $argument_name, "Not a valid boolean.", array(), $severity);
}

/**
 * Reports if a variable is not a float, double, or real.
 *
 * Why:
 *   See reason from cf_error_invalid_variable() function.
 *
 * @param array $function_history
 *   An array of function names, ie: array('0' => 'my_function_name').
 * @param string $argument_name
 *   The variable name of the argument in question.
 * @param int $severity
 *   (optional) This is passed directly to watchdog and represents the severity
 *   of the report.
 */
function cf_error_invalid_float($function_history, $argument_name, $severity = WATCHDOG_ERROR) {
  cf_error_append_history($function_history, __FUNCTION__);
  if ($argument_name == '') {
    cf_error_empty_string($function_history, 'argument_name', $severity);
  }
  cf_error_invalid_variable($function_history, $argument_name, "Not a valid float, double, or real.", array(), $severity);
}

/**
 * Reports if an argument is not a callable function.
 *
 * Why:
 *   See reason from cf_error_invalid_variable() function.
 *
 * @param array $function_history
 *   An array of function names, ie: array('0' => 'my_function_name').
 * @param string $argument_name
 *   The variable name of the argument in question.
 * @param int $severity
 *   (optional) This is passed directly to watchdog and represents the severity
 *   of the report.
 */
function cf_error_invalid_callable($function_history, $argument_name, $severity = WATCHDOG_ERROR) {
  cf_error_append_history($function_history, __FUNCTION__);
  if ($argument_name == '') {
    cf_error_empty_string($function_history, 'argument_name', $severity);
  }
  cf_error_invalid_variable($function_history, $argument_name, "Cannot be called as a function.", array(), $severity);
}

/**
 * Reports that a given argument is not an integer or a long.
 *
 * Why:
 *   See reason from cf_error_invalid_variable() function.
 *
 * @param array $function_history
 *   An array of function names, ie: array('0' => 'my_function_name').
 * @param string $argument_name
 *   The variable name of the argument in question.
 * @param int $severity
 *   (optional) This is passed directly to watchdog and represents the severity
 *   of the report.
 */
function cf_error_invalid_integer($function_history, $argument_name, $severity = WATCHDOG_ERROR) {
  cf_error_append_history($function_history, __FUNCTION__);
  if ($argument_name == '') {
    cf_error_empty_string($function_history, 'argument_name', $severity);
  }
  cf_error_invalid_variable($function_history, $argument_name, "Not a valid integer or long.", array(), $severity);
}

/**
 * Reports that a given argument is supposed to be a resource but is not.
 *
 * Why:
 *   See reason from cf_error_invalid_variable() function.
 *
 * @param array $function_history
 *   An array of function names, ie: array('0' => 'my_function_name').
 * @param string $argument_name
 *   The variable name of the argument in question.
 * @param int $severity
 *   (optional) This is passed directly to watchdog and represents the severity
 *   of the report.
 */
function cf_error_invalid_resource($function_history, $argument_name, $severity = WATCHDOG_ERROR) {
  cf_error_append_history($function_history, __FUNCTION__);
  if ($argument_name == '') {
    cf_error_empty_string($function_history, 'argument_name', $severity);
  }
  cf_error_invalid_variable($function_history, $argument_name, "Not a valid resource.", array(), $severity);
}

/**
 * Reports that a given argument is supposed to be a scalar but is not.
 *
 * Why:
 *   See reason from cf_error_invalid_variable() function.
 *
 * @param array $function_history
 *   An array of function names, ie: array('0' => 'my_function_name').
 * @param string $argument_name
 *   The variable name of the argument in question.
 * @param int $severity
 *   (optional) This is passed directly to watchdog and represents the severity
 *   of the report.
 */
function cf_error_invalid_scalar($function_history, $argument_name, $severity = WATCHDOG_ERROR) {
  cf_error_append_history($function_history, __FUNCTION__);
  if ($argument_name == '') {
    cf_error_empty_string($function_history, 'argument_name', $severity);
  }
  cf_error_invalid_variable($function_history, $argument_name, "Not a valid scalar.", array(), $severity);
}

/**
 * Reports that a given argument is supposed to be a null but is not.
 *
 * Why:
 *   See reason from cf_error_invalid_variable() function.
 *
 * @param array $function_history
 *   An array of function names, ie: array('0' => 'my_function_name').
 * @param string $argument_name
 *   The variable name of the argument in question.
 * @param int $severity
 *   (optional) This is passed directly to watchdog and represents the severity
 *   of the report.
 */
function cf_error_invalid_null($function_history, $argument_name, $severity = WATCHDOG_ERROR) {
  cf_error_append_history($function_history, __FUNCTION__);
  if ($argument_name == '') {
    cf_error_empty_string($function_history, 'argument_name', $severity);
  }
  cf_error_invalid_variable($function_history, $argument_name, "Not NULL.", array(), $severity);
}

Functions

Namesort descending Description
cf_error_append_history Appends the function name to the function_history.
cf_error_cf_permission_alter Implements hook_cf_permission_alter().
cf_error_empty_string Reports that a given argument is supposed to be non-empty string but is not.
cf_error_invalid_array Reports that a given argument is supposed to be an array but is not.
cf_error_invalid_bool Reports that a given argument is supposed to be an boolean but is not.
cf_error_invalid_callable Reports if an argument is not a callable function.
cf_error_invalid_float Reports if a variable is not a float, double, or real.
cf_error_invalid_integer Reports that a given argument is not an integer or a long.
cf_error_invalid_null Reports that a given argument is supposed to be a null but is not.
cf_error_invalid_object Reports that a given argument is supposed to be an object but is not.
cf_error_invalid_resource Reports that a given argument is supposed to be a resource but is not.
cf_error_invalid_scalar Reports that a given argument is supposed to be a scalar but is not.
cf_error_invalid_variable Reports variables as invalid to the watchdog system.
cf_error_missing_array_key Reports that a given array is missing a specific array key.
cf_error_missing_object_property Reports that a given object is missing a property.
cf_error_not_numeric Reports that a given argument is supposed to be numeric but is not.
cf_error_not_string Reports that a given argument is supposed to be a string but is not.
cf_error_on_query_execution Reports query execution failures to the watchdog system.
cf_error_print_message Prints error messages to the screen.