20250806

help/class_desc/attributes/Check.md

@@ -0,0 +1,62 @@
+# Атрибут `Check`
+
+Атрибут `Check` предназначен для установки ограничений на добавляемые данные путём наложения проверок при внесении новой
+записи в базу данных. Это даёт возможность заранее определить, какое условие должно соблюдаться для того, чтобы новая
+запись была сохранена.
+
+## Основное назначение
+
+Атрибут позволяет задать дополнительное правило (условие), которое будет проверяться всякий раз, когда создаётся новая
+запись в базе данных. Таким образом, можно гарантировать соблюдение бизнес-правил и повысить целостность данных.
+
+## Пример использования атрибута
+
+Предположим, у вас есть модель данных, описывающая пользователей, и вы хотите убедиться, что каждое новое имя
+пользователя начинается с заглавной буквы:
+
+```php
+use goodboyalex\php_db_components_pack\attributes\Check;
+use goodboyalex\php_db_components_pack\attributes\FieldName;
+use goodboyalex\php_db_components_pack\classes\ConditionBuilder;
+
+final class User
+{
+    #[Check(new ConditionBuilder()->WhereEqual('FUNC:SUBSTR(name, 1, 1)', 'FUNC:UPPER(SUBSTR(name, 1, 1))
+    ')), FieldName('name')]
+    private string $Name;
+
+    private string $email;
+
+    //...
+}
+```
+
+В данном примере атрибут `#[Check]` применяется к полю `name`, и любое новое значение поля проходит проверку на то,
+что первая буква должна быть заглавной.
+
+## Пространство имён
+
+Атрибут объявлен в пространстве имён:
+
+```php
+namespace goodboyalex\php_db_components_pack\attributes;
+```
+
+## Версии и автор
+
+- **Автор**: Александр Бабаев
+- **Версия**: 1.0
+- **Дата выпуска**: с версии 1.0
+
+## Особенности
+
+- **Применяется только к полям (properties)** Атрибут используется исключительно для аннотирования полей классов,
+  которые соответствуют столбцам базы данных.
+
+## Когда использовать атрибут?
+
+Атрибут `Check` подходит для ситуаций, когда нужно обеспечить дополнительную защиту данных и ограничить ввод
+некорректных значений. Например, вы можете потребовать, чтобы пароль состоял минимум из восьми символов, или
+удостовериться, что введённый адрес электронной почты действительно валиден.
+
+[На главную](../../index.md)