Rules

Rules neboli pravidla slouží k validaci dat při ukládání přes API a přes formuláře v datagridu.

Příklad využití rules

Předpokládejme, že chceme vytvořit nový článek. Článek má pět atributů: title, content, slug, source_url a authorName Atribut title je povinný, content musí mít minimálně 10 znaků, slug musí být unikátní a ve formátu [a-z0-9-], source_url musí být validní URL a authorName může být null nebo string.

Demonstraci si provedeme na PureField, který neobsahuje žádná přednastavená pravidla, formátery ani serializéry.

public function create(WriteBuilder $builder, CollectionRequest $request): WriteBuilder
{
    return $builder
        ->add(new PureField(
            key: 'title',
            name: 'Titulek',
            rules: [
                new StringRule(),
                new RequiredRule()
            ]
        ))
        ->add(new PureField(
            key: 'content',
            name: 'Obsah',
            rules: [
                new StringRule(), 
                new MinRule(10)
            ]
        ))
        ->add(new PureField(
            key: 'slug',
            name: 'Slug',
            rules: [
                new RegexRule(
                    pattern: '/^[a-z0-9]+(-[a-z0-9]+)*$/',
                    message: 'Slug musí obsahovat pouze malá písmena, číslice a pomlčku.'
                ),
                // Namísto regexu lze rovnou použít
                // new SlugRule(),
                new UniqueRule(
                    targetEntity: Article::class,
                    columnName: 'slug',
                    message: 'Tento slug je již použit.'
                ),
            ]
        ))
        ->add(new PureField(
            key: 'source_url',
            name: 'Zdrojová URL',
            rules: [
                new UrlRule()
            ]
        ))
        ->add(new PureField(
            key: 'authorName',
            name: 'Autor',
            rules: [
                new StringRule()
                new NullableRule(), 
            ]
        ))
    ;
}

Přehled pravidel

	Rule (název třídy)	Popis	Parametry
1	AnyOfRule	Ověří, zda hodnota patří do pole povolených hodnot.	array $keys ?string $message
2	ArrayRule	Ověří, zda hodnota je array.	?string $message
3	BooleanRule	Ověří, zda hodnota je boolean.	?string $message
4	CallableRule	Umožňuje definovat vlastní callback funkci pro validaci hodnoty.	callable $callback ?string $message
5	DateCzRule	Ověří, zda je hodnota ve formátu j.n.Y.	?string $message
6	DateRule	Ověří, zda je hodnota ve formátu Y-m-d.	?string $message
7	DateTimeCzRule	Ověří, zda je hodnota ve formátu j.n.Y H:i:s.	?string $message
8	DateTimeIntervalRule	Ověří, zda je hodnota ve formátu Y-m-d H:i:s Y-m-d H:i:s.	?string $message
9	DateTimeRule	Ověří, zda je hodnota ve formátu Y-m-d H:i:s.	?string $message
10	DateTimeZoneRule	Ověří, zda se jedná o array{datetime: Y-m-d H:i:s, zone: Zone/Name}.	?string $message
11	DecimalRule	Ověří, zda je hodnota desetinné číslo.	?string $message
12	EmailRule	Ověří, zda je hodnota validní e-mailová adresa.	?string $message
13	EqualRule	Ověří, zda je hodnota shodná s hodnotu v jiném fieldu.	string $targetField ?string $message
14	HourMinuteCzRule	Ověří, zda je hodnota ve formátu G:i.	?string $message
15	HourMinuteRule	Ověří, zda je hodnota ve formátu H:i.	?string $message
16	IntegerRule	Ověří, zda je hodnota celé číslo.	?string $message
17	JsonRule	Ověří, zda je hodnota validní JSON. Parametr $schema umožňuje definici validačního schéma viz ukázka zde.	?Schema $schema ?string $message
18	JsonStringRule	Ověří, zda je hodnota validní JSON string. Parametr $schema umožňuje definici validačního schéma viz ukázka zde.	?Schema $schema ?string $message
19	MaxRule	V případě array ověří, zda array nepřesahuje maximální počet prvků. V případě stringu ověří, zda string nepřesahuje maximální délku. V případě čísla ověří, zda číslo nepřesahuje maximum.	int $max ?string $message
20	MinRule	V případě array ověří, zda array obsahuje alespoň minimální počet prvků. V případě stringu ověří, zda string není kratší než minimální délka. V případě čísla ověří, zda číslo není menší mež minimum.	int $min ?string $message
21	NullableRule	Povolí hodnotu null.
22	NumericRule	Ověří, zda je hodnota celé nebo desetinné číslo.	?string $message
23	PhoneCzRule	Ověří, zda je hodnota validní české telefonní číslo. Po validaci se (by default) provede i normalizace hodnoty.	bool $normalize ?string $message
24	RegexRule	Ověří, zda hodnota splňuje regulární výraz.	string $expression ?string $message
25	RequiredRule	Ověří, zda je pole vyplněno.	?string $message
26	SlugRule	Ověří, zda je hodnota validní slug /^[a-z0-9]+(-[a-z0-9]+)*$/.	?string $message
27	StringRule	Ověří, zda je hodnota řetězec.	?string $message
28	TimeCzRule	Ověří, zda je hodnota ve formátu G:i:s.	?string $message
29	TimeRule	Ověří, zda je hodnota ve formátu H:i:s.	?string $message
30	UniqueRule	Ověří, zda je hodnota unikátní v databázi.	string $targetEntity string $columnName string $primaryKey ?string $message
31	UrlRule	Ověří, zda je hodnota validní URL.	?string $message
32	VideoLinkRule	Ověří, zda je hodnota validní odkaz na Youtube nebo Vimeo video. Po validaci se (by default) provede i normalizace hodnoty.	bool $normalize ?string $message

