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() {
90 protected $cacheEnabled;
93 * AssetBuilder constructor.
94 * @param $cacheEnabled
96 public function __construct($cacheEnabled = NULL) {
97 if ($cacheEnabled === NULL) {
98 $cacheEnabled = \Civi
::settings()->get('assetCache');
99 if ($cacheEnabled === 'auto') {
100 $cacheEnabled = !\CRM_Core_Config
::singleton()->debug
;
102 $cacheEnabled = (bool) $cacheEnabled;
104 $this->cacheEnabled
= $cacheEnabled;
108 * Determine if $name is a well-formed asset name.
110 * @param string $name
113 public function isValidName($name) {
114 return preg_match(';^[a-zA-Z0-9\.\-_/]+$;', $name)
115 && strpos($name, '..') === FALSE
116 && strpos($name, '.') !== FALSE;
120 * @param string $name
121 * Ex: 'angular.json'.
122 * @param array $params
125 * Ex: 'http://example.org/files/civicrm/dyn/angular.abcd1234abcd1234.json'.
127 public function getUrl($name, $params = []) {
128 \CRM_Utils_Hook
::getAssetUrl($name, $params);
130 if (!$this->isValidName($name)) {
131 throw new \
RuntimeException("Invalid dynamic asset name");
134 if ($this->isCacheEnabled()) {
135 $fileName = $this->build($name, $params);
136 return $this->getCacheUrl($fileName);
139 return \CRM_Utils_System
::url('civicrm/asset/builder', [
141 'ap' => $this->encode($params),
142 'ad' => $this->digest($name, $params),
143 ], TRUE, NULL, FALSE);
148 * @param string $name
149 * Ex: 'angular.json'.
150 * @param array $params
153 * Ex: '/var/www/files/civicrm/dyn/angular.abcd1234abcd1234.json'.
155 public function getPath($name, $params = []) {
156 if (!$this->isValidName($name)) {
157 throw new \
RuntimeException("Invalid dynamic asset name");
160 $fileName = $this->build($name, $params);
161 return $this->getCachePath($fileName);
165 * Build the cached copy of an $asset.
167 * @param string $name
168 * Ex: 'angular.json'.
169 * @param array $params
171 * Build the asset anew, even if it already exists.
173 * File name (relative to cache folder).
174 * Ex: 'angular.abcd1234abcd1234.json'.
175 * @throws UnknownAssetException
177 public function build($name, $params, $force = FALSE) {
178 if (!$this->isValidName($name)) {
179 throw new UnknownAssetException("Asset name is malformed");
181 $nameParts = explode('.', $name);
182 array_splice($nameParts, -1, 0, [$this->digest($name, $params)]);
183 $fileName = implode('.', $nameParts);
184 if ($force ||
!file_exists($this->getCachePath($fileName))) {
185 // No file locking, but concurrent writers should produce
186 // the same data, so we'll just plow ahead.
188 if (!file_exists($this->getCachePath())) {
189 mkdir($this->getCachePath());
192 $rendered = $this->render($name, $params);
193 file_put_contents($this->getCachePath($fileName), $rendered['content']);
200 * Generate the content for a dynamic asset.
202 * @param string $name
203 * @param array $params
206 * - statusCode: int, ex: 200.
207 * - mimeType: string, ex: 'text/html'.
208 * - content: string, ex: '<body>Hello world</body>'.
209 * @throws \CRM_Core_Exception
211 public function render($name, $params = []) {
212 if (!$this->isValidName($name)) {
213 throw new UnknownAssetException("Asset name is malformed");
215 \CRM_Utils_Hook
::buildAsset($name, $params, $mimeType, $content);
216 if ($mimeType === NULL && $content === NULL) {
217 throw new UnknownAssetException("Unrecognized asset name: $name");
219 // Beg your pardon, sir. Please may I have an HTTP response class instead?
222 'mimeType' => $mimeType,
223 'content' => $content,
228 * Clear out any cache files.
230 * @param bool $removeDir Should folder itself be removed too.
232 public function clear($removeDir = TRUE) {
233 \CRM_Utils_File
::cleanDir($this->getCachePath(), $removeDir);
237 * Determine the local path of a cache file.
239 * @param string|NULL $fileName
240 * Ex: 'angular.abcd1234abcd1234.json'.
243 * Ex: '/var/www/files/civicrm/dyn/angular.abcd1234abcd1234.json'.
245 protected function getCachePath($fileName = NULL) {
246 // imageUploadDir has the correct functional properties but a wonky name.
247 $suffix = ($fileName === NULL) ?
'' : (DIRECTORY_SEPARATOR
. $fileName);
248 return \CRM_Utils_File
::addTrailingSlash(\CRM_Core_Config
::singleton()->imageUploadDir
)
253 * Determine the URL of a cache file.
255 * @param string|NULL $fileName
256 * Ex: 'angular.abcd1234abcd1234.json'.
259 * Ex: 'http://example.org/files/civicrm/dyn/angular.abcd1234abcd1234.json'.
261 protected function getCacheUrl($fileName = NULL) {
262 // imageUploadURL has the correct functional properties but a wonky name.
263 $suffix = ($fileName === NULL) ?
'' : ('/' . $fileName);
264 return \CRM_Utils_File
::addTrailingSlash(\CRM_Core_Config
::singleton()->imageUploadURL
, '/')
269 * Create a unique identifier for the $params.
271 * This identifier is designed to avoid accidental cache collisions.
273 * @param string $name
274 * @param array $params
277 protected function digest($name, $params) {
278 // WISHLIST: For secure digest, generate+persist privatekey & call hash_hmac.
282 \CRM_Core_Resources
::singleton()->getCacheCode() .
283 \CRM_Core_Config_Runtime
::getId() .
290 * Encode $params in a format that's optimized for shorter URLs.
292 * @param array $params
295 protected function encode($params) {
296 if (empty($params)) {
300 $str = json_encode($params);
301 if (function_exists('gzdeflate')) {
302 $str = gzdeflate($str);
304 return base64_encode($str);
311 protected function decode($str) {
312 if ($str === NULL ||
$str === FALSE ||
$str === '') {
316 $str = base64_decode($str);
317 if (function_exists('gzdeflate')) {
318 $str = gzinflate($str);
320 return json_decode($str, TRUE);
326 public function isCacheEnabled() {
327 return $this->cacheEnabled
;
331 * @param bool|null $cacheEnabled
332 * @return AssetBuilder
334 public function setCacheEnabled($cacheEnabled) {
335 $this->cacheEnabled
= $cacheEnabled;
342 * Execute a page-request for `civicrm/asset/builder`.
344 public static function pageRun() {
345 // Beg your pardon, sir. Please may I have an HTTP response class instead?
346 $asset = self
::pageRender($_GET);
347 \CRM_Utils_System
::sendResponse(new \GuzzleHttp\Psr7\
Response($asset['statusCode'], ['Content-Type' => $asset['mimeType']], $asset['content']));
353 * Execute a page-request for `civicrm/asset/builder`.
359 * - statusCode: int, ex 200.
360 * - mimeType: string, ex 'text/html'.
361 * - content: string, ex '<body>Hello world</body>'.
363 public static function pageRender($get) {
364 // Beg your pardon, sir. Please may I have an HTTP response class instead?
366 $assets = \Civi
::service('asset_builder');
367 return $assets->render($get['an'], $assets->decode($get['ap']));
369 catch (UnknownAssetException
$e) {
372 'mimeType' => 'text/plain',
373 'content' => $e->getMessage(),