function ctools_api_version in Chaos Tool Suite (ctools) 7

Same name and namespace in other branches

1. 6 ctools.module \ctools_api_version()

Test the CTools API version.

This function can always be used to safely test if CTools has the minimum API version that your module can use. It can also try to protect you from running if the CTools API version is too new, but if you do that you need to be very quick about watching CTools API releases and release new versions of your software as soon as the new release is made, or people might end up updating CTools and having your module shut down without any recourse.

It is recommended that every hook of your module that might use CTools or might lead to a use of CTools be guarded like this:

if (!module_invoke('ctools', 'api_version', '1.0')) {
  return;
}

Note that some hooks such as _menu() or _theme() must return an array().

You can use it in your hook_requirements to report this error condition like this:

define('MODULENAME_MINIMUM_CTOOLS_API_VERSION', '1.0');
define('MODULENAME_MAXIMUM_CTOOLS_API_VERSION', '1.1');
function MODULENAME_requirements($phase) {
  $requirements = array();
  if (!module_invoke('ctools', 'api_version', MODULENAME_MINIMUM_CTOOLS_API_VERSION, MODULENAME_MAXIMUM_CTOOLS_API_VERSION)) {
    $requirements['MODULENAME_ctools'] = array(
      'title' => $t('MODULENAME required Chaos Tool Suite (CTools) API Version'),
      'value' => t('Between @a and @b', array(
        '@a' => MODULENAME_MINIMUM_CTOOLS_API_VERSION,
        '@b' => MODULENAME_MAXIMUM_CTOOLS_API_VERSION,
      )),
      'severity' => REQUIREMENT_ERROR,
    );
  }
  return $requirements;
}

Please note that the version is a string, not an floating point number. This will matter once CTools reaches version 1.10.

A CTools API changes history will be kept in API.txt. Not every new version of CTools will necessarily update the API version.

Parameters

$minimum: The minimum version of CTools necessary for your software to run with it.

$maximum: The maximum version of CTools allowed for your software to run with it.

Return value

bool TRUE if the running ctools is usable, FALSE otherwise.

1 call to ctools_api_version()

CtoolsModuleTestCase::testApiVersionCompare in tests/ctools.test

Test the ctools version compare function.

File

./ctools.module, line 85

CTools primary module file.

Code

function ctools_api_version($minimum, $maximum = NULL) {
  if (version_compare(CTOOLS_API_VERSION, $minimum, '<')) {
    return FALSE;
  }
  if (isset($maximum) && version_compare(CTOOLS_API_VERSION, $maximum, '>')) {
    return FALSE;
  }
  return TRUE;
}