Chris@0: <?php
Chris@0: 
Chris@0: namespace Drupal\Core\Theme;
Chris@0: 
Chris@0: /**
Chris@0:  * Provides a high level access to the active theme and methods to use it.
Chris@0:  *
Chris@0:  * Beside the active theme it provides a wrapper around _theme as well as the
Chris@0:  * alter functionality for themes.
Chris@0:  */
Chris@0: interface ThemeManagerInterface {
Chris@0: 
Chris@0:   /**
Chris@0:    * Generates themed output.
Chris@0:    *
Chris@0:    * See the @link themeable Default theme implementations topic @endlink for
Chris@0:    * details.
Chris@0:    *
Chris@0:    * @param string $hook
Chris@0:    *   The name of the theme hook to call.
Chris@0:    * @param array $variables
Chris@0:    *   An associative array of theme variables.
Chris@0:    *
Chris@0:    * @return string|\Drupal\Component\Render\MarkupInterface
Chris@0:    *   The rendered output, or a Markup object.
Chris@0:    */
Chris@0:   public function render($hook, array $variables);
Chris@0: 
Chris@0:   /**
Chris@0:    * Returns the active theme object.
Chris@0:    *
Chris@0:    * @return \Drupal\Core\Theme\ActiveTheme
Chris@0:    */
Chris@0:   public function getActiveTheme();
Chris@0: 
Chris@0:   /**
Chris@0:    * Determines whether there is an active theme.
Chris@0:    *
Chris@0:    * @return bool
Chris@0:    */
Chris@0:   public function hasActiveTheme();
Chris@0: 
Chris@0:   /**
Chris@0:    * Resets the current active theme.
Chris@0:    *
Chris@0:    * Note: This method should not be used in common cases, just in special cases
Chris@0:    * like tests.
Chris@0:    *
Chris@0:    * @return $this
Chris@0:    */
Chris@0:   public function resetActiveTheme();
Chris@0: 
Chris@0:   /**
Chris@0:    * Sets the current active theme manually.
Chris@0:    *
Chris@0:    * Note: This method should not be used in common cases, just in special cases
Chris@0:    * like tests.
Chris@0:    *
Chris@0:    * @param \Drupal\Core\Theme\ActiveTheme $active_theme
Chris@0:    *   The new active theme.
Chris@0:    * @return $this
Chris@0:    */
Chris@0:   public function setActiveTheme(ActiveTheme $active_theme);
Chris@0: 
Chris@0:   /**
Chris@0:    * Passes alterable variables to specific $theme_TYPE_alter() implementations.
Chris@0:    *
Chris@0:    * Executes an alter hook on the current theme. It also invokes alter hooks
Chris@0:    * for all base themes.
Chris@0:    *
Chris@0:    * $theme specifies the theme name of the active theme and all its base
Chris@0:    * themes.
Chris@0:    *
Chris@0:    * This dispatch function hands off the passed-in variables to type-specific
Chris@0:    * $theme_TYPE_alter() implementations in the active theme. It ensures a
Chris@0:    * consistent interface for all altering operations.
Chris@0:    *
Chris@0:    * A maximum of 2 alterable arguments is supported. In case more arguments
Chris@0:    * need to be passed and alterable, modules provide additional variables
Chris@0:    * assigned by reference in the last $context argument:
Chris@0:    * @code
Chris@0:    *   $context = array(
Chris@0:    *     'alterable' => &$alterable,
Chris@0:    *     'unalterable' => $unalterable,
Chris@0:    *     'foo' => 'bar',
Chris@0:    *   );
Chris@0:    *   $this->alter('mymodule_data', $alterable1, $alterable2, $context);
Chris@0:    * @endcode
Chris@0:    *
Chris@0:    * Note that objects are always passed by reference in PHP5. If it is
Chris@0:    * absolutely required that no implementation alters a passed object in
Chris@0:    * $context, then an object needs to be cloned:
Chris@0:    * @code
Chris@0:    *   $context = array(
Chris@0:    *     'unalterable_object' => clone $object,
Chris@0:    *   );
Chris@0:    *   $this->alter('mymodule_data', $data, $context);
Chris@0:    * @endcode
Chris@0:    *
Chris@0:    * @param string|array $type
Chris@0:    *   A string describing the type of the alterable $data. 'form', 'links',
Chris@0:    *   'node_content', and so on are several examples. Alternatively can be an
Chris@0:    *   array, in which case $theme_TYPE_alter() is invoked for each value in the
Chris@0:    *   array. When Form API is using $this->alter() to
Chris@0:    *   execute both $theme_form_alter() and $theme_form_FORM_ID_alter()
Chris@0:    *   implementations, it passes array('form', 'form_' . $form_id) for $type.
Chris@0:    * @param mixed $data
Chris@0:    *   The variable that will be passed to $theme_TYPE_alter() implementations
Chris@0:    *   to be altered. The type of this variable depends on the value of the
Chris@0:    *   $type argument. For example, when altering a 'form', $data will be a
Chris@0:    *   structured array. When altering a 'profile', $data will be an object.
Chris@0:    * @param mixed $context1
Chris@0:    *   (optional) An additional variable that is passed by reference.
Chris@0:    * @param mixed $context2
Chris@0:    *   (optional) An additional variable that is passed by reference. If more
Chris@0:    *   context needs to be provided to implementations, then this should be an
Chris@0:    *   associative array as described above.
Chris@0:    *
Chris@0:    * @see \Drupal\Core\Extension\ModuleHandlerInterface
Chris@0:    */
Chris@0:   public function alter($type, &$data, &$context1 = NULL, &$context2 = NULL);
Chris@0: 
Chris@0:   /**
Chris@0:    * Provides an alter hook for a specific theme.
Chris@0:    *
Chris@0:    * Similar to ::alter, it also invokes the alter hooks for the base themes.
Chris@0:    *
Chris@0:    * @param \Drupal\Core\Theme\ActiveTheme $theme
Chris@0:    *   A manually specified theme.
Chris@0:    * @param string|array $type
Chris@0:    *   A string describing the type of the alterable $data.
Chris@0:    * @param mixed $data
Chris@0:    *   The variable that will be passed to $theme_TYPE_alter() implementations
Chris@0:    * @param mixed $context1
Chris@0:    *   (optional) An additional variable that is passed by reference.
Chris@0:    * @param mixed $context2
Chris@0:    *   (optional) An additional variable that is passed by reference.
Chris@0:    *
Chris@0:    * @see ::alter
Chris@0:    */
Chris@0:   public function alterForTheme(ActiveTheme $theme, $type, &$data, &$context1 = NULL, &$context2 = NULL);
Chris@0: 
Chris@0: }