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

20250807

Browse Source
This commit is contained in:
Александр Бабаев
2025-08-07 18:06:55 +03:00
parent eeea57209e
commit d132832d28
34 changed files with 1231 additions and 286 deletions
Download Patch File Download Diff File Expand all files Collapse all files

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

@@ -0,0 +1,58 @@
# Атрибут `DefaultValue`
Атрибут `DefaultValue` предназначен для указания значения по умолчанию, которое будет использоваться для поля при
отсутствии явно заданного значения. Он помогает поддерживать целостность данных и избегать неопределенности, возникающей
при наличии необязательных полей.
## Основное назначение
Атрибут используется для явного указания значения, которое будет применяться к полю модели данных, если пользователь или
программа не указали собственное значение. Это особенно полезно для тех случаев, когда данные нужны обязательно, но
вводить их необязательно или сложно.
## Пример использования атрибута
Допустим, у вас есть модель данных, описывающая пользователя, и вы хотите назначить статус "активирован" по умолчанию
каждому новому пользователю:
```php
use goodboyalex\php_db_components_pack\attributes\DefaultValue;
final class User
{
#[DefaultValue(true)]
private bool $Active;
// Остальные поля и геттеры/сеттеры...
}
```
В данном примере атрибут `#[DefaultValue]` применяется к полю `$Active`, устанавливая значение по умолчанию равным
`true`.
## Пространство имён
Атрибут объявлен в пространстве имён:
```php
namespace goodboyalex\php_db_components_pack\attributes;
```
## Версии и автор
- **Автор**: Александр Бабаев
- **Версия**: 1.0
- **Дата выпуска**: с версии 1.0
## Особенности
- **Применяется только к полям (properties)**
Атрибут используется исключительно для аннотирования полей классов, которые соответствуют столбцам базы данных.
## Когда использовать атрибут?
Атрибут `DefaultValue` отлично подходит для ситуаций, когда требуется автоматически заполнить поле некоторым значением,
если оно не установлено явно. Например, можно назначать дефолтные роли пользователям, указывать исходные статусы заказов
или временные отметки по умолчанию.
[На главную](../../index.md)

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

@@ -1,37 +0,0 @@
<?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;
}
}

57
help/class_desc/attributes/FieldName.md Normal file
View File

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

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

@@ -1,37 +0,0 @@
<?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;
}
}

55
help/class_desc/attributes/ForeignKey.md Normal file
View File

@@ -0,0 +1,55 @@
# Атрибут `ForeignKey`
Атрибут `ForeignKey` предназначен для указания внешних связей (foreign keys) между полями модели и другими таблицами в
базе данных. Он позволяет явно задать отношения между сущностями и улучшить навигацию по связанным данным.
## Основное назначение
Атрибут используется для явного указания внешнего ключа, который связывает одно поле модели с полем в другой таблице
базы данных. Это особенно полезно, когда необходимо показать отношение "один ко многим" или "многие ко многим".
## Пример использования атрибута
Допустим, у вас есть модель данных, описывающая продукты, и вы хотите указать внешнюю связь с таблицей категорий
продуктов:
```php
use goodboyalex\php_db_components_pack\attributes\ForeignKey;
final class Product
{
#[ForeignKey(table: 'categories', fieldName: 'category_id')]
private int $CategoryId;
// Остальные поля и геттеры/сеттеры...
}
```
В данном примере атрибут `#[ForeignKey]` применяется к полю `$CategoryId`, явно указывая, что оно связано с полем
`category_id` в таблице `categories`.
## Пространство имён
Атрибут объявлен в пространстве имён:
```php
namespace goodboyalex\php_db_components_pack\attributes;
```
## Версии и автор
- **Автор**: Александр Бабаев
- **Версия**: 1.0
- **Дата выпуска**: с версии 1.0
## Особенности
- **Применяется только к полям (properties)** Атрибут используется исключительно для аннотирования полей классов,
которые соответствуют внешним ключам базы данных.
## Когда использовать атрибут?
Атрибут `ForeignKey` полезен, когда необходимо указать внешние связи между двумя таблицами базы данных. Он помогает
строить полноценные графы отношений и упростить навигацию по данным.
[На главную](../../index.md)

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

@@ -1,44 +0,0 @@
<?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;
}
}

75
help/class_desc/attributes/IgnoredInDB.md Normal file
View File

@@ -0,0 +1,75 @@
# Атрибут `IgnoredInDB`
Атрибут `IgnoredInDB` предназначен для указания, что определенное свойство модели данных должно игнорироваться при
выполнении определенных операций с базой данных. Это позволяет исключить поля из операций вставки, обновления, чтения и
других действий, что может быть полезно для оптимизации производительности или соблюдения особых правил доступа к
данным.
## Основное назначение
Атрибут используется для того, чтобы обозначить, какие операции с базой данных не должны затрагивать конкретное поле
модели. Например, вы можете захотеть исключить временную отметку создания записи из операций обновления, так как она
должна оставаться постоянной.
## Пример использования атрибута
Допустим, у вас есть модель данных, описывающая заказ, и вы хотите, чтобы поле с временной отметкой создания заказа не
обновлялось после первого внесения:
```php
use goodboyalex\php_db_components_pack\attributes\IgnoredInDB;
use goodboyalex\php_db_components_pack\enums\DBOperation;
final class Order
{
#[IgnoredInDB(DBOperation::Update)]
private DateTimeImmutable $CreatedAt;
// Остальные поля и геттеры/сеттеры...
}
```
В данном примере атрибут `#[IgnoredInDB]` применяется к полю `$CreatedAt`, явно указывая, что оно должно игнорироваться
при операции обновления.
**ВАЖНО!** Если атрибут задан, но не заданы операции:
```php
use goodboyalex\php_db_components_pack\attributes\IgnoredInDB;
use goodboyalex\php_db_components_pack\enums\DBOperation;
final class Order
{
#[IgnoredInDB]
private DateTimeImmutable $CreatedAt;
// Остальные поля и геттеры/сеттеры...
}
```
В этом случае атрибут будет **проигнорирован во ВСЕХ операциях**.
## Пространство имён
Атрибут объявлен в пространстве имён:
```php
namespace goodboyalex\php_db_components_pack\attributes;
```
## Версии и автор
- **Автор**: Александр Бабаев
- **Версия**: 1.0
- **Дата выпуска**: с версии 1.0
## Особенности
- **Применяется только к полям (properties)** Атрибут используется исключительно для аннотирования полей классов, которые соответствуют столбцам базы данных.
## Когда использовать атрибут?
Атрибут `IgnoredInDB` полезен, когда необходимо исключить поле из некоторых операций с базой данных. Например, это может
потребоваться для защиты временных отметок, исключения виртуальных полей или улучшения производительности запросов.
[На главную](../../index.md)

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

@@ -1,47 +0,0 @@
<?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);
}
}

55
help/class_desc/attributes/NotNull.md Normal file
View File

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

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

@@ -1,30 +0,0 @@
<?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 ()
{
}
}

55
help/class_desc/attributes/PrimaryKey.md Normal file
View File

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

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

@@ -1,29 +0,0 @@
<?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 ()
{
}
}

57
help/class_desc/attributes/Unique.md Normal file
View File

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

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

@@ -1,30 +0,0 @@
<?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 ()
{
}
}