getAsArray();
}
/**
* @defgroup validation Input validation
* @{
* Functions to validate user input.
*/
/**
* Verifies the syntax of the given email address.
*
* @param string $mail
* A string containing an email address.
*
* @return bool
* TRUE if the address is in a valid format.
*
* @deprecated in Drupal 8.0.x-dev, will be removed before Drupal 9.0.0.
* Use \Drupal::service('email.validator')->isValid().
*
* @see https://www.drupal.org/node/2912661
*/
function valid_email_address($mail) {
return \Drupal::service('email.validator')->isValid($mail);
}
/**
* @} End of "defgroup validation".
*/
/**
* @defgroup sanitization Sanitization functions
* @{
* Functions to sanitize values.
*
* See https://www.drupal.org/writing-secure-code for information
* on writing secure code.
*/
/**
* Strips dangerous protocols from a URI and encodes it for output to HTML.
*
* @param $uri
* A plain-text URI that might contain dangerous protocols.
*
* @return string
* A URI stripped of dangerous protocols and encoded for output to an HTML
* attribute value. Because it is already encoded, it should not be set as a
* value within a $attributes array passed to Drupal\Core\Template\Attribute,
* because Drupal\Core\Template\Attribute expects those values to be
* plain-text strings. To pass a filtered URI to
* Drupal\Core\Template\Attribute, call
* \Drupal\Component\Utility\UrlHelper::stripDangerousProtocols() instead.
*
* @deprecated in Drupal 8.0.x-dev, will be removed before Drupal 9.0.0.
* Use UrlHelper::stripDangerousProtocols() or UrlHelper::filterBadProtocol()
* instead. UrlHelper::stripDangerousProtocols() can be used in conjunction
* with \Drupal\Component\Utility\SafeMarkup::format() and an @variable
* placeholder which will perform the necessary escaping.
* UrlHelper::filterBadProtocol() is functionality equivalent to check_url()
* apart from the fact it is protected from double escaping bugs. Note that
* this method no longer marks its output as safe.
*
* @see \Drupal\Component\Utility\UrlHelper::stripDangerousProtocols()
* @see \Drupal\Component\Utility\UrlHelper::filterBadProtocol()
* @see https://www.drupal.org/node/2560027
*/
function check_url($uri) {
return Html::escape(UrlHelper::stripDangerousProtocols($uri));
}
/**
* @} End of "defgroup sanitization".
*/
/**
* @defgroup format Formatting
* @{
* Functions to format numbers, strings, dates, etc.
*/
/**
* Generates a string representation for the given byte count.
*
* @param $size
* A size in bytes.
* @param $langcode
* Optional language code to translate to a language other than what is used
* to display the page.
*
* @return \Drupal\Core\StringTranslation\TranslatableMarkup
* A translated string representation of the size.
*/
function format_size($size, $langcode = NULL) {
if ($size < Bytes::KILOBYTE) {
return \Drupal::translation()->formatPlural($size, '1 byte', '@count bytes', [], ['langcode' => $langcode]);
}
else {
// Convert bytes to kilobytes.
$size = $size / Bytes::KILOBYTE;
$units = ['KB', 'MB', 'GB', 'TB', 'PB', 'EB', 'ZB', 'YB'];
foreach ($units as $unit) {
if (round($size, 2) >= Bytes::KILOBYTE) {
$size = $size / Bytes::KILOBYTE;
}
else {
break;
}
}
$args = ['@size' => round($size, 2)];
$options = ['langcode' => $langcode];
switch ($unit) {
case 'KB':
return new TranslatableMarkup('@size KB', $args, $options);
case 'MB':
return new TranslatableMarkup('@size MB', $args, $options);
case 'GB':
return new TranslatableMarkup('@size GB', $args, $options);
case 'TB':
return new TranslatableMarkup('@size TB', $args, $options);
case 'PB':
return new TranslatableMarkup('@size PB', $args, $options);
case 'EB':
return new TranslatableMarkup('@size EB', $args, $options);
case 'ZB':
return new TranslatableMarkup('@size ZB', $args, $options);
case 'YB':
return new TranslatableMarkup('@size YB', $args, $options);
}
}
}
/**
* Formats a date, using a date type or a custom date format string.
*
* @param $timestamp
* A UNIX timestamp to format.
* @param $type
* (optional) The format to use, one of:
* - One of the built-in formats: 'short', 'medium',
* 'long', 'html_datetime', 'html_date', 'html_time',
* 'html_yearless_date', 'html_week', 'html_month', 'html_year'.
* - The name of a date type defined by a date format config entity.
* - The machine name of an administrator-defined date format.
* - 'custom', to use $format.
* Defaults to 'medium'.
* @param $format
* (optional) If $type is 'custom', a PHP date format string suitable for
* input to date(). Use a backslash to escape ordinary text, so it does not
* get interpreted as date format characters.
* @param $timezone
* (optional) Time zone identifier, as described at
* http://php.net/manual/timezones.php Defaults to the time zone used to
* display the page.
* @param $langcode
* (optional) Language code to translate to. Defaults to the language used to
* display the page.
*
* @return
* A translated date string in the requested format.
*
* @deprecated in Drupal 8.0.0, will be removed before Drupal 9.0.0.
* Use \Drupal::service('date.formatter')->format().
*
* @see \Drupal\Core\Datetime\DateFormatter::format()
* @see https://www.drupal.org/node/1876852
*/
function format_date($timestamp, $type = 'medium', $format = '', $timezone = NULL, $langcode = NULL) {
return \Drupal::service('date.formatter')->format($timestamp, $type, $format, $timezone, $langcode);
}
/**
* Returns an ISO8601 formatted date based on the given date.
*
* @param $date
* A UNIX timestamp.
*
* @return string
* An ISO8601 formatted date.
*/
function date_iso8601($date) {
// The DATE_ISO8601 constant cannot be used here because it does not match
// date('c') and produces invalid RDF markup.
return date('c', $date);
}
/**
* @} End of "defgroup format".
*/
/**
* Formats an attribute string for an HTTP header.
*
* @param $attributes
* An associative array of attributes such as 'rel'.
*
* @return
* A ; separated string ready for insertion in a HTTP header. No escaping is
* performed for HTML entities, so this string is not safe to be printed.
*/
function drupal_http_header_attributes(array $attributes = []) {
foreach ($attributes as $attribute => &$data) {
if (is_array($data)) {
$data = implode(' ', $data);
}
$data = $attribute . '="' . $data . '"';
}
return $attributes ? ' ' . implode('; ', $attributes) : '';
}
/**
* Attempts to set the PHP maximum execution time.
*
* This function is a wrapper around the PHP function set_time_limit().
* When called, set_time_limit() restarts the timeout counter from zero.
* In other words, if the timeout is the default 30 seconds, and 25 seconds
* into script execution a call such as set_time_limit(20) is made, the
* script will run for a total of 45 seconds before timing out.
*
* If the current time limit is not unlimited it is possible to decrease the
* total time limit if the sum of the new time limit and the current time spent
* running the script is inferior to the original time limit. It is inherent to
* the way set_time_limit() works, it should rather be called with an
* appropriate value every time you need to allocate a certain amount of time
* to execute a task than only once at the beginning of the script.
*
* Before calling set_time_limit(), we check if this function is available
* because it could be disabled by the server administrator. We also hide all
* the errors that could occur when calling set_time_limit(), because it is
* not possible to reliably ensure that PHP or a security extension will
* not issue a warning/error if they prevent the use of this function.
*
* @param $time_limit
* An integer specifying the new time limit, in seconds. A value of 0
* indicates unlimited execution time.
*
* @ingroup php_wrappers
*/
function drupal_set_time_limit($time_limit) {
if (function_exists('set_time_limit')) {
$current = ini_get('max_execution_time');
// Do not set time limit if it is currently unlimited.
if ($current != 0) {
@set_time_limit($time_limit);
}
}
}
/**
* Returns the base URL path (i.e., directory) of the Drupal installation.
*
* base_path() adds a "/" to the beginning and end of the returned path if the
* path is not empty. At the very least, this will return "/".
*
* Examples:
* - http://example.com returns "/" because the path is empty.
* - http://example.com/drupal/folder returns "/drupal/folder/".
*/
function base_path() {
return $GLOBALS['base_path'];
}
/**
* Deletes old cached CSS files.
*
* @deprecated in Drupal 8.x, will be removed before Drupal 9.0.
* Use \Drupal\Core\Asset\AssetCollectionOptimizerInterface::deleteAll().
*
* @see https://www.drupal.org/node/2317841
*/
function drupal_clear_css_cache() {
\Drupal::service('asset.css.collection_optimizer')->deleteAll();
}
/**
* Constructs an array of the defaults that are used for JavaScript assets.
*
* @param $data
* (optional) The default data parameter for the JavaScript asset array.
*
* @see hook_js_alter()
*/
function drupal_js_defaults($data = NULL) {
return [
'type' => 'file',
'group' => JS_DEFAULT,
'weight' => 0,
'scope' => 'header',
'cache' => TRUE,
'preprocess' => TRUE,
'attributes' => [],
'version' => NULL,
'data' => $data,
'browsers' => [],
];
}
/**
* Adds JavaScript to change the state of an element based on another element.
*
* A "state" means a certain property on a DOM element, such as "visible" or
* "checked". A state can be applied to an element, depending on the state of
* another element on the page. In general, states depend on HTML attributes and
* DOM element properties, which change due to user interaction.
*
* Since states are driven by JavaScript only, it is important to understand
* that all states are applied on presentation only, none of the states force
* any server-side logic, and that they will not be applied for site visitors
* without JavaScript support. All modules implementing states have to make
* sure that the intended logic also works without JavaScript being enabled.
*
* #states is an associative array in the form of:
* @code
* array(
* STATE1 => CONDITIONS_ARRAY1,
* STATE2 => CONDITIONS_ARRAY2,
* ...
* )
* @endcode
* Each key is the name of a state to apply to the element, such as 'visible'.
* Each value is a list of conditions that denote when the state should be
* applied.
*
* Multiple different states may be specified to act on complex conditions:
* @code
* array(
* 'visible' => CONDITIONS,
* 'checked' => OTHER_CONDITIONS,
* )
* @endcode
*
* Every condition is a key/value pair, whose key is a jQuery selector that
* denotes another element on the page, and whose value is an array of
* conditions, which must bet met on that element:
* @code
* array(
* 'visible' => array(
* JQUERY_SELECTOR => REMOTE_CONDITIONS,
* JQUERY_SELECTOR => REMOTE_CONDITIONS,
* ...
* ),
* )
* @endcode
* All conditions must be met for the state to be applied.
*
* Each remote condition is a key/value pair specifying conditions on the other
* element that need to be met to apply the state to the element:
* @code
* array(
* 'visible' => array(
* ':input[name="remote_checkbox"]' => array('checked' => TRUE),
* ),
* )
* @endcode
*
* For example, to show a textfield only when a checkbox is checked:
* @code
* $form['toggle_me'] = array(
* '#type' => 'checkbox',
* '#title' => t('Tick this box to type'),
* );
* $form['settings'] = array(
* '#type' => 'textfield',
* '#states' => array(
* // Only show this field when the 'toggle_me' checkbox is enabled.
* 'visible' => array(
* ':input[name="toggle_me"]' => array('checked' => TRUE),
* ),
* ),
* );
* @endcode
*
* The following states may be applied to an element:
* - enabled
* - disabled
* - required
* - optional
* - visible
* - invisible
* - checked
* - unchecked
* - expanded
* - collapsed
*
* The following states may be used in remote conditions:
* - empty
* - filled
* - checked
* - unchecked
* - expanded
* - collapsed
* - value
*
* The following states exist for both elements and remote conditions, but are
* not fully implemented and may not change anything on the element:
* - relevant
* - irrelevant
* - valid
* - invalid
* - touched
* - untouched
* - readwrite
* - readonly
*
* When referencing select lists and radio buttons in remote conditions, a
* 'value' condition must be used:
* @code
* '#states' => array(
* // Show the settings if 'bar' has been selected for 'foo'.
* 'visible' => array(
* ':input[name="foo"]' => array('value' => 'bar'),
* ),
* ),
* @endcode
*
* @param $elements
* A renderable array element having a #states property as described above.
*
* @see form_example_states_form()
*/
function drupal_process_states(&$elements) {
$elements['#attached']['library'][] = 'core/drupal.states';
// Elements of '#type' => 'item' are not actual form input elements, but we
// still want to be able to show/hide them. Since there's no actual HTML input
// element available, setting #attributes does not make sense, but a wrapper
// is available, so setting #wrapper_attributes makes it work.
$key = ($elements['#type'] == 'item') ? '#wrapper_attributes' : '#attributes';
$elements[$key]['data-drupal-states'] = Json::encode($elements['#states']);
}
/**
* Assists in attaching the tableDrag JavaScript behavior to a themed table.
*
* Draggable tables should be used wherever an outline or list of sortable items
* needs to be arranged by an end-user. Draggable tables are very flexible and
* can manipulate the value of form elements placed within individual columns.
*
* To set up a table to use drag and drop in place of weight select-lists or in
* place of a form that contains parent relationships, the form must be themed
* into a table. The table must have an ID attribute set and it
* may be set as follows:
* @code
* $table = array(
* '#type' => 'table',
* '#header' => $header,
* '#rows' => $rows,
* '#attributes' => array(
* 'id' => 'my-module-table',
* ),
* );
* return drupal_render($table);
* @endcode
*
* In the theme function for the form, a special class must be added to each
* form element within the same column, "grouping" them together.
*
* In a situation where a single weight column is being sorted in the table, the
* classes could be added like this (in the theme function):
* @code
* $form['my_elements'][$delta]['weight']['#attributes']['class'] = array('my-elements-weight');
* @endcode
*
* Each row of the table must also have a class of "draggable" in order to
* enable the drag handles:
* @code
* $row = array(...);
* $rows[] = array(
* 'data' => $row,
* 'class' => array('draggable'),
* );
* @endcode
*
* When tree relationships are present, the two additional classes
* 'tabledrag-leaf' and 'tabledrag-root' can be used to refine the behavior:
* - Rows with the 'tabledrag-leaf' class cannot have child rows.
* - Rows with the 'tabledrag-root' class cannot be nested under a parent row.
*
* Calling drupal_attach_tabledrag() would then be written as such:
* @code
* drupal_attach_tabledrag('my-module-table', array(
* 'action' => 'order',
* 'relationship' => 'sibling',
* 'group' => 'my-elements-weight',
* );
* @endcode
*
* In a more complex case where there are several groups in one column (such as
* the block regions on the admin/structure/block page), a separate subgroup
* class must also be added to differentiate the groups.
* @code
* $form['my_elements'][$region][$delta]['weight']['#attributes']['class'] = array('my-elements-weight', 'my-elements-weight-' . $region);
* @endcode
*
* The 'group' option is still 'my-element-weight', and the additional
* 'subgroup' option will be passed in as 'my-elements-weight-' . $region. This
* also means that you'll need to call drupal_attach_tabledrag() once for every
* region added.
*
* @code
* foreach ($regions as $region) {
* drupal_attach_tabledrag('my-module-table', array(
* 'action' => 'order',
* 'relationship' => 'sibling',
* 'group' => 'my-elements-weight',
* 'subgroup' => 'my-elements-weight-' . $region,
* ));
* }
* @endcode
*
* In a situation where tree relationships are present, adding multiple
* subgroups is not necessary, because the table will contain indentations that
* provide enough information about the sibling and parent relationships. See
* MenuForm::BuildOverviewForm for an example creating a table
* containing parent relationships.
*
* @param $element
* A form element to attach the tableDrag behavior to.
* @param array $options
* These options are used to generate JavaScript settings necessary to
* configure the tableDrag behavior appropriately for this particular table.
* An associative array containing the following keys:
* - 'table_id': String containing the target table's id attribute.
* If the table does not have an id, one will need to be set,
* such as
.
* - 'action': String describing the action to be done on the form item.
* Either 'match' 'depth', or 'order':
* - 'match' is typically used for parent relationships.
* - 'order' is typically used to set weights on other form elements with
* the same group.
* - 'depth' updates the target element with the current indentation.
* - 'relationship': String describing where the "action" option
* should be performed. Either 'parent', 'sibling', 'group', or 'self':
* - 'parent' will only look for fields up the tree.
* - 'sibling' will look for fields in the same group in rows above and
* below it.
* - 'self' affects the dragged row itself.
* - 'group' affects the dragged row, plus any children below it (the entire
* dragged group).
* - 'group': A class name applied on all related form elements for this action.
* - 'subgroup': (optional) If the group has several subgroups within it, this
* string should contain the class name identifying fields in the same
* subgroup.
* - 'source': (optional) If the $action is 'match', this string should contain
* the classname identifying what field will be used as the source value
* when matching the value in $subgroup.
* - 'hidden': (optional) The column containing the field elements may be
* entirely hidden from view dynamically when the JavaScript is loaded. Set
* to FALSE if the column should not be hidden.
* - 'limit': (optional) Limit the maximum amount of parenting in this table.
*
* @see MenuForm::BuildOverviewForm()
*/
function drupal_attach_tabledrag(&$element, array $options) {
// Add default values to elements.
$options = $options + [
'subgroup' => NULL,
'source' => NULL,
'hidden' => TRUE,
'limit' => 0
];
$group = $options['group'];
$tabledrag_id = &drupal_static(__FUNCTION__);
$tabledrag_id = (!isset($tabledrag_id)) ? 0 : $tabledrag_id + 1;
// If a subgroup or source isn't set, assume it is the same as the group.
$target = isset($options['subgroup']) ? $options['subgroup'] : $group;
$source = isset($options['source']) ? $options['source'] : $target;
$element['#attached']['drupalSettings']['tableDrag'][$options['table_id']][$group][$tabledrag_id] = [
'target' => $target,
'source' => $source,
'relationship' => $options['relationship'],
'action' => $options['action'],
'hidden' => $options['hidden'],
'limit' => $options['limit'],
];
$element['#attached']['library'][] = 'core/drupal.tabledrag';
}
/**
* Deletes old cached JavaScript files and variables.
*
* @deprecated in Drupal 8.x, will be removed before Drupal 9.0.
* Use \Drupal\Core\Asset\AssetCollectionOptimizerInterface::deleteAll().
*
* @see https://www.drupal.org/node/2317841
*/
function drupal_clear_js_cache() {
\Drupal::service('asset.js.collection_optimizer')->deleteAll();
}
/**
* Pre-render callback: Renders a link into #markup.
*
* @deprecated in Drupal 8.x, will be removed before Drupal 9.0.
* Use \Drupal\Core\Render\Element\Link::preRenderLink().
*/
function drupal_pre_render_link($element) {
return Link::preRenderLink($element);
}
/**
* Pre-render callback: Collects child links into a single array.
*
* This function can be added as a pre_render callback for a renderable array,
* usually one which will be themed by links.html.twig. It iterates through all
* unrendered children of the element, collects any #links properties it finds,
* merges them into the parent element's #links array, and prevents those
* children from being rendered separately.
*
* The purpose of this is to allow links to be logically grouped into related
* categories, so that each child group can be rendered as its own list of
* links if drupal_render() is called on it, but calling drupal_render() on the
* parent element will still produce a single list containing all the remaining
* links, regardless of what group they were in.
*
* A typical example comes from node links, which are stored in a renderable
* array similar to this:
* @code
* $build['links'] = array(
* '#theme' => 'links__node',
* '#pre_render' => array('drupal_pre_render_links'),
* 'comment' => array(
* '#theme' => 'links__node__comment',
* '#links' => array(
* // An array of links associated with node comments, suitable for
* // passing in to links.html.twig.
* ),
* ),
* 'statistics' => array(
* '#theme' => 'links__node__statistics',
* '#links' => array(
* // An array of links associated with node statistics, suitable for
* // passing in to links.html.twig.
* ),
* ),
* 'translation' => array(
* '#theme' => 'links__node__translation',
* '#links' => array(
* // An array of links associated with node translation, suitable for
* // passing in to links.html.twig.
* ),
* ),
* );
* @endcode
*
* In this example, the links are grouped by functionality, which can be
* helpful to themers who want to display certain kinds of links independently.
* For example, adding this code to node.html.twig will result in the comment
* links being rendered as a single list:
* @code
* {{ content.links.comment }}
* @endcode
*
* (where a node's content has been transformed into $content before handing
* control to the node.html.twig template).
*
* The pre_render function defined here allows the above flexibility, but also
* allows the following code to be used to render all remaining links into a
* single list, regardless of their group:
* @code
* {{ content.links }}
* @endcode
*
* In the above example, this will result in the statistics and translation
* links being rendered together in a single list (but not the comment links,
* which were rendered previously on their own).
*
* Because of the way this function works, the individual properties of each
* group (for example, a group-specific #theme property such as
* 'links__node__comment' in the example above, or any other property such as
* #attributes or #pre_render that is attached to it) are only used when that
* group is rendered on its own. When the group is rendered together with other
* children, these child-specific properties are ignored, and only the overall
* properties of the parent are used.
*/
function drupal_pre_render_links($element) {
$element += ['#links' => [], '#attached' => []];
foreach (Element::children($element) as $key) {
$child = &$element[$key];
// If the child has links which have not been printed yet and the user has
// access to it, merge its links in to the parent.
if (isset($child['#links']) && empty($child['#printed']) && Element::isVisibleElement($child)) {
$element['#links'] += $child['#links'];
// Mark the child as having been printed already (so that its links
// cannot be mistakenly rendered twice).
$child['#printed'] = TRUE;
}
// Merge attachments.
if (isset($child['#attached'])) {
$element['#attached'] = BubbleableMetadata::mergeAttachments($element['#attached'], $child['#attached']);
}
}
return $element;
}
/**
* Renders final HTML given a structured array tree.
*
* @deprecated as of Drupal 8.0.x, will be removed before Drupal 9.0.0. Use the
* 'renderer' service instead.
*
* @see \Drupal\Core\Render\RendererInterface::renderRoot()
* @see https://www.drupal.org/node/2912696
*/
function drupal_render_root(&$elements) {
return \Drupal::service('renderer')->renderRoot($elements);
}
/**
* Renders HTML given a structured array tree.
*
* @deprecated as of Drupal 8.0.x, will be removed before Drupal 9.0.0. Use the
* 'renderer' service instead.
*
* @see \Drupal\Core\Render\RendererInterface::render()
* @see https://www.drupal.org/node/2912696
*/
function drupal_render(&$elements, $is_recursive_call = FALSE) {
return \Drupal::service('renderer')->render($elements, $is_recursive_call);
}
/**
* Renders children of an element and concatenates them.
*
* @param array $element
* The structured array whose children shall be rendered.
* @param array $children_keys
* (optional) If the keys of the element's children are already known, they
* can be passed in to save another run of
* \Drupal\Core\Render\Element::children().
*
* @return string|\Drupal\Component\Render\MarkupInterface
* The rendered HTML of all children of the element.
*
* @deprecated in Drupal 8.0.x and will be removed before 9.0.0. Avoid early
* rendering when possible or loop through the elements and render them as
* they are available.
*
* @see drupal_render()
* @see https://www.drupal.org/node/2912757
*/
function drupal_render_children(&$element, $children_keys = NULL) {
if ($children_keys === NULL) {
$children_keys = Element::children($element);
}
$output = '';
foreach ($children_keys as $key) {
if (!empty($element[$key])) {
$output .= \Drupal::service('renderer')->render($element[$key]);
}
}
return Markup::create($output);
}
/**
* Renders an element.
*
* This function renders an element. The top level element is shown with show()
* before rendering, so it will always be rendered even if hide() had been
* previously used on it.
*
* @param $element
* The element to be rendered.
*
* @return
* The rendered element.
*
* @see \Drupal\Core\Render\RendererInterface
* @see show()
* @see hide()
*/
function render(&$element) {
if (!$element && $element !== 0) {
return NULL;
}
if (is_array($element)) {
// Early return if this element was pre-rendered (no need to re-render).
if (isset($element['#printed']) && $element['#printed'] == TRUE && isset($element['#markup']) && strlen($element['#markup']) > 0) {
return $element['#markup'];
}
show($element);
return \Drupal::service('renderer')->render($element);
}
else {
// Safe-guard for inappropriate use of render() on flat variables: return
// the variable as-is.
return $element;
}
}
/**
* Hides an element from later rendering.
*
* The first time render() or drupal_render() is called on an element tree,
* as each element in the tree is rendered, it is marked with a #printed flag
* and the rendered children of the element are cached. Subsequent calls to
* render() or drupal_render() will not traverse the child tree of this element
* again: they will just use the cached children. So if you want to hide an
* element, be sure to call hide() on the element before its parent tree is
* rendered for the first time, as it will have no effect on subsequent
* renderings of the parent tree.
*
* @param $element
* The element to be hidden.
*
* @return
* The element.
*
* @see render()
* @see show()
*/
function hide(&$element) {
$element['#printed'] = TRUE;
return $element;
}
/**
* Shows a hidden element for later rendering.
*
* You can also use render($element), which shows the element while rendering
* it.
*
* The first time render() or drupal_render() is called on an element tree,
* as each element in the tree is rendered, it is marked with a #printed flag
* and the rendered children of the element are cached. Subsequent calls to
* render() or drupal_render() will not traverse the child tree of this element
* again: they will just use the cached children. So if you want to show an
* element, be sure to call show() on the element before its parent tree is
* rendered for the first time, as it will have no effect on subsequent
* renderings of the parent tree.
*
* @param $element
* The element to be shown.
*
* @return
* The element.
*
* @see render()
* @see hide()
*/
function show(&$element) {
$element['#printed'] = FALSE;
return $element;
}
/**
* Retrieves the default properties for the defined element type.
*
* @param $type
* An element type as defined by an element plugin.
*
* @deprecated in Drupal 8.0.0, will be removed before Drupal 9.0.0.
* Use \Drupal::service('element_info')->getInfo() instead.
*
* @see https://www.drupal.org/node/2235461
*/
function element_info($type) {
return \Drupal::service('element_info')->getInfo($type);
}
/**
* Retrieves a single property for the defined element type.
*
* @param $type
* An element type as defined by an element plugin.
* @param $property_name
* The property within the element type that should be returned.
* @param $default
* (Optional) The value to return if the element type does not specify a
* value for the property. Defaults to NULL.
*
* @deprecated in Drupal 8.0.0, will be removed before Drupal 9.0.0.
* Use \Drupal::service('element_info')->getInfoProperty() instead.
*
* @see https://www.drupal.org/node/2235461
*/
function element_info_property($type, $property_name, $default = NULL) {
return \Drupal::service('element_info')->getInfoProperty($type, $property_name, $default);
}
/**
* Flushes all persistent caches, resets all variables, and rebuilds all data structures.
*
* At times, it is necessary to re-initialize the entire system to account for
* changed or new code. This function:
* - Clears all persistent caches:
* - The bootstrap cache bin containing base system, module system, and theme
* system information.
* - The common 'default' cache bin containing arbitrary caches.
* - The page cache.
* - The URL alias path cache.
* - Resets all static variables that have been defined via drupal_static().
* - Clears asset (JS/CSS) file caches.
* - Updates the system with latest information about extensions (modules and
* themes).
* - Updates the bootstrap flag for modules implementing bootstrap_hooks().
* - Rebuilds the full database schema information (invoking hook_schema()).
* - Rebuilds data structures of all modules (invoking hook_rebuild()). In
* core this means
* - blocks, node types, date formats and actions are synchronized with the
* database
* - The 'active' status of fields is refreshed.
* - Rebuilds the menu router.
*
* This means the entire system is reset so all caches and static variables are
* effectively empty. After that is guaranteed, information about the currently
* active code is updated, and rebuild operations are successively called in
* order to synchronize the active system according to the current information
* defined in code.
*
* All modules need to ensure that all of their caches are flushed when
* hook_cache_flush() is invoked; any previously known information must no
* longer exist. All following hook_rebuild() operations must be based on fresh
* and current system data. All modules must be able to rely on this contract.
*
* @see \Drupal\Core\Cache\CacheHelper::getBins()
* @see hook_cache_flush()
* @see hook_rebuild()
*
* This function also resets the theme, which means it is not initialized
* anymore and all previously added JavaScript and CSS is gone. Normally, this
* function is called as an end-of-POST-request operation that is followed by a
* redirect, so this effect is not visible. Since the full reset is the whole
* point of this function, callers need to take care for backing up all needed
* variables and properly restoring or re-initializing them on their own. For
* convenience, this function automatically re-initializes the maintenance theme
* if it was initialized before.
*
* @todo Try to clear page/JS/CSS caches last, so cached pages can still be
* served during this possibly long-running operation. (Conflict on bootstrap
* cache though.)
* @todo Add a global lock to ensure that caches are not primed in concurrent
* requests.
*/
function drupal_flush_all_caches() {
$module_handler = \Drupal::moduleHandler();
// Flush all persistent caches.
// This is executed based on old/previously known information, which is
// sufficient, since new extensions cannot have any primed caches yet.
$module_handler->invokeAll('cache_flush');
foreach (Cache::getBins() as $service_id => $cache_backend) {
$cache_backend->deleteAll();
}
// Flush asset file caches.
\Drupal::service('asset.css.collection_optimizer')->deleteAll();
\Drupal::service('asset.js.collection_optimizer')->deleteAll();
_drupal_flush_css_js();
// Reset all static caches.
drupal_static_reset();
// Invalidate the container.
\Drupal::service('kernel')->invalidateContainer();
// Wipe the Twig PHP Storage cache.
PhpStorageFactory::get('twig')->deleteAll();
// Rebuild module and theme data.
$module_data = system_rebuild_module_data();
/** @var \Drupal\Core\Extension\ThemeHandlerInterface $theme_handler */
$theme_handler = \Drupal::service('theme_handler');
$theme_handler->refreshInfo();
// In case the active theme gets requested later in the same request we need
// to reset the theme manager.
\Drupal::theme()->resetActiveTheme();
// Rebuild and reboot a new kernel. A simple DrupalKernel reboot is not
// sufficient, since the list of enabled modules might have been adjusted
// above due to changed code.
$files = [];
foreach ($module_data as $name => $extension) {
if ($extension->status) {
$files[$name] = $extension;
}
}
\Drupal::service('kernel')->updateModules($module_handler->getModuleList(), $files);
// New container, new module handler.
$module_handler = \Drupal::moduleHandler();
// Ensure that all modules that are currently supposed to be enabled are
// actually loaded.
$module_handler->loadAll();
// Rebuild all information based on new module data.
$module_handler->invokeAll('rebuild');
// Clear all plugin caches.
\Drupal::service('plugin.cache_clearer')->clearCachedDefinitions();
// Rebuild the menu router based on all rebuilt data.
// Important: This rebuild must happen last, so the menu router is guaranteed
// to be based on up to date information.
\Drupal::service('router.builder')->rebuild();
// Re-initialize the maintenance theme, if the current request attempted to
// use it. Unlike regular usages of this function, the installer and update
// scripts need to flush all caches during GET requests/page building.
if (function_exists('_drupal_maintenance_theme')) {
\Drupal::theme()->resetActiveTheme();
drupal_maintenance_theme();
}
}
/**
* Changes the dummy query string added to all CSS and JavaScript files.
*
* Changing the dummy query string appended to CSS and JavaScript files forces
* all browsers to reload fresh files.
*/
function _drupal_flush_css_js() {
// The timestamp is converted to base 36 in order to make it more compact.
Drupal::state()->set('system.css_js_query_string', base_convert(REQUEST_TIME, 10, 36));
}
/**
* Outputs debug information.
*
* The debug information is passed on to trigger_error() after being converted
* to a string using _drupal_debug_message().
*
* @param $data
* Data to be output.
* @param $label
* Label to prefix the data.
* @param $print_r
* Flag to switch between print_r() and var_export() for data conversion to
* string. Set $print_r to FALSE to use var_export() instead of print_r().
* Passing recursive data structures to var_export() will generate an error.
*/
function debug($data, $label = NULL, $print_r = TRUE) {
// Print $data contents to string.
$string = Html::escape($print_r ? print_r($data, TRUE) : var_export($data, TRUE));
// Display values with pre-formatting to increase readability.
$string = '' . $string . '
';
trigger_error(trim($label ? "$label: $string" : $string));
}
/**
* Checks whether a version is compatible with a given dependency.
*
* @param $v
* A parsed dependency structure e.g. from ModuleHandler::parseDependency().
* @param $current_version
* The version to check against (like 4.2).
*
* @return
* NULL if compatible, otherwise the original dependency version string that
* caused the incompatibility.
*
* @see \Drupal\Core\Extension\ModuleHandler::parseDependency()
*/
function drupal_check_incompatibility($v, $current_version) {
if (!empty($v['versions'])) {
foreach ($v['versions'] as $required_version) {
if ((isset($required_version['op']) && !version_compare($current_version, $required_version['version'], $required_version['op']))) {
return $v['original_version'];
}
}
}
}
/**
* Returns a string of supported archive extensions.
*
* @return
* A space-separated string of extensions suitable for use by the file
* validation system.
*/
function archiver_get_extensions() {
$valid_extensions = [];
foreach (\Drupal::service('plugin.manager.archiver')->getDefinitions() as $archive) {
foreach ($archive['extensions'] as $extension) {
foreach (explode('.', $extension) as $part) {
if (!in_array($part, $valid_extensions)) {
$valid_extensions[] = $part;
}
}
}
}
return implode(' ', $valid_extensions);
}
/**
* Creates the appropriate archiver for the specified file.
*
* @param $file
* The full path of the archive file. Note that stream wrapper paths are
* supported, but not remote ones.
*
* @return
* A newly created instance of the archiver class appropriate
* for the specified file, already bound to that file.
* If no appropriate archiver class was found, will return FALSE.
*/
function archiver_get_archiver($file) {
// Archivers can only work on local paths
$filepath = \Drupal::service('file_system')->realpath($file);
if (!is_file($filepath)) {
throw new Exception(t('Archivers can only operate on local files: %file not supported', ['%file' => $file]));
}
return \Drupal::service('plugin.manager.archiver')->getInstance(['filepath' => $filepath]);
}
/**
* Assembles the Drupal Updater registry.
*
* An Updater is a class that knows how to update various parts of the Drupal
* file system, for example to update modules that have newer releases, or to
* install a new theme.
*
* @return array
* The Drupal Updater class registry.
*
* @see \Drupal\Core\Updater\Updater
* @see hook_updater_info()
* @see hook_updater_info_alter()
*/
function drupal_get_updaters() {
$updaters = &drupal_static(__FUNCTION__);
if (!isset($updaters)) {
$updaters = \Drupal::moduleHandler()->invokeAll('updater_info');
\Drupal::moduleHandler()->alter('updater_info', $updaters);
uasort($updaters, [SortArray::class, 'sortByWeightElement']);
}
return $updaters;
}
/**
* Assembles the Drupal FileTransfer registry.
*
* @return
* The Drupal FileTransfer class registry.
*
* @see \Drupal\Core\FileTransfer\FileTransfer
* @see hook_filetransfer_info()
* @see hook_filetransfer_info_alter()
*/
function drupal_get_filetransfer_info() {
$info = &drupal_static(__FUNCTION__);
if (!isset($info)) {
$info = \Drupal::moduleHandler()->invokeAll('filetransfer_info');
\Drupal::moduleHandler()->alter('filetransfer_info', $info);
uasort($info, [SortArray::class, 'sortByWeightElement']);
}
return $info;
}