NoSuspiciousCharacters
Warning: You are browsing the documentation for Symfony 6.3, which is no longer maintained.
Read the updated version of this page for Symfony 7.1 (the current stable version).
6.3
The NoSuspiciousCharacters
constraint was introduced in Symfony 6.3.
Validates that the given string does not contain characters used in spoofing security attacks, such as invisible characters such as zero-width spaces or characters that are visually similar.
"symfony.com" and "ѕymfony.com" look similar, but their first letter is different (in the second string, the "s" is actually a cyrillic small letter dze). This can make a user think they'll navigate to Symfony's website, whereas it would be somewhere else.
This is a kind of spoofing attack (called "IDN homograph attack"). It tries to identify something as something else to exploit the resulting confusion. This is why it is recommended to check user-submitted, public-facing identifiers for suspicious characters in order to prevent such attacks.
Because Unicode contains such a large number of characters and incorporates the varied writing systems of the world, incorrect usage can expose programs or systems to possible security attacks.
That's why this constraint ensures strings or Stringables do not include any suspicious characters. As it leverages PHP's Spoofchecker, the intl extension must be enabled to use it.
Applies to | property or method |
Class | NoSuspiciousCharacters |
Validator | NoSuspiciousCharactersValidator |
Basic Usage
The following constraint will use different detection mechanisms to ensure that the username is not spoofed:
1 2 3 4 5 6 7 8 9 10
// src/Entity/User.php
namespace App\Entity;
use Symfony\Component\Validator\Constraints as Assert;
class User
{
#[Assert\NoSuspiciousCharacters]
private string $username;
}
1 2 3 4 5
# config/validator/validation.yaml
App\Entity\User:
properties:
username:
- NoSuspiciousCharacters: ~
1 2 3 4 5 6 7 8 9 10 11 12
<!-- config/validator/validation.xml -->
<?xml version="1.0" encoding="UTF-8" ?>
<constraint-mapping xmlns="http://symfony.com/schema/dic/constraint-mapping"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://symfony.com/schema/dic/constraint-mapping https://symfony.com/schema/dic/constraint-mapping/constraint-mapping-1.0.xsd">
<class name="App\Entity\User">
<property name="username">
<constraint name="NoSuspiciousCharacters"/>
</property>
</class>
</constraint-mapping>
1 2 3 4 5 6 7 8 9 10 11 12 13
// src/Entity/User.php
namespace App\Entity;
use Symfony\Component\Validator\Constraints as Assert;
use Symfony\Component\Validator\Mapping\ClassMetadata;
class User
{
public static function loadValidatorMetadata(ClassMetadata $metadata)
{
$metadata->addPropertyConstraint('username', new Assert\NoSuspiciousCharacters());
}
}
Note
As with most of the other constraints, null
and empty strings are
considered valid values. This is to allow them to be optional values.
If the value is mandatory, a common solution is to combine this constraint
with NotBlank.
Options
checks
type: integer
default: all
This option is a bitmask of the checks you want to perform on the string:
NoSuspiciousCharacters::CHECK_INVISIBLE
checks for the presence of invisible characters such as zero-width spaces, or character sequences that are likely not to display, such as multiple occurrences of the same non-spacing mark.NoSuspiciousCharacters::CHECK_MIXED_NUMBERS
(usable with ICU 58 or higher) checks for numbers from different numbering systems.NoSuspiciousCharacters::CHECK_HIDDEN_OVERLAY
(usable with ICU 62 or higher) checks for combining characters hidden in their preceding one.
You can also configure additional requirements using locales and restrictionLevel.
locales
type: array
default: framework.enabled_locales
Restrict the string's characters to those normally used with the associated languages.
For example, the character "π" would be considered suspicious if you restricted the locale to "English", because the Greek script is not associated with it.
Passing an empty array, or configuring restrictionLevel to
NoSuspiciousCharacters::RESTRICTION_LEVEL_NONE
will disable this requirement.
restrictionLevel
type: integer
default: NoSuspiciousCharacters::RESTRICTION_LEVEL_MODERATE
on ICU >= 58, otherwise NoSuspiciousCharacters::RESTRICTION_LEVEL_SINGLE_SCRIPT
Configures the set of acceptable characters for the validated string through a specified "level":
NoSuspiciousCharacters::RESTRICTION_LEVEL_MINIMAL
requires the string's characters to match the configured locales'.NoSuspiciousCharacters::RESTRICTION_LEVEL_MODERATE
also requires the string to be covered by Latin and any one other Recommended or Limited Use script, except Cyrillic, Greek, and Cherokee.NoSuspiciousCharacters::RESTRICTION_LEVEL_HIGH
(usable with ICU 58 or higher) also requires the string to be covered by any of the following sets of scripts:- Latin + Han + Bopomofo (or equivalently: Latn + Hanb)
- Latin + Han + Hiragana + Katakana (or equivalently: Latn + Jpan)
- Latin + Han + Hangul (or equivalently: Latn + Kore)
NoSuspiciousCharacters::RESTRICTION_LEVEL_SINGLE_SCRIPT
also requires the string to be single-script.NoSuspiciousCharacters::RESTRICTION_LEVEL_ASCII
(usable with ICU 58 or higher) also requires the string's characters to be in the ASCII range.
You can accept all characters by setting this option to
NoSuspiciousCharacters::RESTRICTION_LEVEL_NONE
.
groups
type: array
| string
default: null
It defines the validation group or groups of this constraint. Read more about validation groups.
payload
type: mixed
default: null
This option can be used to attach arbitrary domain-specific data to a constraint. The configured payload is not used by the Validator component, but its processing is completely up to you.
For example, you may want to use several error levels to present failed constraints differently in the front-end depending on the severity of the error.