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.2 (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.

This work, including the code samples, is licensed under a Creative Commons BY-SA 3.0 license.

TOC

Version