Libraries CDN API is an API module to query CDN services to automatically provides libraries on your site.

It is bundled with two CDN plugins: CDNJS and jsDelivr.
Check the very simple API to understand how to query a CDN and how to create your own CDN plugins too.

It also provides an integration with Libraries API. If your module depends on a library that needs to be downloaded and installed in sites/all/libraries and if this library is also hosted on a CDN, this module allows you to use the CDN version of the library very easily, without the need to download the library.

Basically, the module alter the libraries array and adds variants to it, these variants gets their files from the cloud, the module is also able to download a local copy of the library.

API

The module provides its own API, here it is.

  // List available CDN plugins
  $plugins = \Drupal\libraries_cdn\LibrariesCDN::getAvailableCDN();

  // Set the cdn you want to use
  \Drupal\libraries_cdn\LibrariesCDN::setPlugin('cdnjs');
  
  // Set the cdn and the library to use
  \Drupal\libraries_cdn\LibrariesCDN::setPlugin('cdnjs', 'ol3');

  // Set the cdn, the library and the configuration.
  \Drupal\libraries_cdn\LibrariesCDN::setPlugin('cdnjs', 'ol3', array('request' => array('timeout' => 5)));
  
  // Get the cdn plugin
  \Drupal\libraries_cdn\LibrariesCDN::getPlugin();

  // Set the library you want to get data from
  \Drupal\libraries_cdn\LibrariesCDN::setLibrary('openlayers');
  
  // Check if the library is available
  \Drupal\libraries_cdn\LibrariesCDN::isAvailable();
  
  // Get information about the library
  \Drupal\libraries_cdn\LibrariesCDN::getInformation();

  // Get versions available
  \Drupal\libraries_cdn\LibrariesCDN::getVersions();
  
  // Get files available
  \Drupal\libraries_cdn\LibrariesCDN::getFiles();
  
  // Get latest version available
  \Drupal\libraries_cdn\LibrariesCDN::getLatestVersion();

  // Get array of CDN plugins ID where the library is available
  \Drupal\libraries_cdn\LibrariesCDN::find($library);

  // Perform a search on each CDN Plugins and return an array of results
  \Drupal\libraries_cdn\LibrariesCDN::search($library);

Integration with Libraries API

This module provides also a kind of autodiscovery for Libraries API through the hook_libraries_info_alter().
In order to have it working, add a new key to the library definition in hook_libraries_info().

Here's an example:

/*
 * Implementation of hook_libraries_info().
 */
function mymodule_libraries_info() {
  return array(
    'mylibrary' => array(
      'name' => 'MyLibrary library',
      'library path' => drupal_get_path('module', 'mymodule'),
      'version callback' => , // Set a callback here to get the version in use.
      'version arguments' => array(),
      'variants' => array(),
      'cdn' => array(
        'aliases' => array('mlib', 'mylib'),
        'limit' => 3,
        'options' => array(
          'weight' => -2,
          'group' => 'MyLib',
        ),
        'download' => array(
          'versions' => array('3.8.1'),
          'plugins' => array(
            'cdnjs' => array('latest'),
            '*' => array('latest')
          )
        ),
        'request' => array(
          'timeout' => 5,
        ),
      )
    )
  );
}

The explanation of this new key:

  • plugins: array, the list of cdn plugins to search the library from. Will use all if not set.
  • aliases: array, if the library has different names.
  • limit: integer, set this to limit the number of results. If set to 3, it will return the 3 latest versions available.
  • options: array, this array will be applied to each file definition, see drupal_add_TYPE() (js or css) to see which are the keys.
  • download: array, options to download a local copy of the library
    • versions: array, version to download on any CDN when available.
    • plugins: array, keys are CDN plugin ids and the special keyword '*' can be use to specify all CDN plugins. Values are the versions to download when available. The special keyword: 'latest' can be used to download the latest version available.
  • request array, this array will be the configuration that will be passed to the request function. See drupal_http_request() for a list of key values.

You can include a library variant select in your module, here's an example:

  $library = libraries_detect('openlayers3');
  $options_variants = array();
  foreach ($library['variants'] as $version => $variant) {
    list($optgroup) = explode(':', $version, 2);
    if (empty($optgroup)) {
      $optgroup = t('Other');
    }
    $optgroup = drupal_strtoupper($optgroup);
    $options_variants[$optgroup][$version] = (isset($variant['name'])) ? $variant['name'] : $version;
  }

  $form['library'] = array(
    '#type' => 'select',
    '#title' => 'Select version of the library you want to use',
    '#options' => $options_variants,
  );

Integration using #attached

Use the #attached key of a render array to attach any CDN libraries, just like any other regular libraries.

$form['#attached'] = array(
 'libraries_cdn_load' => array(
   array('cdnjs', 'ol3', '3.8.2'),
 ),
);

The parameters are:

  • String, required: The CDN to get the library from. (use * to query all CDN available and use the first who has it)
  • String, required: The library name
  • String, optional: The version. Will get the latest version if omitted.

Extend the module

You can add more CDN by creating a simple Drupal module.

Your module's info file must contains:

dependencies[] = libraries_cdn
dependencies[] = registry_autoload
registry_autoload[] = PSR-4

Create directory structure that follows this one in your module:

src/Plugin/LibrariesCDN

Pay attention to the case, it's important.

Then, create your file containing your class in that directory.
Have a look at the files provided in the original module to inspire yours.

Requirements

Contribute

You can submit issues and patches on the issue queue or on Github where a clone of this repository is maintained. Github is the preferred method to contribute. Clone the repository, submit a pull request, and it's done.

Tests

PHPunit tests are runned everytime a commit is made. Travis CI is running them automatically and report the result in Github. Code coverage report is also generated and uploaded on coveralls.io.

TODO

  • More tests and code coverage to 100%.
  • Do not use drupal_http_request().
  • More CDNs.
  • More documentation.
  • Better Libraries API integration.
  • Permit the download and installation of libraries.

Project Information

Downloads