babaev-an/php_db_components_pack
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases 3 Wiki Activity

20250806

Browse Source
This commit is contained in:
Александр Бабаев
2025-08-06 18:10:04 +03:00
parent 7b42ba781c
commit eeea57209e
19 changed files with 636 additions and 16 deletions
Download Patch File Download Diff File Expand all files Collapse all files

63
help/class_desc/attributes/AutoIncrement.md Normal file
View File

@@ -0,0 +1,63 @@
# Атрибут `AutoIncrement`
Атрибут `AutoIncrement` используется для пометки полей в моделях данных, которые будут автоматически заполняться
уникальным значением при каждом новом сохранении записи. Обычно он применяется для идентификации уникальных записей,
таких как первичные ключи.
## Основное назначение
Этот атрибут необходим для того, чтобы отметить поля, значения которых не задаются вручную, а генерируются автоматически
самой базой данных при вставке нового элемента. Например, если поле объявлено как автоинкрементируемое (AUTO_INCREMENT в
MySQL, SERIAL в PostgreSQL), то именно этот атрибут поможет разработчику ясно выразить намерение, что такое поле само
получает уникальный идентификатор.
## Пример использования атрибута
Предположим, у вас есть простая модель данных, описывающая пользователей, где каждое поле соответствует столбцу в базе
данных:
```php
use goodboyalex\php_db_components_pack\attributes\AutoIncrement;
final class User
{
#[AutoIncrement]
private int $Id;
private string $Name;
private string $Email;
// ...
}
```
Здесь атрибут `#[AutoIncrement]` указывает, что поле `$Id` будет автоматически получать уникальные значения при создании
новых записей.
## Пространство имён
Атрибут объявлен в пространстве имён:
```php
namespace goodboyalex\php_db_components_pack\attributes;
```
### Версии и автор
- **Автор**: Александр Бабаев
- **Версия**: 1.0
- **Дата выпуска**: с версии 1.0
### Особенности
- **Только для свойств (fields)**
Атрибут применим исключительно к свойствам классов, которые представляют собой поля базы данных.
### Когда использовать атрибут?
Атрибут `AutoIncrement` рекомендуется использовать в случаях, когда важно подчеркнуть автоматическое поведение поля при
вставке новых записей в базу данных. Особенно это актуально для идентификационных полей, таких как первичные ключи, где
обеспечение уникальности критично для целостности данных.
[На главную](../../index.md)

62
help/class_desc/attributes/Check.md Normal file
View File

@@ -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)

58
help/class_desc/attributes/Compare.md Normal file
View File

@@ -0,0 +1,58 @@
# Атрибут `Compare`
Атрибут `Compare` предназначен для задания специальных процедур сравнения значений поля при работе с базой данных. Он
позволяет реализовать кастомные механизмы сравнения, отличающиеся от стандартного равенства, что бывает крайне полезно
при сложной логике работы с данными.
## Основное назначение
Атрибут позволяет указать собственный метод сравнения значений, применяемый к определенному полю в базе данных.
Например, это может понадобиться, если простое сравнение двух значений недостаточно точно отражает вашу бизнес-логику (
например, если нужно сравнивать значения с учётом округления или игнорируя регистр букв).
## Пример использования атрибута
Допустим, у вас есть модель данных, включающая поле, содержащее имя пользователя, и вы хотите сравнить имена независимо
от регистра:
```php
use goodboyalex\php_db_components_pack\attributes\Compare;
final class User
{
#[Compare(fn($left, $right) => strcasecmp($left, $right))]
private string $Name;
// Остальные поля и геттеры/сеттеры...
}
```
В данном примере атрибут `#[Compare]` применяется к полю `$Name`, и указанное замыкание (closure) реализует
сравнение строк без учёта регистра.
## Пространство имён
Атрибут объявлен в пространстве имён:
```php
namespace goodboyalex\php_db_components_pack\attributes;
```
### Версии и автор
- **Автор**: Александр Бабаев
- **Версия**: 1.0
- **Дата выпуска**: с версии 1.0
## Особенности
- **Применяется только к полям (properties)**
Атрибут используется исключительно для аннотирования полей классов, которые соответствуют столбцам базы данных.
## Когда использовать атрибут?
Атрибут `Compare` идеально подойдёт, когда вам необходимо установить особое правило сравнения значений. Например, если
требуется учесть особенности сортировки, учета регистров или даже допустимые погрешности при сравнении числовых
значений.
[На главную](../../index.md)