Vlastní pravidlo

Pokud potřebujete ovlivnit validaci nějakých hodnot jiným způsobem než nabízí výše uvedená pravidla, můžete si vytvořit vlastní pravidlo.

Vytvoření pravidla

Stačí přidat novou třídu, která podědí BaseRule a implementuje metodu validate().

app/Collection/Rule/MyCustomRule.php

class MyCustomRule extends BaseRule
{
    /**
     * @param class-string $targetEntity
     */
    public function __construct(
        protected string  $targetEntity,
        protected string  $columnName,
        protected string  $primaryKey = 'id',
        protected ?string $message = null
    )
    {
        parent::__construct($message);
    }
    
    public function message(): string
    {
        return $this->message ?: "Value must be unique";
    }
    
    /**
     * Return true if validation is passed
     * @return bool
     * @throws \Doctrine\ORM\NonUniqueResultException
     * @throws \Megio\Collection\Exception\InvalidArgumentException
     */
    public function validate(): bool
    {
        $value = $this->getValue();
        
        if (!is_string($value) && !is_numeric($value) && !is_bool($value)) {
            return false;
        }
        
        $repo = $this->getEntityManager()->getRepository($this->targetEntity);
        
        $row = $repo->createQueryBuilder('e')
            ->select('e')
            ->where("e.{$this->columnName} = :value")
            ->setParameter('value', $this->getValue())
            ->getQuery()
            ->getOneOrNullResult(AbstractQuery::HYDRATE_ARRAY);
        
        if ($row === null) {
            return true;
        }
        
        if (!array_key_exists($this->primaryKey, $row)) {
            throw new InvalidArgumentException(
                "Property '{$this->primaryKey}' not found in entity '{$this->targetEntity}'"
            );
        }
        
        if (
            $row
            && $row[$this->columnName] === $this->getValue()
            && $row[$this->primaryKey] === $this->getBuilder()->getRowId()
        ) {
            return true;
        }
        
        return false;
    }
}

Povinné parametry konstruktoru

Jediným povinným parametrem je message, který určuje, jaká chybová zpráva se má zobrazit, pokud hodnota neprojde validací.