Documentation

AssetBuilder extends AutoService

in package

• Civi
• Core

Class AssetBuilder

Tags

service

asset_builder

The AssetBuilder is used to manage semi-dynamic assets. In normal production use, these assets are built on first reference and then stored in a public-facing cache folder. (In debug mode, these assets are constructed during every request.)

There are generally two aspects to usage -- creating a URL for the asset, and defining the content of the asset.

For example, suppose we wanted to define a static file named "api-fields.json" which lists all the fields of all the API entities.

// Build a URL to `api-fields.json`.
$url = \Civi::service('asset_builder')->getUrl('api-fields.json');

// Define the content of `api-fields.json`.
function hook_civicrm_buildAsset($asset, $params, &$mimeType, &$content) {
  if ($asset !== 'api-fields.json') return;

  $entities = civicrm_api3('Entity', 'get', array());
  $fields = array();
  foreach ($entities['values'] as $entity) {
    $fields[$entity] = civicrm_api3($entity, 'getfields');
  }

  $mimeType = 'application/json';
  $content = json_encode($fields);
}

Assets can be parameterized. Each combination of ($asset,$params) will be cached separately. For example, we might want a copy of 'api-fields.json' which only includes a handful of chosen entities. Simply pass the chosen entities into getUrl(), then update the definition to use $params['entities'], as in:

// Build a URL to `api-fields.json`.
$url = \Civi::service('asset_builder')->getUrl('api-fields.json', array(
  'entities' => array('Contact', 'Phone', 'Email', 'Address'),
));

// Define the content of `api-fields.json`.
function hook_civicrm_buildAsset($asset, $params, &$mimeType, &$content) {
  if ($asset !== 'api-fields.json') return;

  $fields = array();
  foreach ($params['entities'] as $entity) {
    $fields[$entity] = civicrm_api3($entity, 'getfields');
  }

  $mimeType = 'application/json';
  $content = json_encode($fields);
}

Note: These assets are designed to hold non-sensitive data, such as aggregated JS or common metadata. There probably are ways to secure it (e.g. alternative digest() calculations), but the current implementation is KISS.

Table of Contents

Properties

$cacheEnabled  : mixed

Methods

__construct()  : mixed

AssetBuilder constructor.

build()  : string

Build the cached copy of an $asset.

clear()  : mixed

Clear out any cache files.

getCacheModes()  : array<string|int, mixed>

getPath()  : string

getUrl()  : string

isCacheEnabled()  : bool

isValidName()  : bool

Determine if $name is a well-formed asset name.

pageRender()  : array<string|int, mixed>

(INTERNAL ONLY)

pageRun()  : mixed

(INTERNAL ONLY)

render()  : array<string|int, mixed>

Generate the content for a dynamic asset.

setCacheEnabled()  : AssetBuilder

digest()  : string

Create a unique identifier for the $params.

getCachePath()  : string

Determine the local path of a cache file.

getCacheUrl()  : string

Determine the URL of a cache file.