63
help/class_desc/attributes/ConvertToDB.md Normal file
View File

@@ -0,0 +1,63 @@
# Атрибут `ConvertToDB`
Атрибут `ConvertToDB` предназначен для настройки процесса преобразования значений при взаимодействии с базой данных. Он
позволяет задать специальные методы для преобразования данных между внутренним представлением и формой, подходящей для
сохранения в базе данных.
## Основное назначение
Атрибут позволяет настроить индивидуальные процедуры для преобразования данных, поступающих из базы данных и обратно.
Часто бывает необходимо изменять формат данных при передаче их между слоями приложения и хранилищем, например,
преобразовать JSON в объект или нормализовать строку для хранения в определенном формате.
## Пример использования атрибута
Допустим, у вас есть модель данных, содержащая поле, которое хранит метаданные в формате JSON, и вы хотите, чтобы это
поле было сериализовано в JSON при сохранении в базу данных и десериализовано обратно при извлечении:
```php
use goodboyalex\php_db_components_pack\attributes\ConvertToDB;
use goodboyalex\php_db_components_pack\attributes\DataType;
use goodboyalex\php_db_components_pack\enums\DBType;
final class Product
{
#[ConvertToDB(
fromType: fn($val) => json_decode($val, true),
toType: fn($val) => json_encode($val)
), DataType(DBType::STRING)]
public array $MetaData;
// Другие поля и геттеры/сеттеры...
}
```
В данном примере атрибут `#[ConvertToDB]` применяется к полю `$MetaData`, и два заданных замыкания определяют порядок
преобразования данных при чтении и записи.
## Пространство имён
Атрибут объявлен в пространстве имён:
```php
namespace goodboyalex\php_db_components_pack\attributes;
```
## Версии и автор
- **Автор**: Александр Бабаев
- **Версия**: 1.0
- **Дата выпуска**: с версии 1.0
## Особенности
- **Применяется только к полям (properties)**
Атрибут используется исключительно для аннотирования полей классов, которые соответствуют столбцам базы данных.
## Когда использовать атрибут?
Атрибут `ConvertToDB` пригодится, когда возникает необходимость нестандартного преобразования данных. Например, если вы
работаете с JSON-данными, XML-документами или бинарными изображениями, и нужно аккуратно сохранять и извлекать эти
данные из базы данных.
[На главную](../../index.md)

59
help/class_desc/attributes/DataType.md Normal file
View File

@@ -0,0 +1,59 @@
# Атрибут `DataType`
Атрибут `DataType` предназначен для указания типа данных и размера поля, используемого в базе данных. Он позволяет чётко
определять, какой тип данных хранится в конкретном поле и каким образом он представлен в базе данных.
## Основное назначение
Атрибут используется для явного указания типа данных, хранимых в соответствующем поле модели данных. Это важно, потому
что разные базы данных поддерживают различные типы данных, и важно обеспечить точное соответствие между моделью данных и
физической схемой базы данных.
## Пример использования атрибута
Допустим, у вас есть модель данных, описывающая товары, и вы хотите указать, что цена товара представлена числом с
плавающей точкой, а название товара ограничено длиной в 100 символов:
```php
use goodboyalex\php_db_components_pack\attributes\DataType;
use goodboyalex\php_db_components_pack\enums\DBType;
final class Product
{
#[DataType(DBType::FLOAT)]
private float $Price;
#[DataType(DBType::STRING, size: 100)]
private string $Title;
// Остальные поля и геттеры/сеттеры...
}
```
В данном примере атрибут `#[DataType]` применяется к двум полям: одному для цены и другому для заголовка продукта.
## Пространство имён
Атрибут объявлен в пространстве имён:
```php
namespace goodboyalex\php_db_components_pack\attributes;
```
## Версия и автор
- **Автор**: Александр Бабаев
- **Версия**: 1.0
- **Дата выпуска**: с версии 1.0
## Особенности
- **Применяется только к полям (properties)**
Атрибут используется исключительно для аннотирования полей классов, которые соответствуют столбцам базы данных.
## Когда использовать атрибут?
Атрибут `DataType` идеален, когда вам нужно явно указать тип данных, который сохраняется в поле базы данных. Это может
быть особенно полезно при миграции данных или проверке соответствия схемы базы данных вашим моделям.
[На главную](../../index.md)

