5 use Civi\Core\Exception\UnknownAssetException
;
11 * The AssetBuilder is used to manage semi-dynamic assets.
12 * In normal production use, these assets are built on first
13 * reference and then stored in a public-facing cache folder.
14 * (In debug mode, these assets are constructed during every request.)
16 * There are generally two aspects to usage -- creating a URL
17 * for the asset, and defining the content of the asset.
19 * For example, suppose we wanted to define a static file
20 * named "api-fields.json" which lists all the fields of
21 * all the API entities.
24 * // Build a URL to `api-fields.json`.
25 * $url = \Civi::service('asset_builder')->getUrl('api-fields.json');
27 * // Define the content of `api-fields.json`.
28 * function hook_civicrm_buildAsset($asset, $params, &$mimeType, &$content) {
29 * if ($asset !== 'api-fields.json') return;
31 * $entities = civicrm_api3('Entity', 'get', array());
33 * foreach ($entities['values'] as $entity) {
34 * $fields[$entity] = civicrm_api3($entity, 'getfields');
37 * $mimeType = 'application/json';
38 * $content = json_encode($fields);
42 * Assets can be parameterized. Each combination of ($asset,$params)
43 * will be cached separately. For example, we might want a copy of
44 * 'api-fields.json' which only includes a handful of chosen entities.
45 * Simply pass the chosen entities into `getUrl()`, then update
46 * the definition to use `$params['entities']`, as in:
49 * // Build a URL to `api-fields.json`.
50 * $url = \Civi::service('asset_builder')->getUrl('api-fields.json', array(
51 * 'entities' => array('Contact', 'Phone', 'Email', 'Address'),
54 * // Define the content of `api-fields.json`.
55 * function hook_civicrm_buildAsset($asset, $params, &$mimeType, &$content) {
56 * if ($asset !== 'api-fields.json') return;
59 * foreach ($params['entities'] as $entity) {
60 * $fields[$entity] = civicrm_api3($entity, 'getfields');
63 * $mimeType = 'application/json';
64 * $content = json_encode($fields);
68 * Note: These assets are designed to hold non-sensitive data, such as
69 * aggregated JS or common metadata. There probably are ways to
70 * secure it (e.g. alternative digest() calculations), but the
71 * current implementation is KISS.
77 * Array(string $value => string $label).
79 public static function getCacheModes() {
87 protected $cacheEnabled;
90 * AssetBuilder constructor.
91 * @param $cacheEnabled
93 public function __construct($cacheEnabled = NULL) {
94 if ($cacheEnabled === NULL) {
95 $cacheEnabled = \Civi
::settings()->get('assetCache');
96 if ($cacheEnabled === 'auto') {
97 $cacheEnabled = !\CRM_Core_Config
::singleton()->debug
;
99 $cacheEnabled = (bool) $cacheEnabled;
101 $this->cacheEnabled
= $cacheEnabled;
105 * Determine if $name is a well-formed asset name.
107 * @param string $name
110 public function isValidName($name) {
111 return preg_match(';^[a-zA-Z0-9\.\-_/]+$;', $name)
112 && strpos($name, '..') === FALSE
113 && strpos($name, '.') !== FALSE;
117 * @param string $name
118 * Ex: 'angular.json'.
119 * @param array $params
122 * Ex: 'http://example.org/files/civicrm/dyn/angular.abcd1234abcd1234.json'.
124 public function getUrl($name, $params = array()) {
125 if (!$this->isValidName($name)) {
126 throw new \
RuntimeException("Invalid dynamic asset name");
129 if ($this->isCacheEnabled()) {
130 $fileName = $this->build($name, $params);
131 return $this->getCacheUrl($fileName);
134 return \CRM_Utils_System
::url('civicrm/asset/builder', array(
136 'ap' => $this->encode($params),
137 'ad' => $this->digest($name, $params),
138 ), TRUE, NULL, FALSE);
143 * @param string $name
144 * Ex: 'angular.json'.
145 * @param array $params
148 * Ex: '/var/www/files/civicrm/dyn/angular.abcd1234abcd1234.json'.
150 public function getPath($name, $params = array()) {
151 if (!$this->isValidName($name)) {
152 throw new \
RuntimeException("Invalid dynamic asset name");
155 $fileName = $this->build($name, $params);
156 return $this->getCachePath($fileName);
160 * Build the cached copy of an $asset.
162 * @param string $name
163 * Ex: 'angular.json'.
164 * @param array $params
166 * Build the asset anew, even if it already exists.
168 * File name (relative to cache folder).
169 * Ex: 'angular.abcd1234abcd1234.json'.
170 * @throws UnknownAssetException
172 public function build($name, $params, $force = FALSE) {
173 if (!$this->isValidName($name)) {
174 throw new UnknownAssetException("Asset name is malformed");
176 $nameParts = explode('.', $name);
177 array_splice($nameParts, -1, 0, array($this->digest($name, $params)));
178 $fileName = implode('.', $nameParts);
179 if ($force ||
!file_exists($this->getCachePath($fileName))) {
180 // No file locking, but concurrent writers should produce
181 // the same data, so we'll just plow ahead.
183 if (!file_exists($this->getCachePath())) {
184 mkdir($this->getCachePath());
187 $rendered = $this->render($name, $params);
188 file_put_contents($this->getCachePath($fileName), $rendered['content']);
195 * Generate the content for a dynamic asset.
197 * @param string $name
198 * @param array $params
201 * - statusCode: int, ex: 200.
202 * - mimeType: string, ex: 'text/html'.
203 * - content: string, ex: '<body>Hello world</body>'.
204 * @throws \CRM_Core_Exception
206 public function render($name, $params = array()) {
207 if (!$this->isValidName($name)) {
208 throw new UnknownAssetException("Asset name is malformed");
210 \CRM_Utils_Hook
::buildAsset($name, $params, $mimeType, $content);
211 if ($mimeType === NULL && $content === NULL) {
212 throw new UnknownAssetException("Unrecognized asset name: $name");
214 // Beg your pardon, sir. Please may I have an HTTP response class instead?
217 'mimeType' => $mimeType,
218 'content' => $content,
223 * Clear out any cache files.
225 public function clear() {
226 \CRM_Utils_File
::cleanDir($this->getCachePath());
230 * Determine the local path of a cache file.
232 * @param string|NULL $fileName
233 * Ex: 'angular.abcd1234abcd1234.json'.
236 * Ex: '/var/www/files/civicrm/dyn/angular.abcd1234abcd1234.json'.
238 protected function getCachePath($fileName = NULL) {
239 // imageUploadDir has the correct functional properties but a wonky name.
240 $suffix = ($fileName === NULL) ?
'' : (DIRECTORY_SEPARATOR
. $fileName);
242 \CRM_Utils_File
::addTrailingSlash(\CRM_Core_Config
::singleton()->imageUploadDir
)
247 * Determine the URL of a cache file.
249 * @param string|NULL $fileName
250 * Ex: 'angular.abcd1234abcd1234.json'.
253 * Ex: 'http://example.org/files/civicrm/dyn/angular.abcd1234abcd1234.json'.
255 protected function getCacheUrl($fileName = NULL) {
256 // imageUploadURL has the correct functional properties but a wonky name.
257 $suffix = ($fileName === NULL) ?
'' : ('/' . $fileName);
259 \CRM_Utils_File
::addTrailingSlash(\CRM_Core_Config
::singleton()->imageUploadURL
, '/')
264 * Create a unique identifier for the $params.
266 * This identifier is designed to avoid accidental cache collisions.
268 * @param string $name
269 * @param array $params
272 protected function digest($name, $params) {
273 // WISHLIST: For secure digest, generate+persist privatekey & call hash_hmac.
277 \CRM_Core_Resources
::singleton()->getCacheCode() .
278 \CRM_Core_Config_Runtime
::getId() .
285 * Encode $params in a format that's optimized for shorter URLs.
287 * @param array $params
290 protected function encode($params) {
291 if (empty($params)) {
295 $str = json_encode($params);
296 if (function_exists('gzdeflate')) {
297 $str = gzdeflate($str);
299 return base64_encode($str);
306 protected function decode($str) {
307 if ($str === NULL ||
$str === FALSE ||
$str === '') {
311 $str = base64_decode($str);
312 if (function_exists('gzdeflate')) {
313 $str = gzinflate($str);
315 return json_decode($str, TRUE);
321 public function isCacheEnabled() {
322 return $this->cacheEnabled
;
326 * @param bool|null $cacheEnabled
327 * @return AssetBuilder
329 public function setCacheEnabled($cacheEnabled) {
330 $this->cacheEnabled
= $cacheEnabled;
337 * Execute a page-request for `civicrm/asset/builder`.
339 public static function pageRun() {
340 // Beg your pardon, sir. Please may I have an HTTP response class instead?
341 $asset = self
::pageRender($_GET);
342 if (function_exists('http_response_code')) {
344 http_response_code($asset['statusCode']);
347 header('X-PHP-Response-Code: ' . $asset['statusCode'], TRUE, $asset['statusCode']);
350 header('Content-Type: ' . $asset['mimeType']);
351 echo $asset['content'];
352 \CRM_Utils_System
::civiExit();
358 * Execute a page-request for `civicrm/asset/builder`.
364 * - statusCode: int, ex 200.
365 * - mimeType: string, ex 'text/html'.
366 * - content: string, ex '<body>Hello world</body>'.
368 public static function pageRender($get) {
369 // Beg your pardon, sir. Please may I have an HTTP response class instead?
371 $assets = \Civi
::service('asset_builder');
372 return $assets->render($get['an'], $assets->decode($get['ap']));
374 catch (UnknownAssetException
$e) {
377 'mimeType' => 'text/plain',
378 'content' => $e->getMessage(),