Constructs a new class instance.
When possible, use the
\Drupal\Core\StringTranslation\StringTranslationTrait $this->t(). Otherwise
create a new \Drupal\Core\StringTranslation\TranslatableMarkup object
directly.
Calling the trait's t() method or instantiating a new TranslatableMarkup
object serves two purposes:
- At run-time it translates user-visible text into the appropriate
language.
- Static analyzers detect calls to t() and new TranslatableMarkup, and add
the first argument (the string to be translated) to the database of
strings that need translation. These strings are expected to be in
English, so the first argument should always be in English.
To allow the site to be localized, it is important that all human-readable
text that will be displayed on the site or sent to a user is made available
in one of the ways supported by the
@link https://www.drupal.org/node/322729 Localization API @endlink.
See the @link https://www.drupal.org/node/322729 Localization API @endlink
pages for more information, including recommendations on how to break up or
not break up strings for translation.
@section sec_translating_vars Translating Variables
$string should always be an English literal string.
$string should never contain a variable, such as:
@code
new TranslatableMarkup($text)
@endcode
There are several reasons for this:
- Using a variable for $string that is user input is a security risk.
- Using a variable for $string that has even guaranteed safe text (for
example, user interface text provided literally in code), will not be
picked up by the localization static text processor. (The parameter could
be a variable if the entire string in $text has been passed into t() or
new TranslatableMarkup() elsewhere as the first argument, but that
strategy is not recommended.)
It is especially important never to call new TranslatableMarkup($user_text)
or t($user_text) where $user_text is some text that a user entered -- doing
that can lead to cross-site scripting and other security problems. However,
you can use variable substitution in your string, to put variable text such
as user names or link URLs into translated text. Variable substitution
looks like this:
@code
new TranslatableMarkup("@name's blog", array('@name' => $account->getDisplayName()));
@endcode
Basically, you can put placeholders like @name into your string, and the
method will substitute the sanitized values at translation time. (See the
Localization API pages referenced above and the documentation of
\Drupal\Component\Render\FormattableMarkup::placeholderFormat()
for details about how to safely and correctly define variables in your
string.) Translators can then rearrange the string as necessary for the
language (e.g., in Spanish, it might be "blog de @name").
@param string $string
A string containing the English text to translate.
@param array $arguments
(optional) An associative array of replacements to make after
translation. Based on the first character of the key, the value is
escaped and/or themed. See
\Drupal\Component\Render\FormattableMarkup::placeholderFormat() for
details.
@param array $options
(optional) An associative array of additional options, with the following
elements:
- 'langcode' (defaults to the current language): A language code, to
translate to a language other than what is used to display the page.
- 'context' (defaults to the empty context): The context the source
string belongs to.
@param \Drupal\Core\StringTranslation\TranslationInterface $string_translation
(optional) The string translation service.
@throws \InvalidArgumentException
Exception thrown when $string is not a string.
@see \Drupal\Component\Render\FormattableMarkup::placeholderFormat()
@see \Drupal\Core\StringTranslation\StringTranslationTrait::t()
@ingroup sanitization
Defined in <ROOT>/core/lib/Drupal/Core/StringTranslation/TranslatableMarkup.php:129
→public __sleep()
Magic __sleep() method to avoid serializing the string translator.
Defined in <ROOT>/core/lib/Drupal/Core/StringTranslation/TranslatableMarkup.php:203
→public __toString()
Implements the magic __toString() method.
Defined in <ROOT>/core/lib/Drupal/Component/Utility/ToStringTrait.php:13
→public count() -> int
Returns the string length.
@return int
The length of the string.
Defined in <ROOT>/core/lib/Drupal/Core/StringTranslation/TranslatableMarkup.php:227
→public getArguments() -> mixed[]
Gets all arguments from this translated string.
@return mixed[]
The array of arguments.
Defined in <ROOT>/core/lib/Drupal/Core/StringTranslation/TranslatableMarkup.php:178
→public getOption($name) -> mixed
Gets a specific option from this translated string.
@param string $name
Option name.
@return mixed
The value of this option or empty string of option is not set.
Defined in <ROOT>/core/lib/Drupal/Core/StringTranslation/TranslatableMarkup.php:158
→public getOptions() -> mixed[]
Gets all options from this translated string.
@return mixed[]
The array of options.
Defined in <ROOT>/core/lib/Drupal/Core/StringTranslation/TranslatableMarkup.php:168
→public getUntranslatedString() -> string
Gets the untranslated string value stored in this translated string.
@return string
The string stored in this wrapper.
Defined in <ROOT>/core/lib/Drupal/Core/StringTranslation/TranslatableMarkup.php:145
→public jsonSerialize() -> string
Returns a representation of the object for use in JSON serialization.
@return string
The safe string content.
Inherited from Drupal\Component\Render\FormattableMarkup
Defined in <ROOT>/core/lib/Drupal/Component/Render/FormattableMarkup.php:118
→public render() -> string
Renders the object as a string.
@return string
The translated string.
Defined in <ROOT>/core/lib/Drupal/Core/StringTranslation/TranslatableMarkup.php:188
Escapes a placeholder replacement value if needed.
@param string|\Drupal\Component\Render\MarkupInterface $value
A placeholder replacement value.
@return string
The properly escaped replacement value.
Inherited from Drupal\Component\Render\FormattableMarkup
Defined in <ROOT>/core/lib/Drupal/Component/Render/FormattableMarkup.php:264
Replaces placeholders in a string with values.
@param string $string
A string containing placeholders. The string itself is expected to be
safe and correct HTML. Any unsafe content must be in $args and
inserted via placeholders.
@param array $args
An associative array of replacements. Each array key should be the same
as a placeholder in $string. The corresponding value should be a string
or an object that implements
\Drupal\Component\Render\MarkupInterface. The value replaces the
placeholder in $string. Sanitization and formatting will be done before
replacement. The type of sanitization and formatting depends on the first
character of the key:
- @variable: When the placeholder replacement value is:
- A string, the replaced value in the returned string will be sanitized
using \Drupal\Component\Utility\Html::escape().
- A MarkupInterface object, the replaced value in the returned string
will not be sanitized.
- A MarkupInterface object cast to a string, the replaced value in the
returned string be forcibly sanitized using
\Drupal\Component\Utility\Html::escape().
@code
$this->placeholderFormat('This will force HTML-escaping of the replacement value: @text', ['@text' => (string) $safe_string_interface_object));
@endcode
Use this placeholder as the default choice for anything displayed on
the site, but not within HTML attributes, JavaScript, or CSS. Doing so
is a security risk.
- %variable: Use when the replacement value is to be wrapped in <em>
tags.
A call like:
@code
$string = "%output_text";
$arguments = ['%output_text' => 'text output here.'];
$this->placeholderFormat($string, $arguments);
@endcode
makes the following HTML code:
@code
<em class="placeholder">text output here.</em>
@endcode
As with @variable, do not use this within HTML attributes, JavaScript,
or CSS. Doing so is a security risk.
- :variable: Return value is escaped with
\Drupal\Component\Utility\Html::escape() and filtered for dangerous
protocols using UrlHelper::stripDangerousProtocols(). Use this when
using the "href" attribute, ensuring the attribute value is always
wrapped in quotes:
@code
// Secure (with quotes):
$this->placeholderFormat('<a href=":url">@variable</a>', [':url' => $url, '@variable' => $variable]);
// Insecure (without quotes):
$this->placeholderFormat('<a href=:url>@variable</a>', [':url' => $url, '@variable' => $variable]);
@endcode
When ":variable" comes from arbitrary user input, the result is secure,
but not guaranteed to be a valid URL (which means the resulting output
could fail HTML validation). To guarantee a valid URL, use
Url::fromUri($user_input)->toString() (which either throws an exception
or returns a well-formed URL) before passing the result into a
":variable" placeholder.
@return string
A formatted HTML string with the placeholders replaced.
@ingroup sanitization
@see \Drupal\Core\StringTranslation\TranslatableMarkup
@see \Drupal\Core\StringTranslation\PluralTranslatableMarkup
@see \Drupal\Component\Utility\Html::escape()
@see \Drupal\Component\Utility\UrlHelper::stripDangerousProtocols()
@see \Drupal\Core\Url::fromUri()
Inherited from Drupal\Component\Render\FormattableMarkup
Defined in <ROOT>/core/lib/Drupal/Component/Render/FormattableMarkup.php:194
→protected _die()
For test purposes, wrap die() in an overridable method.
Defined in <ROOT>/core/lib/Drupal/Component/Utility/ToStringTrait.php:31
Gets the string translation service.
@return \Drupal\Core\StringTranslation\TranslationInterface
The string translation service.
Defined in <ROOT>/core/lib/Drupal/Core/StringTranslation/TranslatableMarkup.php:213
Constructs a new class instance.
When possible, use the
\Drupal\Core\StringTranslation\StringTranslationTrait $this->t(). Otherwise
create a new \Drupal\Core\StringTranslation\TranslatableMarkup object
directly.
Calling the trait's t() method or instantiating a new TranslatableMarkup
object serves two purposes:
- At run-time it translates user-visible text into the appropriate
language.
- Static analyzers detect calls to t() and new TranslatableMarkup, and add
the first argument (the string to be translated) to the database of
strings that need translation. These strings are expected to be in
English, so the first argument should always be in English.
To allow the site to be localized, it is important that all human-readable
text that will be displayed on the site or sent to a user is made available
in one of the ways supported by the
@link https://www.drupal.org/node/322729 Localization API @endlink.
See the @link https://www.drupal.org/node/322729 Localization API @endlink
pages for more information, including recommendations on how to break up or
not break up strings for translation.
@section sec_translating_vars Translating Variables
$string should always be an English literal string.
$string should never contain a variable, such as:
@code
new TranslatableMarkup($text)
@endcode
There are several reasons for this:
- Using a variable for $string that is user input is a security risk.
- Using a variable for $string that has even guaranteed safe text (for
example, user interface text provided literally in code), will not be
picked up by the localization static text processor. (The parameter could
be a variable if the entire string in $text has been passed into t() or
new TranslatableMarkup() elsewhere as the first argument, but that
strategy is not recommended.)
It is especially important never to call new TranslatableMarkup($user_text)
or t($user_text) where $user_text is some text that a user entered -- doing
that can lead to cross-site scripting and other security problems. However,
you can use variable substitution in your string, to put variable text such
as user names or link URLs into translated text. Variable substitution
looks like this:
@code
new TranslatableMarkup("@name's blog", array('@name' => $account->getDisplayName()));
@endcode
Basically, you can put placeholders like @name into your string, and the
method will substitute the sanitized values at translation time. (See the
Localization API pages referenced above and the documentation of
\Drupal\Component\Render\FormattableMarkup::placeholderFormat()
for details about how to safely and correctly define variables in your
string.) Translators can then rearrange the string as necessary for the
language (e.g., in Spanish, it might be "blog de @name").
@param string $string
A string containing the English text to translate.
@param array $arguments
(optional) An associative array of replacements to make after
translation. Based on the first character of the key, the value is
escaped and/or themed. See
\Drupal\Component\Render\FormattableMarkup::placeholderFormat() for
details.
@param array $options
(optional) An associative array of additional options, with the following
elements:
- 'langcode' (defaults to the current language): A language code, to
translate to a language other than what is used to display the page.
- 'context' (defaults to the empty context): The context the source
string belongs to.
@param \Drupal\Core\StringTranslation\TranslationInterface $string_translation
(optional) The string translation service.
@throws \InvalidArgumentException
Exception thrown when $string is not a string.
@see \Drupal\Component\Render\FormattableMarkup::placeholderFormat()
@see \Drupal\Core\StringTranslation\StringTranslationTrait::t()
@ingroup sanitization
Defined in <ROOT>/core/lib/Drupal/Core/StringTranslation/TranslatableMarkup.php:129
→public __sleep()
Magic __sleep() method to avoid serializing the string translator.
Defined in <ROOT>/core/lib/Drupal/Core/StringTranslation/TranslatableMarkup.php:203
→public __toString()
Implements the magic __toString() method.
Defined in <ROOT>/core/lib/Drupal/Component/Utility/ToStringTrait.php:13
→public count() -> int
Returns the string length.
@return int
The length of the string.
Defined in <ROOT>/core/lib/Drupal/Core/StringTranslation/TranslatableMarkup.php:227
→public getArguments() -> mixed[]
Gets all arguments from this translated string.
@return mixed[]
The array of arguments.
Defined in <ROOT>/core/lib/Drupal/Core/StringTranslation/TranslatableMarkup.php:178
→public getOption($name) -> mixed
Gets a specific option from this translated string.
@param string $name
Option name.
@return mixed
The value of this option or empty string of option is not set.
Defined in <ROOT>/core/lib/Drupal/Core/StringTranslation/TranslatableMarkup.php:158
→public getOptions() -> mixed[]
Gets all options from this translated string.
@return mixed[]
The array of options.
Defined in <ROOT>/core/lib/Drupal/Core/StringTranslation/TranslatableMarkup.php:168
→public getUntranslatedString() -> string
Gets the untranslated string value stored in this translated string.
@return string
The string stored in this wrapper.
Defined in <ROOT>/core/lib/Drupal/Core/StringTranslation/TranslatableMarkup.php:145
→public jsonSerialize() -> string
Returns a representation of the object for use in JSON serialization.
@return string
The safe string content.
Inherited from Drupal\Component\Render\FormattableMarkup
Defined in <ROOT>/core/lib/Drupal/Component/Render/FormattableMarkup.php:118
→public render() -> string
Renders the object as a string.
@return string
The translated string.
Defined in <ROOT>/core/lib/Drupal/Core/StringTranslation/TranslatableMarkup.php:188
Escapes a placeholder replacement value if needed.
@param string|\Drupal\Component\Render\MarkupInterface $value
A placeholder replacement value.
@return string
The properly escaped replacement value.
Inherited from Drupal\Component\Render\FormattableMarkup
Defined in <ROOT>/core/lib/Drupal/Component/Render/FormattableMarkup.php:264
Replaces placeholders in a string with values.
@param string $string
A string containing placeholders. The string itself is expected to be
safe and correct HTML. Any unsafe content must be in $args and
inserted via placeholders.
@param array $args
An associative array of replacements. Each array key should be the same
as a placeholder in $string. The corresponding value should be a string
or an object that implements
\Drupal\Component\Render\MarkupInterface. The value replaces the
placeholder in $string. Sanitization and formatting will be done before
replacement. The type of sanitization and formatting depends on the first
character of the key:
- @variable: When the placeholder replacement value is:
- A string, the replaced value in the returned string will be sanitized
using \Drupal\Component\Utility\Html::escape().
- A MarkupInterface object, the replaced value in the returned string
will not be sanitized.
- A MarkupInterface object cast to a string, the replaced value in the
returned string be forcibly sanitized using
\Drupal\Component\Utility\Html::escape().
@code
$this->placeholderFormat('This will force HTML-escaping of the replacement value: @text', ['@text' => (string) $safe_string_interface_object));
@endcode
Use this placeholder as the default choice for anything displayed on
the site, but not within HTML attributes, JavaScript, or CSS. Doing so
is a security risk.
- %variable: Use when the replacement value is to be wrapped in <em>
tags.
A call like:
@code
$string = "%output_text";
$arguments = ['%output_text' => 'text output here.'];
$this->placeholderFormat($string, $arguments);
@endcode
makes the following HTML code:
@code
<em class="placeholder">text output here.</em>
@endcode
As with @variable, do not use this within HTML attributes, JavaScript,
or CSS. Doing so is a security risk.
- :variable: Return value is escaped with
\Drupal\Component\Utility\Html::escape() and filtered for dangerous
protocols using UrlHelper::stripDangerousProtocols(). Use this when
using the "href" attribute, ensuring the attribute value is always
wrapped in quotes:
@code
// Secure (with quotes):
$this->placeholderFormat('<a href=":url">@variable</a>', [':url' => $url, '@variable' => $variable]);
// Insecure (without quotes):
$this->placeholderFormat('<a href=:url>@variable</a>', [':url' => $url, '@variable' => $variable]);
@endcode
When ":variable" comes from arbitrary user input, the result is secure,
but not guaranteed to be a valid URL (which means the resulting output
could fail HTML validation). To guarantee a valid URL, use
Url::fromUri($user_input)->toString() (which either throws an exception
or returns a well-formed URL) before passing the result into a
":variable" placeholder.
@return string
A formatted HTML string with the placeholders replaced.
@ingroup sanitization
@see \Drupal\Core\StringTranslation\TranslatableMarkup
@see \Drupal\Core\StringTranslation\PluralTranslatableMarkup
@see \Drupal\Component\Utility\Html::escape()
@see \Drupal\Component\Utility\UrlHelper::stripDangerousProtocols()
@see \Drupal\Core\Url::fromUri()
Inherited from Drupal\Component\Render\FormattableMarkup
Defined in <ROOT>/core/lib/Drupal/Component/Render/FormattableMarkup.php:194
→protected _die()
For test purposes, wrap die() in an overridable method.
Defined in <ROOT>/core/lib/Drupal/Component/Utility/ToStringTrait.php:31
Gets the string translation service.
@return \Drupal\Core\StringTranslation\TranslationInterface
The string translation service.
Defined in <ROOT>/core/lib/Drupal/Core/StringTranslation/TranslatableMarkup.php:213
Constructs a new class instance.
When possible, use the
\Drupal\Core\StringTranslation\StringTranslationTrait $this->t(). Otherwise
create a new \Drupal\Core\StringTranslation\TranslatableMarkup object
directly.
Calling the trait's t() method or instantiating a new TranslatableMarkup
object serves two purposes:
- At run-time it translates user-visible text into the appropriate
language.
- Static analyzers detect calls to t() and new TranslatableMarkup, and add
the first argument (the string to be translated) to the database of
strings that need translation. These strings are expected to be in
English, so the first argument should always be in English.
To allow the site to be localized, it is important that all human-readable
text that will be displayed on the site or sent to a user is made available
in one of the ways supported by the
@link https://www.drupal.org/node/322729 Localization API @endlink.
See the @link https://www.drupal.org/node/322729 Localization API @endlink
pages for more information, including recommendations on how to break up or
not break up strings for translation.
@section sec_translating_vars Translating Variables
$string should always be an English literal string.
$string should never contain a variable, such as:
@code
new TranslatableMarkup($text)
@endcode
There are several reasons for this:
- Using a variable for $string that is user input is a security risk.
- Using a variable for $string that has even guaranteed safe text (for
example, user interface text provided literally in code), will not be
picked up by the localization static text processor. (The parameter could
be a variable if the entire string in $text has been passed into t() or
new TranslatableMarkup() elsewhere as the first argument, but that
strategy is not recommended.)
It is especially important never to call new TranslatableMarkup($user_text)
or t($user_text) where $user_text is some text that a user entered -- doing
that can lead to cross-site scripting and other security problems. However,
you can use variable substitution in your string, to put variable text such
as user names or link URLs into translated text. Variable substitution
looks like this:
@code
new TranslatableMarkup("@name's blog", array('@name' => $account->getDisplayName()));
@endcode
Basically, you can put placeholders like @name into your string, and the
method will substitute the sanitized values at translation time. (See the
Localization API pages referenced above and the documentation of
\Drupal\Component\Render\FormattableMarkup::placeholderFormat()
for details about how to safely and correctly define variables in your
string.) Translators can then rearrange the string as necessary for the
language (e.g., in Spanish, it might be "blog de @name").
@param string $string
A string containing the English text to translate.
@param array $arguments
(optional) An associative array of replacements to make after
translation. Based on the first character of the key, the value is
escaped and/or themed. See
\Drupal\Component\Render\FormattableMarkup::placeholderFormat() for
details.
@param array $options
(optional) An associative array of additional options, with the following
elements:
- 'langcode' (defaults to the current language): A language code, to
translate to a language other than what is used to display the page.
- 'context' (defaults to the empty context): The context the source
string belongs to.
@param \Drupal\Core\StringTranslation\TranslationInterface $string_translation
(optional) The string translation service.
@throws \InvalidArgumentException
Exception thrown when $string is not a string.
@see \Drupal\Component\Render\FormattableMarkup::placeholderFormat()
@see \Drupal\Core\StringTranslation\StringTranslationTrait::t()
@ingroup sanitization
Defined in <ROOT>/core/lib/Drupal/Core/StringTranslation/TranslatableMarkup.php:129
→public __sleep()
Magic __sleep() method to avoid serializing the string translator.
Defined in <ROOT>/core/lib/Drupal/Core/StringTranslation/TranslatableMarkup.php:203
→public __toString()
Implements the magic __toString() method.
Defined in <ROOT>/core/lib/Drupal/Component/Utility/ToStringTrait.php:13
→public count() -> int
Returns the string length.
@return int
The length of the string.
Defined in <ROOT>/core/lib/Drupal/Core/StringTranslation/TranslatableMarkup.php:227
→public getArguments() -> mixed[]
Gets all arguments from this translated string.
@return mixed[]
The array of arguments.
Defined in <ROOT>/core/lib/Drupal/Core/StringTranslation/TranslatableMarkup.php:178
→public getOption($name) -> mixed
Gets a specific option from this translated string.
@param string $name
Option name.
@return mixed
The value of this option or empty string of option is not set.
Defined in <ROOT>/core/lib/Drupal/Core/StringTranslation/TranslatableMarkup.php:158
→public getOptions() -> mixed[]
Gets all options from this translated string.
@return mixed[]
The array of options.
Defined in <ROOT>/core/lib/Drupal/Core/StringTranslation/TranslatableMarkup.php:168
→public getUntranslatedString() -> string
Gets the untranslated string value stored in this translated string.
@return string
The string stored in this wrapper.
Defined in <ROOT>/core/lib/Drupal/Core/StringTranslation/TranslatableMarkup.php:145
→public jsonSerialize() -> string
Returns a representation of the object for use in JSON serialization.
@return string
The safe string content.
Inherited from Drupal\Component\Render\FormattableMarkup
Defined in <ROOT>/core/lib/Drupal/Component/Render/FormattableMarkup.php:118
→public render() -> string
Renders the object as a string.
@return string
The translated string.
Defined in <ROOT>/core/lib/Drupal/Core/StringTranslation/TranslatableMarkup.php:188
Escapes a placeholder replacement value if needed.
@param string|\Drupal\Component\Render\MarkupInterface $value
A placeholder replacement value.
@return string
The properly escaped replacement value.
Inherited from Drupal\Component\Render\FormattableMarkup
Defined in <ROOT>/core/lib/Drupal/Component/Render/FormattableMarkup.php:264
Replaces placeholders in a string with values.
@param string $string
A string containing placeholders. The string itself is expected to be
safe and correct HTML. Any unsafe content must be in $args and
inserted via placeholders.
@param array $args
An associative array of replacements. Each array key should be the same
as a placeholder in $string. The corresponding value should be a string
or an object that implements
\Drupal\Component\Render\MarkupInterface. The value replaces the
placeholder in $string. Sanitization and formatting will be done before
replacement. The type of sanitization and formatting depends on the first
character of the key:
- @variable: When the placeholder replacement value is:
- A string, the replaced value in the returned string will be sanitized
using \Drupal\Component\Utility\Html::escape().
- A MarkupInterface object, the replaced value in the returned string
will not be sanitized.
- A MarkupInterface object cast to a string, the replaced value in the
returned string be forcibly sanitized using
\Drupal\Component\Utility\Html::escape().
@code
$this->placeholderFormat('This will force HTML-escaping of the replacement value: @text', ['@text' => (string) $safe_string_interface_object));
@endcode
Use this placeholder as the default choice for anything displayed on
the site, but not within HTML attributes, JavaScript, or CSS. Doing so
is a security risk.
- %variable: Use when the replacement value is to be wrapped in <em>
tags.
A call like:
@code
$string = "%output_text";
$arguments = ['%output_text' => 'text output here.'];
$this->placeholderFormat($string, $arguments);
@endcode
makes the following HTML code:
@code
<em class="placeholder">text output here.</em>
@endcode
As with @variable, do not use this within HTML attributes, JavaScript,
or CSS. Doing so is a security risk.
- :variable: Return value is escaped with
\Drupal\Component\Utility\Html::escape() and filtered for dangerous
protocols using UrlHelper::stripDangerousProtocols(). Use this when
using the "href" attribute, ensuring the attribute value is always
wrapped in quotes:
@code
// Secure (with quotes):
$this->placeholderFormat('<a href=":url">@variable</a>', [':url' => $url, '@variable' => $variable]);
// Insecure (without quotes):
$this->placeholderFormat('<a href=:url>@variable</a>', [':url' => $url, '@variable' => $variable]);
@endcode
When ":variable" comes from arbitrary user input, the result is secure,
but not guaranteed to be a valid URL (which means the resulting output
could fail HTML validation). To guarantee a valid URL, use
Url::fromUri($user_input)->toString() (which either throws an exception
or returns a well-formed URL) before passing the result into a
":variable" placeholder.
@return string
A formatted HTML string with the placeholders replaced.
@ingroup sanitization
@see \Drupal\Core\StringTranslation\TranslatableMarkup
@see \Drupal\Core\StringTranslation\PluralTranslatableMarkup
@see \Drupal\Component\Utility\Html::escape()
@see \Drupal\Component\Utility\UrlHelper::stripDangerousProtocols()
@see \Drupal\Core\Url::fromUri()
Inherited from Drupal\Component\Render\FormattableMarkup
Defined in <ROOT>/core/lib/Drupal/Component/Render/FormattableMarkup.php:194
→protected _die()
For test purposes, wrap die() in an overridable method.
Defined in <ROOT>/core/lib/Drupal/Component/Utility/ToStringTrait.php:31
Gets the string translation service.
@return \Drupal\Core\StringTranslation\TranslationInterface
The string translation service.
Defined in <ROOT>/core/lib/Drupal/Core/StringTranslation/TranslatableMarkup.php:213
Constructs a new class instance.
When possible, use the
\Drupal\Core\StringTranslation\StringTranslationTrait $this->t(). Otherwise
create a new \Drupal\Core\StringTranslation\TranslatableMarkup object
directly.
Calling the trait's t() method or instantiating a new TranslatableMarkup
object serves two purposes:
- At run-time it translates user-visible text into the appropriate
language.
- Static analyzers detect calls to t() and new TranslatableMarkup, and add
the first argument (the string to be translated) to the database of
strings that need translation. These strings are expected to be in
English, so the first argument should always be in English.
To allow the site to be localized, it is important that all human-readable
text that will be displayed on the site or sent to a user is made available
in one of the ways supported by the
@link https://www.drupal.org/node/322729 Localization API @endlink.
See the @link https://www.drupal.org/node/322729 Localization API @endlink
pages for more information, including recommendations on how to break up or
not break up strings for translation.
@section sec_translating_vars Translating Variables
$string should always be an English literal string.
$string should never contain a variable, such as:
@code
new TranslatableMarkup($text)
@endcode
There are several reasons for this:
- Using a variable for $string that is user input is a security risk.
- Using a variable for $string that has even guaranteed safe text (for
example, user interface text provided literally in code), will not be
picked up by the localization static text processor. (The parameter could
be a variable if the entire string in $text has been passed into t() or
new TranslatableMarkup() elsewhere as the first argument, but that
strategy is not recommended.)
It is especially important never to call new TranslatableMarkup($user_text)
or t($user_text) where $user_text is some text that a user entered -- doing
that can lead to cross-site scripting and other security problems. However,
you can use variable substitution in your string, to put variable text such
as user names or link URLs into translated text. Variable substitution
looks like this:
@code
new TranslatableMarkup("@name's blog", array('@name' => $account->getDisplayName()));
@endcode
Basically, you can put placeholders like @name into your string, and the
method will substitute the sanitized values at translation time. (See the
Localization API pages referenced above and the documentation of
\Drupal\Component\Render\FormattableMarkup::placeholderFormat()
for details about how to safely and correctly define variables in your
string.) Translators can then rearrange the string as necessary for the
language (e.g., in Spanish, it might be "blog de @name").
@param string $string
A string containing the English text to translate.
@param array $arguments
(optional) An associative array of replacements to make after
translation. Based on the first character of the key, the value is
escaped and/or themed. See
\Drupal\Component\Render\FormattableMarkup::placeholderFormat() for
details.
@param array $options
(optional) An associative array of additional options, with the following
elements:
- 'langcode' (defaults to the current language): A language code, to
translate to a language other than what is used to display the page.
- 'context' (defaults to the empty context): The context the source
string belongs to.
@param \Drupal\Core\StringTranslation\TranslationInterface $string_translation
(optional) The string translation service.
@throws \InvalidArgumentException
Exception thrown when $string is not a string.
@see \Drupal\Component\Render\FormattableMarkup::placeholderFormat()
@see \Drupal\Core\StringTranslation\StringTranslationTrait::t()
@ingroup sanitization
Defined in <ROOT>/core/lib/Drupal/Core/StringTranslation/TranslatableMarkup.php:129
→public __sleep()
Magic __sleep() method to avoid serializing the string translator.
Defined in <ROOT>/core/lib/Drupal/Core/StringTranslation/TranslatableMarkup.php:203
→public __toString()
Implements the magic __toString() method.
Defined in <ROOT>/core/lib/Drupal/Component/Utility/ToStringTrait.php:13
→public count() -> int
Returns the string length.
@return int
The length of the string.
Defined in <ROOT>/core/lib/Drupal/Core/StringTranslation/TranslatableMarkup.php:227
→public getArguments() -> mixed[]
Gets all arguments from this translated string.
@return mixed[]
The array of arguments.
Defined in <ROOT>/core/lib/Drupal/Core/StringTranslation/TranslatableMarkup.php:178
→public getOption($name) -> mixed
Gets a specific option from this translated string.
@param string $name
Option name.
@return mixed
The value of this option or empty string of option is not set.
Defined in <ROOT>/core/lib/Drupal/Core/StringTranslation/TranslatableMarkup.php:158
→public getOptions() -> mixed[]
Gets all options from this translated string.
@return mixed[]
The array of options.
Defined in <ROOT>/core/lib/Drupal/Core/StringTranslation/TranslatableMarkup.php:168
→public getUntranslatedString() -> string
Gets the untranslated string value stored in this translated string.
@return string
The string stored in this wrapper.
Defined in <ROOT>/core/lib/Drupal/Core/StringTranslation/TranslatableMarkup.php:145
→public jsonSerialize() -> string
Returns a representation of the object for use in JSON serialization.
@return string
The safe string content.
Inherited from Drupal\Component\Render\FormattableMarkup
Defined in <ROOT>/core/lib/Drupal/Component/Render/FormattableMarkup.php:118
→public render() -> string
Renders the object as a string.
@return string
The translated string.
Defined in <ROOT>/core/lib/Drupal/Core/StringTranslation/TranslatableMarkup.php:188
Escapes a placeholder replacement value if needed.
@param string|\Drupal\Component\Render\MarkupInterface $value
A placeholder replacement value.
@return string
The properly escaped replacement value.
Inherited from Drupal\Component\Render\FormattableMarkup
Defined in <ROOT>/core/lib/Drupal/Component/Render/FormattableMarkup.php:264
Replaces placeholders in a string with values.
@param string $string
A string containing placeholders. The string itself is expected to be
safe and correct HTML. Any unsafe content must be in $args and
inserted via placeholders.
@param array $args
An associative array of replacements. Each array key should be the same
as a placeholder in $string. The corresponding value should be a string
or an object that implements
\Drupal\Component\Render\MarkupInterface. The value replaces the
placeholder in $string. Sanitization and formatting will be done before
replacement. The type of sanitization and formatting depends on the first
character of the key:
- @variable: When the placeholder replacement value is:
- A string, the replaced value in the returned string will be sanitized
using \Drupal\Component\Utility\Html::escape().
- A MarkupInterface object, the replaced value in the returned string
will not be sanitized.
- A MarkupInterface object cast to a string, the replaced value in the
returned string be forcibly sanitized using
\Drupal\Component\Utility\Html::escape().
@code
$this->placeholderFormat('This will force HTML-escaping of the replacement value: @text', ['@text' => (string) $safe_string_interface_object));
@endcode
Use this placeholder as the default choice for anything displayed on
the site, but not within HTML attributes, JavaScript, or CSS. Doing so
is a security risk.
- %variable: Use when the replacement value is to be wrapped in <em>
tags.
A call like:
@code
$string = "%output_text";
$arguments = ['%output_text' => 'text output here.'];
$this->placeholderFormat($string, $arguments);
@endcode
makes the following HTML code:
@code
<em class="placeholder">text output here.</em>
@endcode
As with @variable, do not use this within HTML attributes, JavaScript,
or CSS. Doing so is a security risk.
- :variable: Return value is escaped with
\Drupal\Component\Utility\Html::escape() and filtered for dangerous
protocols using UrlHelper::stripDangerousProtocols(). Use this when
using the "href" attribute, ensuring the attribute value is always
wrapped in quotes:
@code
// Secure (with quotes):
$this->placeholderFormat('<a href=":url">@variable</a>', [':url' => $url, '@variable' => $variable]);
// Insecure (without quotes):
$this->placeholderFormat('<a href=:url>@variable</a>', [':url' => $url, '@variable' => $variable]);
@endcode
When ":variable" comes from arbitrary user input, the result is secure,
but not guaranteed to be a valid URL (which means the resulting output
could fail HTML validation). To guarantee a valid URL, use
Url::fromUri($user_input)->toString() (which either throws an exception
or returns a well-formed URL) before passing the result into a
":variable" placeholder.
@return string
A formatted HTML string with the placeholders replaced.
@ingroup sanitization
@see \Drupal\Core\StringTranslation\TranslatableMarkup
@see \Drupal\Core\StringTranslation\PluralTranslatableMarkup
@see \Drupal\Component\Utility\Html::escape()
@see \Drupal\Component\Utility\UrlHelper::stripDangerousProtocols()
@see \Drupal\Core\Url::fromUri()
Inherited from Drupal\Component\Render\FormattableMarkup
Defined in <ROOT>/core/lib/Drupal/Component/Render/FormattableMarkup.php:194
→protected _die()
For test purposes, wrap die() in an overridable method.
Defined in <ROOT>/core/lib/Drupal/Component/Utility/ToStringTrait.php:31
Gets the string translation service.
@return \Drupal\Core\StringTranslation\TranslationInterface
The string translation service.
Defined in <ROOT>/core/lib/Drupal/Core/StringTranslation/TranslatableMarkup.php:213
Constructs a new class instance.
When possible, use the
\Drupal\Core\StringTranslation\StringTranslationTrait $this->t(). Otherwise
create a new \Drupal\Core\StringTranslation\TranslatableMarkup object
directly.
Calling the trait's t() method or instantiating a new TranslatableMarkup
object serves two purposes:
- At run-time it translates user-visible text into the appropriate
language.
- Static analyzers detect calls to t() and new TranslatableMarkup, and add
the first argument (the string to be translated) to the database of
strings that need translation. These strings are expected to be in
English, so the first argument should always be in English.
To allow the site to be localized, it is important that all human-readable
text that will be displayed on the site or sent to a user is made available
in one of the ways supported by the
@link https://www.drupal.org/node/322729 Localization API @endlink.
See the @link https://www.drupal.org/node/322729 Localization API @endlink
pages for more information, including recommendations on how to break up or
not break up strings for translation.
@section sec_translating_vars Translating Variables
$string should always be an English literal string.
$string should never contain a variable, such as:
@code
new TranslatableMarkup($text)
@endcode
There are several reasons for this:
- Using a variable for $string that is user input is a security risk.
- Using a variable for $string that has even guaranteed safe text (for
example, user interface text provided literally in code), will not be
picked up by the localization static text processor. (The parameter could
be a variable if the entire string in $text has been passed into t() or
new TranslatableMarkup() elsewhere as the first argument, but that
strategy is not recommended.)
It is especially important never to call new TranslatableMarkup($user_text)
or t($user_text) where $user_text is some text that a user entered -- doing
that can lead to cross-site scripting and other security problems. However,
you can use variable substitution in your string, to put variable text such
as user names or link URLs into translated text. Variable substitution
looks like this:
@code
new TranslatableMarkup("@name's blog", array('@name' => $account->getDisplayName()));
@endcode
Basically, you can put placeholders like @name into your string, and the
method will substitute the sanitized values at translation time. (See the
Localization API pages referenced above and the documentation of
\Drupal\Component\Render\FormattableMarkup::placeholderFormat()
for details about how to safely and correctly define variables in your
string.) Translators can then rearrange the string as necessary for the
language (e.g., in Spanish, it might be "blog de @name").
@param string $string
A string containing the English text to translate.
@param array $arguments
(optional) An associative array of replacements to make after
translation. Based on the first character of the key, the value is
escaped and/or themed. See
\Drupal\Component\Render\FormattableMarkup::placeholderFormat() for
details.
@param array $options
(optional) An associative array of additional options, with the following
elements:
- 'langcode' (defaults to the current language): A language code, to
translate to a language other than what is used to display the page.
- 'context' (defaults to the empty context): The context the source
string belongs to.
@param \Drupal\Core\StringTranslation\TranslationInterface $string_translation
(optional) The string translation service.
@throws \InvalidArgumentException
Exception thrown when $string is not a string.
@see \Drupal\Component\Render\FormattableMarkup::placeholderFormat()
@see \Drupal\Core\StringTranslation\StringTranslationTrait::t()
@ingroup sanitization
Defined in <ROOT>/core/lib/Drupal/Core/StringTranslation/TranslatableMarkup.php:129
→public __sleep()
Magic __sleep() method to avoid serializing the string translator.
Defined in <ROOT>/core/lib/Drupal/Core/StringTranslation/TranslatableMarkup.php:203
→public __toString()
Implements the magic __toString() method.
Defined in <ROOT>/core/lib/Drupal/Component/Utility/ToStringTrait.php:13
→public count() -> int
Returns the string length.
@return int
The length of the string.
Defined in <ROOT>/core/lib/Drupal/Core/StringTranslation/TranslatableMarkup.php:227
→public getArguments() -> mixed[]
Gets all arguments from this translated string.
@return mixed[]
The array of arguments.
Defined in <ROOT>/core/lib/Drupal/Core/StringTranslation/TranslatableMarkup.php:178
→public getOption($name) -> mixed
Gets a specific option from this translated string.
@param string $name
Option name.
@return mixed
The value of this option or empty string of option is not set.
Defined in <ROOT>/core/lib/Drupal/Core/StringTranslation/TranslatableMarkup.php:158
→public getOptions() -> mixed[]
Gets all options from this translated string.
@return mixed[]
The array of options.
Defined in <ROOT>/core/lib/Drupal/Core/StringTranslation/TranslatableMarkup.php:168
→public getUntranslatedString() -> string
Gets the untranslated string value stored in this translated string.
@return string
The string stored in this wrapper.
Defined in <ROOT>/core/lib/Drupal/Core/StringTranslation/TranslatableMarkup.php:145
→public jsonSerialize() -> string
Returns a representation of the object for use in JSON serialization.
@return string
The safe string content.
Inherited from Drupal\Component\Render\FormattableMarkup
Defined in <ROOT>/core/lib/Drupal/Component/Render/FormattableMarkup.php:118
→public render() -> string
Renders the object as a string.
@return string
The translated string.
Defined in <ROOT>/core/lib/Drupal/Core/StringTranslation/TranslatableMarkup.php:188
Escapes a placeholder replacement value if needed.
@param string|\Drupal\Component\Render\MarkupInterface $value
A placeholder replacement value.
@return string
The properly escaped replacement value.
Inherited from Drupal\Component\Render\FormattableMarkup
Defined in <ROOT>/core/lib/Drupal/Component/Render/FormattableMarkup.php:264
Replaces placeholders in a string with values.
@param string $string
A string containing placeholders. The string itself is expected to be
safe and correct HTML. Any unsafe content must be in $args and
inserted via placeholders.
@param array $args
An associative array of replacements. Each array key should be the same
as a placeholder in $string. The corresponding value should be a string
or an object that implements
\Drupal\Component\Render\MarkupInterface. The value replaces the
placeholder in $string. Sanitization and formatting will be done before
replacement. The type of sanitization and formatting depends on the first
character of the key:
- @variable: When the placeholder replacement value is:
- A string, the replaced value in the returned string will be sanitized
using \Drupal\Component\Utility\Html::escape().
- A MarkupInterface object, the replaced value in the returned string
will not be sanitized.
- A MarkupInterface object cast to a string, the replaced value in the
returned string be forcibly sanitized using
\Drupal\Component\Utility\Html::escape().
@code
$this->placeholderFormat('This will force HTML-escaping of the replacement value: @text', ['@text' => (string) $safe_string_interface_object));
@endcode
Use this placeholder as the default choice for anything displayed on
the site, but not within HTML attributes, JavaScript, or CSS. Doing so
is a security risk.
- %variable: Use when the replacement value is to be wrapped in <em>
tags.
A call like:
@code
$string = "%output_text";
$arguments = ['%output_text' => 'text output here.'];
$this->placeholderFormat($string, $arguments);
@endcode
makes the following HTML code:
@code
<em class="placeholder">text output here.</em>
@endcode
As with @variable, do not use this within HTML attributes, JavaScript,
or CSS. Doing so is a security risk.
- :variable: Return value is escaped with
\Drupal\Component\Utility\Html::escape() and filtered for dangerous
protocols using UrlHelper::stripDangerousProtocols(). Use this when
using the "href" attribute, ensuring the attribute value is always
wrapped in quotes:
@code
// Secure (with quotes):
$this->placeholderFormat('<a href=":url">@variable</a>', [':url' => $url, '@variable' => $variable]);
// Insecure (without quotes):
$this->placeholderFormat('<a href=:url>@variable</a>', [':url' => $url, '@variable' => $variable]);
@endcode
When ":variable" comes from arbitrary user input, the result is secure,
but not guaranteed to be a valid URL (which means the resulting output
could fail HTML validation). To guarantee a valid URL, use
Url::fromUri($user_input)->toString() (which either throws an exception
or returns a well-formed URL) before passing the result into a
":variable" placeholder.
@return string
A formatted HTML string with the placeholders replaced.
@ingroup sanitization
@see \Drupal\Core\StringTranslation\TranslatableMarkup
@see \Drupal\Core\StringTranslation\PluralTranslatableMarkup
@see \Drupal\Component\Utility\Html::escape()
@see \Drupal\Component\Utility\UrlHelper::stripDangerousProtocols()
@see \Drupal\Core\Url::fromUri()
Inherited from Drupal\Component\Render\FormattableMarkup
Defined in <ROOT>/core/lib/Drupal/Component/Render/FormattableMarkup.php:194
→protected _die()
For test purposes, wrap die() in an overridable method.
Defined in <ROOT>/core/lib/Drupal/Component/Utility/ToStringTrait.php:31
Gets the string translation service.
@return \Drupal\Core\StringTranslation\TranslationInterface
The string translation service.
Defined in <ROOT>/core/lib/Drupal/Core/StringTranslation/TranslatableMarkup.php:213
Constructs a new class instance.
When possible, use the
\Drupal\Core\StringTranslation\StringTranslationTrait $this->t(). Otherwise
create a new \Drupal\Core\StringTranslation\TranslatableMarkup object
directly.
Calling the trait's t() method or instantiating a new TranslatableMarkup
object serves two purposes:
- At run-time it translates user-visible text into the appropriate
language.
- Static analyzers detect calls to t() and new TranslatableMarkup, and add
the first argument (the string to be translated) to the database of
strings that need translation. These strings are expected to be in
English, so the first argument should always be in English.
To allow the site to be localized, it is important that all human-readable
text that will be displayed on the site or sent to a user is made available
in one of the ways supported by the
@link https://www.drupal.org/node/322729 Localization API @endlink.
See the @link https://www.drupal.org/node/322729 Localization API @endlink
pages for more information, including recommendations on how to break up or
not break up strings for translation.
@section sec_translating_vars Translating Variables
$string should always be an English literal string.
$string should never contain a variable, such as:
@code
new TranslatableMarkup($text)
@endcode
There are several reasons for this:
- Using a variable for $string that is user input is a security risk.
- Using a variable for $string that has even guaranteed safe text (for
example, user interface text provided literally in code), will not be
picked up by the localization static text processor. (The parameter could
be a variable if the entire string in $text has been passed into t() or
new TranslatableMarkup() elsewhere as the first argument, but that
strategy is not recommended.)
It is especially important never to call new TranslatableMarkup($user_text)
or t($user_text) where $user_text is some text that a user entered -- doing
that can lead to cross-site scripting and other security problems. However,
you can use variable substitution in your string, to put variable text such
as user names or link URLs into translated text. Variable substitution
looks like this:
@code
new TranslatableMarkup("@name's blog", array('@name' => $account->getDisplayName()));
@endcode
Basically, you can put placeholders like @name into your string, and the
method will substitute the sanitized values at translation time. (See the
Localization API pages referenced above and the documentation of
\Drupal\Component\Render\FormattableMarkup::placeholderFormat()
for details about how to safely and correctly define variables in your
string.) Translators can then rearrange the string as necessary for the
language (e.g., in Spanish, it might be "blog de @name").
@param string $string
A string containing the English text to translate.
@param array $arguments
(optional) An associative array of replacements to make after
translation. Based on the first character of the key, the value is
escaped and/or themed. See
\Drupal\Component\Render\FormattableMarkup::placeholderFormat() for
details.
@param array $options
(optional) An associative array of additional options, with the following
elements:
- 'langcode' (defaults to the current language): A language code, to
translate to a language other than what is used to display the page.
- 'context' (defaults to the empty context): The context the source
string belongs to.
@param \Drupal\Core\StringTranslation\TranslationInterface $string_translation
(optional) The string translation service.
@throws \InvalidArgumentException
Exception thrown when $string is not a string.
@see \Drupal\Component\Render\FormattableMarkup::placeholderFormat()
@see \Drupal\Core\StringTranslation\StringTranslationTrait::t()
@ingroup sanitization
Defined in <ROOT>/core/lib/Drupal/Core/StringTranslation/TranslatableMarkup.php:129
→public __sleep()
Magic __sleep() method to avoid serializing the string translator.
Defined in <ROOT>/core/lib/Drupal/Core/StringTranslation/TranslatableMarkup.php:203
→public __toString()
Implements the magic __toString() method.
Defined in <ROOT>/core/lib/Drupal/Component/Utility/ToStringTrait.php:13
→public count() -> int
Returns the string length.
@return int
The length of the string.
Defined in <ROOT>/core/lib/Drupal/Core/StringTranslation/TranslatableMarkup.php:227
→public getArguments() -> mixed[]
Gets all arguments from this translated string.
@return mixed[]
The array of arguments.
Defined in <ROOT>/core/lib/Drupal/Core/StringTranslation/TranslatableMarkup.php:178
→public getOption($name) -> mixed
Gets a specific option from this translated string.
@param string $name
Option name.
@return mixed
The value of this option or empty string of option is not set.
Defined in <ROOT>/core/lib/Drupal/Core/StringTranslation/TranslatableMarkup.php:158
→public getOptions() -> mixed[]
Gets all options from this translated string.
@return mixed[]
The array of options.
Defined in <ROOT>/core/lib/Drupal/Core/StringTranslation/TranslatableMarkup.php:168
→public getUntranslatedString() -> string
Gets the untranslated string value stored in this translated string.
@return string
The string stored in this wrapper.
Defined in <ROOT>/core/lib/Drupal/Core/StringTranslation/TranslatableMarkup.php:145
→public jsonSerialize() -> string
Returns a representation of the object for use in JSON serialization.
@return string
The safe string content.
Inherited from Drupal\Component\Render\FormattableMarkup
Defined in <ROOT>/core/lib/Drupal/Component/Render/FormattableMarkup.php:118
→public render() -> string
Renders the object as a string.
@return string
The translated string.
Defined in <ROOT>/core/lib/Drupal/Core/StringTranslation/TranslatableMarkup.php:188
Escapes a placeholder replacement value if needed.
@param string|\Drupal\Component\Render\MarkupInterface $value
A placeholder replacement value.
@return string
The properly escaped replacement value.
Inherited from Drupal\Component\Render\FormattableMarkup
Defined in <ROOT>/core/lib/Drupal/Component/Render/FormattableMarkup.php:264
Replaces placeholders in a string with values.
@param string $string
A string containing placeholders. The string itself is expected to be
safe and correct HTML. Any unsafe content must be in $args and
inserted via placeholders.
@param array $args
An associative array of replacements. Each array key should be the same
as a placeholder in $string. The corresponding value should be a string
or an object that implements
\Drupal\Component\Render\MarkupInterface. The value replaces the
placeholder in $string. Sanitization and formatting will be done before
replacement. The type of sanitization and formatting depends on the first
character of the key:
- @variable: When the placeholder replacement value is:
- A string, the replaced value in the returned string will be sanitized
using \Drupal\Component\Utility\Html::escape().
- A MarkupInterface object, the replaced value in the returned string
will not be sanitized.
- A MarkupInterface object cast to a string, the replaced value in the
returned string be forcibly sanitized using
\Drupal\Component\Utility\Html::escape().
@code
$this->placeholderFormat('This will force HTML-escaping of the replacement value: @text', ['@text' => (string) $safe_string_interface_object));
@endcode
Use this placeholder as the default choice for anything displayed on
the site, but not within HTML attributes, JavaScript, or CSS. Doing so
is a security risk.
- %variable: Use when the replacement value is to be wrapped in <em>
tags.
A call like:
@code
$string = "%output_text";
$arguments = ['%output_text' => 'text output here.'];
$this->placeholderFormat($string, $arguments);
@endcode
makes the following HTML code:
@code
<em class="placeholder">text output here.</em>
@endcode
As with @variable, do not use this within HTML attributes, JavaScript,
or CSS. Doing so is a security risk.
- :variable: Return value is escaped with
\Drupal\Component\Utility\Html::escape() and filtered for dangerous
protocols using UrlHelper::stripDangerousProtocols(). Use this when
using the "href" attribute, ensuring the attribute value is always
wrapped in quotes:
@code
// Secure (with quotes):
$this->placeholderFormat('<a href=":url">@variable</a>', [':url' => $url, '@variable' => $variable]);
// Insecure (without quotes):
$this->placeholderFormat('<a href=:url>@variable</a>', [':url' => $url, '@variable' => $variable]);
@endcode
When ":variable" comes from arbitrary user input, the result is secure,
but not guaranteed to be a valid URL (which means the resulting output
could fail HTML validation). To guarantee a valid URL, use
Url::fromUri($user_input)->toString() (which either throws an exception
or returns a well-formed URL) before passing the result into a
":variable" placeholder.
@return string
A formatted HTML string with the placeholders replaced.
@ingroup sanitization
@see \Drupal\Core\StringTranslation\TranslatableMarkup
@see \Drupal\Core\StringTranslation\PluralTranslatableMarkup
@see \Drupal\Component\Utility\Html::escape()
@see \Drupal\Component\Utility\UrlHelper::stripDangerousProtocols()
@see \Drupal\Core\Url::fromUri()
Inherited from Drupal\Component\Render\FormattableMarkup
Defined in <ROOT>/core/lib/Drupal/Component/Render/FormattableMarkup.php:194
→protected _die()
For test purposes, wrap die() in an overridable method.
Defined in <ROOT>/core/lib/Drupal/Component/Utility/ToStringTrait.php:31
Gets the string translation service.
@return \Drupal\Core\StringTranslation\TranslationInterface
The string translation service.
Defined in <ROOT>/core/lib/Drupal/Core/StringTranslation/TranslatableMarkup.php:213
protected class -> string(23) "Drupal\node\Entity\Node"
protected provider -> string(4) "node"
protected _serviceIds -> array(0)
protected _entityStorages -> array(0)
protected stringTranslation -> NULL
constant ID_MAX_LENGTH :: integer32
constant BUNDLE_MAX_LENGTH :: integer32
→public __construct($definition)
{@inheritdoc}
Defined in <ROOT>/core/lib/Drupal/Core/Entity/ContentEntityType.php:32
→public __sleep()
{@inheritdoc}
Inherited from Drupal\Core\Entity\EntityType
Defined in <ROOT>/core/lib/Drupal/Core/DependencyInjection/DependencySerializationTrait.php:30
→public __wakeup()
{@inheritdoc}
Inherited from Drupal\Core\Entity\EntityType
Defined in <ROOT>/core/lib/Drupal/Core/DependencyInjection/DependencySerializationTrait.php:65
{@inheritdoc}
Inherited from Drupal\Core\Entity\EntityType
Defined in <ROOT>/core/lib/Drupal/Core/Entity/EntityType.php:897
→public entityClassImplements($interface)
{@inheritdoc}
Inherited from Drupal\Core\Entity\EntityType
Defined in <ROOT>/core/lib/Drupal/Core/Entity/EntityType.php:439
→public get($property)
{@inheritdoc}
Inherited from Drupal\Core\Entity\EntityType
Defined in <ROOT>/core/lib/Drupal/Core/Entity/EntityType.php:342
→public getAccessControlClass()
{@inheritdoc}
Inherited from Drupal\Core\Entity\EntityType
Defined in <ROOT>/core/lib/Drupal/Core/Entity/EntityType.php:599
→public getAdminPermission()
{@inheritdoc}
Inherited from Drupal\Core\Entity\EntityType
Defined in <ROOT>/core/lib/Drupal/Core/Entity/EntityType.php:614
→public getBaseTable()
{@inheritdoc}
Inherited from Drupal\Core\Entity\EntityType
Defined in <ROOT>/core/lib/Drupal/Core/Entity/EntityType.php:714
→public getBundleConfigDependency($bundle)
{@inheritdoc}
Inherited from Drupal\Core\Entity\EntityType
Defined in <ROOT>/core/lib/Drupal/Core/Entity/EntityType.php:905
→public getBundleEntityType()
{@inheritdoc}
Inherited from Drupal\Core\Entity\EntityType
Defined in <ROOT>/core/lib/Drupal/Core/Entity/EntityType.php:685
→public getBundleLabel()
{@inheritdoc}
Inherited from Drupal\Core\Entity\EntityType
Defined in <ROOT>/core/lib/Drupal/Core/Entity/EntityType.php:699
→public getBundleOf()
{@inheritdoc}
Inherited from Drupal\Core\Entity\EntityType
Defined in <ROOT>/core/lib/Drupal/Core/Entity/EntityType.php:692
→public getClass()
{@inheritdoc}
Inherited from Drupal\Component\Plugin\Definition\PluginDefinition
Defined in <ROOT>/core/lib/Drupal/Component/Plugin/Definition/PluginDefinition.php:49
→public getCollectionLabel()
{@inheritdoc}
Inherited from Drupal\Core\Entity\EntityType
Defined in <ROOT>/core/lib/Drupal/Core/Entity/EntityType.php:778
→public getConfigDependencyKey()
{@inheritdoc}
Defined in <ROOT>/core/lib/Drupal/Core/Entity/ContentEntityType.php:62
→public getConstraints()
{@inheritdoc}
Inherited from Drupal\Core\Entity\EntityType
Defined in <ROOT>/core/lib/Drupal/Core/Entity/EntityType.php:882
→public getCountLabel($count)
{@inheritdoc}
Inherited from Drupal\Core\Entity\EntityType
Defined in <ROOT>/core/lib/Drupal/Core/Entity/EntityType.php:811
→public getDataTable()
{@inheritdoc}
Inherited from Drupal\Core\Entity\EntityType
Defined in <ROOT>/core/lib/Drupal/Core/Entity/EntityType.php:757
→public getFormClass($operation)
{@inheritdoc}
Inherited from Drupal\Core\Entity\EntityType
Defined in <ROOT>/core/lib/Drupal/Core/Entity/EntityType.php:519
→public getGroup()
{@inheritdoc}
Inherited from Drupal\Core\Entity\EntityType
Defined in <ROOT>/core/lib/Drupal/Core/Entity/EntityType.php:837
→public getGroupLabel()
{@inheritdoc}
Inherited from Drupal\Core\Entity\EntityType
Defined in <ROOT>/core/lib/Drupal/Core/Entity/EntityType.php:844
{@inheritdoc}
Inherited from Drupal\Core\Entity\EntityType
Defined in <ROOT>/core/lib/Drupal/Core/Entity/EntityType.php:460
→public getHandlerClasses()
{@inheritdoc}
Inherited from Drupal\Core\Entity\EntityType
Defined in <ROOT>/core/lib/Drupal/Core/Entity/EntityType.php:453
→public getKey($key)
{@inheritdoc}
Inherited from Drupal\Core\Entity\EntityType
Defined in <ROOT>/core/lib/Drupal/Core/Entity/EntityType.php:403
→public getKeys()
{@inheritdoc}
Inherited from Drupal\Core\Entity\EntityType
Defined in <ROOT>/core/lib/Drupal/Core/Entity/EntityType.php:396
→public getLabel()
{@inheritdoc}
Inherited from Drupal\Core\Entity\EntityType
Defined in <ROOT>/core/lib/Drupal/Core/Entity/EntityType.php:764
→public getLabelCallback()
{@inheritdoc}
Inherited from Drupal\Core\Entity\EntityType
Defined in <ROOT>/core/lib/Drupal/Core/Entity/EntityType.php:663
→public getLinkTemplate($key)
{@inheritdoc}
Inherited from Drupal\Core\Entity\EntityType
Defined in <ROOT>/core/lib/Drupal/Core/Entity/EntityType.php:635
→public getLinkTemplates()
{@inheritdoc}
Inherited from Drupal\Core\Entity\EntityType
Defined in <ROOT>/core/lib/Drupal/Core/Entity/EntityType.php:628
→public getListBuilderClass()
{@inheritdoc}
Inherited from Drupal\Core\Entity\EntityType
Defined in <ROOT>/core/lib/Drupal/Core/Entity/EntityType.php:548
→public getListCacheContexts()
{@inheritdoc}
Inherited from Drupal\Core\Entity\EntityType
Defined in <ROOT>/core/lib/Drupal/Core/Entity/EntityType.php:851
→public getListCacheTags()
{@inheritdoc}
Inherited from Drupal\Core\Entity\EntityType
Defined in <ROOT>/core/lib/Drupal/Core/Entity/EntityType.php:858
→public getLowercaseLabel()
{@inheritdoc}
Inherited from Drupal\Core\Entity\EntityType
Defined in <ROOT>/core/lib/Drupal/Core/Entity/EntityType.php:771
→public getOriginalClass()
{@inheritdoc}
Inherited from Drupal\Core\Entity\EntityType
Defined in <ROOT>/core/lib/Drupal/Core/Entity/EntityType.php:419
→public getPermissionGranularity()
{@inheritdoc}
Inherited from Drupal\Core\Entity\EntityType
Defined in <ROOT>/core/lib/Drupal/Core/Entity/EntityType.php:621
→public getPluralLabel()
{@inheritdoc}
Inherited from Drupal\Core\Entity\EntityType
Defined in <ROOT>/core/lib/Drupal/Core/Entity/EntityType.php:800
→public getProvider()
{@inheritdoc}
Inherited from Drupal\Component\Plugin\Definition\PluginDefinition
Defined in <ROOT>/core/lib/Drupal/Component/Plugin/Definition/PluginDefinition.php:56
→public getRevisionDataTable()
{@inheritdoc}
Inherited from Drupal\Core\Entity\EntityType
Defined in <ROOT>/core/lib/Drupal/Core/Entity/EntityType.php:743
→public getRevisionMetadataKey($key)
{@inheritdoc}
Defined in <ROOT>/core/lib/Drupal/Core/Entity/ContentEntityType.php:109
{@inheritdoc}
Inherited from Drupal\Core\Entity\EntityType
Defined in <ROOT>/core/lib/Drupal/Core/Entity/EntityType.php:478
→public hasKey($key)
{@inheritdoc}
Inherited from Drupal\Core\Entity\EntityType
Defined in <ROOT>/core/lib/Drupal/Core/Entity/EntityType.php:411
→public hasLabelCallback()
{@inheritdoc}
Inherited from Drupal\Core\Entity\EntityType
Defined in <ROOT>/core/lib/Drupal/Core/Entity/EntityType.php:678
→public hasLinkTemplate($key)
{@inheritdoc}
Inherited from Drupal\Core\Entity\EntityType
Defined in <ROOT>/core/lib/Drupal/Core/Entity/EntityType.php:643
→public hasListBuilderClass()
{@inheritdoc}
Inherited from Drupal\Core\Entity\EntityType
Defined in <ROOT>/core/lib/Drupal/Core/Entity/EntityType.php:563
→public hasRevisionMetadataKey($key)
{@inheritdoc}
Defined in <ROOT>/core/lib/Drupal/Core/Entity/ContentEntityType.php:117
→public hasRouteProviders()
{@inheritdoc}
Inherited from Drupal\Core\Entity\EntityType
Defined in <ROOT>/core/lib/Drupal/Core/Entity/EntityType.php:541
→public hasViewBuilderClass()
{@inheritdoc}
Inherited from Drupal\Core\Entity\EntityType
Defined in <ROOT>/core/lib/Drupal/Core/Entity/EntityType.php:585
→public id()
{@inheritdoc}
Inherited from Drupal\Component\Plugin\Definition\PluginDefinition
Defined in <ROOT>/core/lib/Drupal/Component/Plugin/Definition/PluginDefinition.php:34
→public isCommonReferenceTarget()
{@inheritdoc}
Inherited from Drupal\Core\Entity\EntityType
Defined in <ROOT>/core/lib/Drupal/Core/Entity/EntityType.php:875
→public isInternal()
{@inheritdoc}
Inherited from Drupal\Core\Entity\EntityType
Defined in <ROOT>/core/lib/Drupal/Core/Entity/EntityType.php:368
→public isPersistentlyCacheable()
{@inheritdoc}
Inherited from Drupal\Core\Entity\EntityType
Defined in <ROOT>/core/lib/Drupal/Core/Entity/EntityType.php:389
→public isRenderCacheable()
{@inheritdoc}
Inherited from Drupal\Core\Entity\EntityType
Defined in <ROOT>/core/lib/Drupal/Core/Entity/EntityType.php:382
→public isRevisionable()
{@inheritdoc}
Inherited from Drupal\Core\Entity\EntityType
Defined in <ROOT>/core/lib/Drupal/Core/Entity/EntityType.php:735
→public isStaticallyCacheable()
{@inheritdoc}
Inherited from Drupal\Core\Entity\EntityType
Defined in <ROOT>/core/lib/Drupal/Core/Entity/EntityType.php:375
→public isSubclassOf($class)
{@inheritdoc}
Inherited from Drupal\Core\Entity\EntityType
Defined in <ROOT>/core/lib/Drupal/Core/Entity/EntityType.php:446
→public isTranslatable()
{@inheritdoc}
Inherited from Drupal\Core\Entity\EntityType
Defined in <ROOT>/core/lib/Drupal/Core/Entity/EntityType.php:728
→public set($property, $value)
{@inheritdoc}
Inherited from Drupal\Core\Entity\EntityType
Defined in <ROOT>/core/lib/Drupal/Core/Entity/EntityType.php:355
→public setAccessClass($class)
{@inheritdoc}
Inherited from Drupal\Core\Entity\EntityType
Defined in <ROOT>/core/lib/Drupal/Core/Entity/EntityType.php:606
→public setClass($class)
{@inheritdoc}
Inherited from Drupal\Core\Entity\EntityType
Defined in <ROOT>/core/lib/Drupal/Core/Entity/EntityType.php:426
→public setConstraints(array $constraints)
{@inheritdoc}
Inherited from Drupal\Core\Entity\EntityType
Defined in <ROOT>/core/lib/Drupal/Core/Entity/EntityType.php:889
→public setFormClass($operation, $class)
{@inheritdoc}
Inherited from Drupal\Core\Entity\EntityType
Defined in <ROOT>/core/lib/Drupal/Core/Entity/EntityType.php:526
→public setHandlerClass($handler_type, $value)
{@inheritdoc}
Inherited from Drupal\Core\Entity\EntityType
Defined in <ROOT>/core/lib/Drupal/Core/Entity/EntityType.php:470
→public setLabelCallback($callback)
{@inheritdoc}
Inherited from Drupal\Core\Entity\EntityType
Defined in <ROOT>/core/lib/Drupal/Core/Entity/EntityType.php:670
→public setLinkTemplate($key, $path)
{@inheritdoc}
Inherited from Drupal\Core\Entity\EntityType
Defined in <ROOT>/core/lib/Drupal/Core/Entity/EntityType.php:651
→public setListBuilderClass($class)
{@inheritdoc}
Inherited from Drupal\Core\Entity\EntityType
Defined in <ROOT>/core/lib/Drupal/Core/Entity/EntityType.php:555
→public setStorageClass($class)
{@inheritdoc}
Inherited from Drupal\Core\Entity\EntityType
Defined in <ROOT>/core/lib/Drupal/Core/Entity/EntityType.php:500
Sets the string translation service to use.
@param \Drupal\Core\StringTranslation\TranslationInterface $translation
The string translation service.
@return $this
Inherited from Drupal\Core\Entity\EntityType
Defined in <ROOT>/core/lib/Drupal/Core/StringTranslation/StringTranslationTrait.php:118
→public setUriCallback($callback)
{@inheritdoc}
Inherited from Drupal\Core\Entity\EntityType
Defined in <ROOT>/core/lib/Drupal/Core/Entity/EntityType.php:829
→public setViewBuilderClass($class)
{@inheritdoc}
Inherited from Drupal\Core\Entity\EntityType
Defined in <ROOT>/core/lib/Drupal/Core/Entity/EntityType.php:577
→public showRevisionUi()
{@inheritdoc}
Inherited from Drupal\Core\Entity\EntityType
Defined in <ROOT>/core/lib/Drupal/Core/Entity/EntityType.php:721
→protected checkStorageClass($class)
{@inheritdoc}
@throws \InvalidArgumentException
If the provided class does not implement
\Drupal\Core\Entity\ContentEntityStorageInterface.
@see \Drupal\Core\Entity\ContentEntityStorageInterface
Defined in <ROOT>/core/lib/Drupal/Core/Entity/ContentEntityType.php:75
Formats a string containing a count of items.
@see \Drupal\Core\StringTranslation\TranslationInterface::formatPlural()
Inherited from Drupal\Core\Entity\EntityType
Defined in <ROOT>/core/lib/Drupal/Core/StringTranslation/StringTranslationTrait.php:79
→protected getNumberOfPlurals($langcode = NULL)
Returns the number of plurals supported by a given language.
@see \Drupal\locale\PluralFormulaInterface::getNumberOfPlurals()
Inherited from Drupal\Core\Entity\EntityType
Defined in <ROOT>/core/lib/Drupal/Core/StringTranslation/StringTranslationTrait.php:88
Gets the string translation service.
@return \Drupal\Core\StringTranslation\TranslationInterface
The string translation service.
Inherited from Drupal\Core\Entity\EntityType
Defined in <ROOT>/core/lib/Drupal/Core/StringTranslation/StringTranslationTrait.php:102
Translates a string to the current language or to a given language.
See \Drupal\Core\StringTranslation\TranslatableMarkup::__construct() for
important security information and usage guidelines.
In order for strings to be localized, make them available in one of the
ways supported by the
@link https://www.drupal.org/node/322729 Localization API @endlink. When
possible, use the \Drupal\Core\StringTranslation\StringTranslationTrait
$this->t(). Otherwise create a new
\Drupal\Core\StringTranslation\TranslatableMarkup object.
@param string $string
A string containing the English text to translate.
@param array $args
(optional) An associative array of replacements to make after
translation. Based on the first character of the key, the value is
escaped and/or themed. See
\Drupal\Component\Render\FormattableMarkup::placeholderFormat() for
details.
@param array $options
(optional) An associative array of additional options, with the following
elements:
- 'langcode' (defaults to the current language): A language code, to
translate to a language other than what is used to display the page.
- 'context' (defaults to the empty context): The context the source
string belongs to. See the
@link i18n Internationalization topic @endlink for more information
about string contexts.
@return \Drupal\Core\StringTranslation\TranslatableMarkup
An object that, when cast to a string, returns the translated string.
@see \Drupal\Component\Render\FormattableMarkup::placeholderFormat()
@see \Drupal\Core\StringTranslation\TranslatableMarkup::__construct()
@ingroup sanitization
Inherited from Drupal\Core\Entity\EntityType
Defined in <ROOT>/core/lib/Drupal/Core/StringTranslation/StringTranslationTrait.php:70