37
help/class_desc/attributes/DefaultValue.php Normal file
View File

@@ -0,0 +1,37 @@
<?php
/**
* Отключаю несущественные инспекции (из-за Attribute)
*
* @noinspection PhpMultipleClassDeclarationsInspection
*/
namespace goodboyalex\php_db_components_pack\attributes;
use Attribute;
/**
* Атрибут указывающий значение по умолчанию для столбца.
*
* @author Александр Бабаев
* @package php_db_components_pack
* @version 1.0
* @since 1.0
*/
#[Attribute(flags: Attribute::TARGET_PROPERTY)]
final readonly class DefaultValue
{
/**
* @var mixed $Value Значение по умолчанию.
*/
public mixed $Value;
/**
* Конструктор.
*
* @param mixed $value Значение по умолчанию.
*/
public function __construct (mixed $value)
{
$this->Value = $value;
}
}

37
help/class_desc/attributes/FieldName.php Normal file
View File

@@ -0,0 +1,37 @@
<?php
/**
* Отключаю несущественные инспекции (из-за Attribute)
*
* @noinspection PhpMultipleClassDeclarationsInspection
*/
namespace goodboyalex\php_db_components_pack\attributes;
use Attribute;
/**
* Атрибут указывающий имя поля в БД.
*
* @author Александр Бабаев
* @package php_db_components_pack
* @version 1.0
* @since 1.0
*/
#[Attribute(flags: Attribute::TARGET_PROPERTY)]
final readonly class FieldName
{
/**
* @var string $FieldName Имя поля.
*/
public string $FieldName;
/**
* Конструктор.
*
* @param string $fieldName Имя поля.
*/
public function __construct (string $fieldName)
{
$this->FieldName = $fieldName;
}
}

44
help/class_desc/attributes/ForeignKey.php Normal file
View File

@@ -0,0 +1,44 @@
<?php
/**
* Отключаю несущественные инспекции (из-за Attribute)
*
* @noinspection PhpMultipleClassDeclarationsInspection
*/
namespace goodboyalex\php_db_components_pack\attributes;
use Attribute;
/**
* Атрибут указывающий имя поля в БД.
*
* @author Александр Бабаев
* @package php_db_components_pack
* @version 1.0
* @since 1.0
*/
#[Attribute(flags: Attribute::TARGET_PROPERTY)]
final readonly class ForeignKey
{
/**
* @var string $TableName Имя таблицы.
*/
public string $TableName;
/**
* @var string $FieldName Имя связываемого поля.
*/
public string $FieldName;
/**
* Конструктор.
*
* @param string $table Имя таблицы.
* @param string $fieldName Имя связываемого поля.
*/
public function __construct (string $table, string $fieldName)
{
$this->TableName = $table;
$this->FieldName = $fieldName;
}
}

47
help/class_desc/attributes/IgnoredInDB.php Normal file
View File

@@ -0,0 +1,47 @@
<?php
/**
* Отключаю несущественные инспекции (из-за Attribute)
*
* @noinspection PhpMultipleClassDeclarationsInspection
*/
namespace goodboyalex\php_db_components_pack\attributes;
use Attribute;
use goodboyalex\php_components_pack\classes\ObjectArray;
use goodboyalex\php_db_components_pack\enums\DBOperation;
/**
* Атрибут указывающий, что свойство должно игнорироваться при операции с БД.
*
* @author Александр Бабаев
* @package php_db_components_pack
* @version 1.0
* @since 1.0
*/
#[Attribute(flags: Attribute::TARGET_PROPERTY)]
final readonly class IgnoredInDB
{
/**
* @var ObjectArray Игнорируемые операции.
*/
public ObjectArray $IgnoredOperations;
/**
* Конструктор.
*
* @param DBOperation ...$ignoredOperations Список операций, которые игнорируем.
*/
public function __construct (DBOperation ...$ignoredOperations)
{
// Если не указаны операции
if (count($ignoredOperations) === 0)
// - то по умолчанию игнорируем все операции
$ignoredOperations = [
DBOperation::Insert, DBOperation::Get, DBOperation::Update, DBOperation::Delete, DBOperation::Count
];
// Инициализируем массив
$this->IgnoredOperations = new ObjectArray($ignoredOperations);
}
}

