Drupal 8  8.0.2
MachineName Class Reference
Inheritance diagram for MachineName:

Public Member Functions

 getInfo ()
- Public Member Functions inherited from Textfield
 getInfo ()
- Public Member Functions inherited from PluginInspectionInterface
 getPluginId ()
 getPluginDefinition ()

Static Public Member Functions

static valueCallback (&$element, $input, FormStateInterface $form_state)
static processMachineName (&$element, FormStateInterface $form_state, &$complete_form)
static validateMachineName (&$element, FormStateInterface $form_state, &$complete_form)
- Static Public Member Functions inherited from Textfield
static valueCallback (&$element, $input, FormStateInterface $form_state)
static preRenderTextfield ($element)
- Static Public Member Functions inherited from FormElement
static valueCallback (&$element, $input, FormStateInterface $form_state)
static processPattern (&$element, FormStateInterface $form_state, &$complete_form)
static validatePattern (&$element, FormStateInterface $form_state, &$complete_form)
- Static Public Member Functions inherited from RenderElement
static setAttributes (&$element, $class=array())
static preRenderGroup ($element)
static processAjaxForm (&$element, FormStateInterface $form_state, &$complete_form)
static preRenderAjaxForm ($element)
static processGroup (&$element, FormStateInterface $form_state, &$complete_form)

Detailed Description

Provides a machine name render element.

Provides a form element to enter a machine name, which is validated to ensure that the name is unique and does not contain disallowed characters.

The element may be automatically populated via JavaScript when used in conjunction with a separate "source" form element (typically specifying the human-readable name). As the user types text into the source element, the JavaScript converts all values to lower case, replaces any remaining disallowed characters with a replacement, and populates the associated machine name form element.


  • #machine_name: An associative array containing:
    • exists: A callable to invoke for checking whether a submitted machine name value already exists. The submitted value is passed as an argument. In most cases, an existing API or menu argument loader function can be re-used. The callback is only invoked if the submitted value differs from the element's #default_value.
    • source: (optional) The #array_parents of the form element containing the human-readable name (i.e., as contained in the $form structure) to use as source for the machine name. Defaults to array('label').
    • label: (optional) Text to display as label for the machine name value after the human-readable name form element. Defaults to t('Machine name').
    • replace_pattern: (optional) A regular expression (without delimiters) matching disallowed characters in the machine name. Defaults to '[^a-z0-9_]+'.
    • replace: (optional) A character to replace disallowed characters in the machine name via JavaScript. Defaults to '_' (underscore). When using a different character, 'replace_pattern' needs to be set accordingly.
    • error: (optional) A custom form error message string to show, if the machine name contains disallowed characters.
    • standalone: (optional) Whether the live preview should stay in its own form element rather than in the suffix of the source element. Defaults to FALSE.
  • #maxlength: (optional) Maximum allowed length of the machine name. Defaults to 64.
  • #disabled: (optional) Should be set to TRUE if an existing machine name must not be changed after initial creation.

Usage example:

$form['id'] = array(
'#type' => 'machine_name',
'#default_value' => $this->entity->id(),
'#disabled' => !$this->entity->isNew(),
'#maxlength' => 64,
'#description' => $this->t('A unique name for this item. It must only contain lowercase letters, numbers, and underscores.'),
'#machine_name' => array(
'exists' => array($this, 'exists'),
See Also


Member Function Documentation

getInfo ( )

{Returns the element properties for this element.

array An array of element properties. See ::getInfo() for documentation of the standard properties of all elements, and the return value format.

Implements ElementInterface.

static processMachineName ( $element,
FormStateInterface  $form_state,

Processes a machine-readable name form element.

array$elementThe form element to process. See main class documentation for properties.
\Drupal\Core\Form\FormStateInterface$form_stateThe current state of the form.
array$complete_formThe complete form structure.
array The processed element.

References FormStateInterface\getCompleteForm(), NestedArray\getValue(), Drupal\languageManager(), NestedArray\setValue(), and t().

Referenced by MachineNameTest\testProcessMachineName().

Here is the call graph for this function:

Here is the caller graph for this function:

static validateMachineName ( $element,
FormStateInterface  $form_state,

Form element validation handler for machine_name elements.

Note that #maxlength is validated by _form_validate() already.

This checks that the submitted value:

  • Does not contain the replacement character only.
  • Does not contain disallowed characters.
  • Is unique; i.e., does not already exist.
  • Does not exceed the maximum length (via #maxlength).
  • Cannot be changed after creation (via #disabled).

References FormStateInterface\setError(), and t().

Here is the call graph for this function:

static valueCallback ( $element,
FormStateInterface  $form_state 

{Determines how user input is mapped to an element's #value property.

array$elementAn associative array containing the properties of the element.
mixed$inputThe incoming input to populate the form element. If this is FALSE, the element's default value should be returned.
\Drupal\Core\Form\FormStateInterface$form_stateThe current state of the form.
mixed The value to assign to the element.

Implements FormElementInterface.

Referenced by MachineNameTest\testValueCallback().

Here is the caller graph for this function:

The documentation for this class was generated from the following file: