The implementations declared by this hook specify how a particular render
array is to be rendered as HTML.

Parameters

array $existing:
An array of existing implementations that may be used for override
purposes. This is primarily useful for themes that may wish to examine
existing implementations to extract data (such as arguments) so that
it may properly register its own, higher priority implementations.

$type:
Whether a theme, module, etc. is being processed. This is primarily useful
so that themes tell if they are the actual theme being called or a parent
theme. May be one of:

'module': A module is being checked for theme implementations.

'base_theme_engine': A theme engine is being checked for a theme that is
a parent of the actual theme being used.

'theme_engine': A theme engine is being checked for the actual theme
being used.

'base_theme': A base theme is being checked for theme implementations.

'theme': The actual theme in use is being checked.

$theme:
The actual name of theme, module, etc. that is being being processed.

$path:
The directory path of the theme or module, so that it doesn't need to be
looked up.

Return value

array
An associative array of information about theme implementations. The keys
on the outer array are known as "theme hooks". For theme suggestions,
instead of the array key being the base theme hook, the key is a theme
suggestion name with the format 'base_hook_name__sub_hook_name'.
For render elements, the key is the machine name of the render element.
The array values are themselves arrays containing information about the
theme hook and its implementation. Each information array must contain
either a 'variables' element (for using a #theme element) or a
'render element' element (for render elements), but not both.
The following elements may be part of each information array:

variables: Only used for #theme in render array: an array of variables,
where the array keys are the names of the variables, and the array
values are the default values if they are not given in the render array.
Template implementations receive each array key as a variable in the
template file (so they must be legal PHP/Twig variable names). Function
implementations are passed the variables in a single $variables function
argument. If you are using these variables in a render array, prefix the
variable names defined here with a #.

render element: Used for render element items only: the name of the
renderable element or element tree to pass to the theme function. This
name is used as the name of the variable that holds the renderable
element or tree in preprocess and process functions.

file: The file the implementation resides in. This file will be included
prior to the theme being rendered, to make sure that the function or
preprocess function (as needed) is actually loaded.

path: Override the path of the file to be used. Ordinarily the module or
theme path will be used, but if the file will not be in the default
path, include it here. This path should be relative to the Drupal root
directory.

template: If specified, the theme implementation is a template file, and
this is the template name. Do not add 'html.twig' on the end of the
template name. The extension will be added automatically by the default
rendering engine (which is Twig.) If 'path' is specified, 'template'
should also be specified. If neither 'template' nor 'function' are
specified, a default template name will be assumed. For example, if a
module registers the 'search_result' theme hook, 'search-result' will be
assigned as its template name.

function: (deprecated in Drupal 8.0.x, will be removed in Drupal 9.0.x)
If specified, this will be the function name to invoke for this
implementation. If neither 'template' nor 'function' are specified, a
default template name will be assumed. See above for more details.

base hook: Used for theme suggestions only: the base theme hook name.
Instead of this suggestion's implementation being used directly, the base
hook will be invoked with this implementation as its first suggestion.
The base hook's files will be included and the base hook's preprocess
functions will be called in place of any suggestion's preprocess
functions. If an implementation of hook_theme_suggestions_HOOK() (where
HOOK is the base hook) changes the suggestion order, a different
suggestion may be used in place of this suggestion. If after
hook_theme_suggestions_HOOK() this suggestion remains the first
suggestion, then this suggestion's function or template will be used to
generate the rendered output.

pattern: A regular expression pattern to be used to allow this theme
implementation to have a dynamic name. The convention is to use __ to
differentiate the dynamic portion of the theme. For example, to allow
forums to be themed individually, the pattern might be: 'forum__'. Then,
when the forum is rendered, following render array can be used:

preprocess functions: A list of functions used to preprocess this data.
Ordinarily this won't be used; it's automatically filled in. By default,
for a module this will be filled in as template_preprocess_HOOK. For
a theme this will be filled in as twig_preprocess and
twig_preprocess_HOOK as well as themename_preprocess and
themename_preprocess_HOOK.

override preprocess functions: Set to TRUE when a theme does NOT want
the standard preprocess functions to run. This can be used to give a
theme FULL control over how variables are set. For example, if a theme
wants total control over how certain variables in the page.html.twig are
set, this can be set to true. Please keep in mind that when this is used
by a theme, that theme becomes responsible for making sure necessary
variables are set.

type: (automatically derived) Where the theme hook is defined:
'module', 'theme_engine', or 'theme'.

theme path: (automatically derived) The directory path of the theme or
module, so that it doesn't need to be looked up.