30
help/class_desc/attributes/NotNull.php Normal file
View File

@@ -0,0 +1,30 @@
<?php
/**
* Отключаю несущественные инспекции (из-за Attribute)
*
* @noinspection PhpMultipleClassDeclarationsInspection
*/
namespace goodboyalex\php_db_components_pack\attributes;
use Attribute;
/**
* Атрибут указывает, что на данное поле действует ограничение, которое запрещает вставлять пустые (NULL) значения
* в указанное поле.
*
* @author Александр Бабаев
* @package php_db_components_pack
* @version 1.0
* @since 1.0
*/
#[Attribute(flags: Attribute::TARGET_PROPERTY)]
final readonly class NotNull
{
/**
* Конструктор
*/
public function __construct ()
{
}
}

29
help/class_desc/attributes/PrimaryKey.php Normal file
View File

@@ -0,0 +1,29 @@
<?php
/**
* Отключаю несущественные инспекции (из-за Attribute)
*
* @noinspection PhpMultipleClassDeclarationsInspection
*/
namespace goodboyalex\php_db_components_pack\attributes;
use Attribute;
/**
* Атрибут указания, что параметр является первичным ключом таблицы.
*
* @author Александр Бабаев
* @package php_db_components_pack
* @version 1.0
* @since 1.0
*/
#[Attribute(flags: Attribute::TARGET_PROPERTY)]
final readonly class PrimaryKey
{
/**
* Конструктор
*/
public function __construct ()
{
}
}

30
help/class_desc/attributes/Unique.php Normal file
View File

@@ -0,0 +1,30 @@
<?php
/**
* Отключаю несущественные инспекции (из-за Attribute)
*
* @noinspection PhpMultipleClassDeclarationsInspection
*/
namespace goodboyalex\php_db_components_pack\attributes;
use Attribute;
/**
* Атрибут обеспечивает уникальность каждого значения в данном поле. Обычно применяется для уникальных
* идентификационных номеров или адресов электронной почты.
*
* @author Александр Бабаев
* @package php_db_components_pack
* @version 1.0
* @since 1.0
*/
#[Attribute(flags: Attribute::TARGET_PROPERTY)]
final readonly class Unique
{
/**
* Конструктор
*/
public function __construct ()
{
}
}

2
help/class_desc/enums/DBDriver.md
View File

@@ -58,4 +58,4 @@ if ($dbType === DBDriver::MySQL)
Этот класс является частью библиотеки `goodboyalex/php_db_components_pack` и предназначен для унификации работы с
различными системами управления базами данных посредством стандартного интерфейса PDO.
[На гравную](../../index.md)
[На главную](../../index.md)

2
help/class_desc/enums/DBOperation.md
View File

@@ -79,4 +79,4 @@ switch ($operation) {
Этот класс является частью библиотеки `goodboyalex/php_db_components_pack` и предназначен для унификации работы с
различными системами управления базами данных посредством стандартного интерфейса PDO.
[На гравную](../../index.md)
[На главную](../../index.md)

2
help/class_desc/enums/DBType.md
View File

@@ -74,4 +74,4 @@ echo "Эквивалентный SQL-тип: $sqlType"; // Output: VARCHAR
Этот класс является частью библиотеки `goodboyalex/php_db_components_pack` и предназначен для унификации работы с
различными системами управления базами данных посредством стандартного интерфейса PDO.
[На гравную](../../index.md)
[На главную](../../index.md)