20250807
This commit is contained in:
parent
eeea57209e
commit
d132832d28
58
help/class_desc/attributes/DefaultValue.md
Normal file
58
help/class_desc/attributes/DefaultValue.md
Normal 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)
|
||||
@ -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
57
help/class_desc/attributes/FieldName.md
Normal 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)
|
||||
@ -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
55
help/class_desc/attributes/ForeignKey.md
Normal 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)
|
||||
@ -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
75
help/class_desc/attributes/IgnoredInDB.md
Normal 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)
|
||||
@ -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
55
help/class_desc/attributes/NotNull.md
Normal 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)
|
||||
@ -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
55
help/class_desc/attributes/PrimaryKey.md
Normal 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)
|
||||
@ -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
57
help/class_desc/attributes/Unique.md
Normal 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)
|
||||
@ -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 ()
|
||||
{
|
||||
}
|
||||
}
|
||||
158
help/class_desc/classes/Condition.md
Normal file
158
help/class_desc/classes/Condition.md
Normal file
@ -0,0 +1,158 @@
|
||||
# Класс `Condition`
|
||||
|
||||
Класс `Condition` предназначен для представления условий, используемых в запросах к базе данных. Он позволяет построить
|
||||
выражения для фильтрации данных на основе логических операторов и критериев.
|
||||
|
||||
## Пространство имён
|
||||
|
||||
```php
|
||||
namespace goodboyalex\php_db_components_pack;
|
||||
```
|
||||
|
||||
## Автор и версия
|
||||
|
||||
- **Автор**: Александр Бабаев
|
||||
- **Версия**: 1.0
|
||||
- **Дата начала поддержки**: с версии 1.0
|
||||
|
||||
## Назначение
|
||||
|
||||
Класс `Condition` предназначен для создания и представления условий, используемых в SQL-запросах. Он позволяет задавать
|
||||
критерии фильтрации, объединять их логическими операторами и формировать готовые SQL-выражения для безопасного
|
||||
исполнения запросов.
|
||||
|
||||
## Реализуемые интерфейсы
|
||||
|
||||
Класс `Condition` реализует интерфейс `IArrayable`.
|
||||
|
||||
## Логические операторы
|
||||
|
||||
Класс предоставляет ряд постоянных, определяющих логические операторы, которые могут быть использованы при формировании
|
||||
условий:
|
||||
|
||||
- `LOGIC_AND` («И», AND)
|
||||
- `LOGIC_OR` («ИЛИ», OR)
|
||||
- `LOGIC_NOT` («НЕ», NOT)
|
||||
- `LOGIC_XOR` («Исключающее ИЛИ», XOR)
|
||||
- `LOGIC_NAND` («Нелогичное И», NAND)
|
||||
- `LOGIC_NOR` («Нелогичное ИЛИ», NOR)
|
||||
|
||||
## Методы класса
|
||||
|
||||
### 1. Конструктор
|
||||
|
||||
**Назначение**: Создать объект условия с заданием имени колонки, оператора и значения.
|
||||
|
||||
**Синтаксис**:
|
||||
|
||||
```php
|
||||
public function __construct (
|
||||
string $columnName = "",
|
||||
string $operator = "=",
|
||||
mixed $value = null
|
||||
);
|
||||
```
|
||||
|
||||
**Описание**:
|
||||
|
||||
- **$columnName**: Имя колонки, к которой применяется условие ИЛИ условие (подробнее читайте далее в пункте про
|
||||
`FUNC:`).
|
||||
- **$operator**: Оператор сравнения (например, `=`, `<>`, `<`, `>`, `LIKE`, etc.). Стандартное значение — `=` (
|
||||
равенство).
|
||||
- **$value**: Значение, с которым производится сравнение ИЛИ результат вычисления функции (подробнее читайте далее в
|
||||
пункте про `FUNC:`).
|
||||
|
||||
**Пример использования**:
|
||||
|
||||
```php
|
||||
$condition = new Condition('age', '>', 18);
|
||||
```
|
||||
|
||||
#### Задание условий с помощью функции (`FUNC:`)
|
||||
|
||||
Если в имени колонки передаётся какая-либо функция (начинать такую функцию следует с `FUNC:`), то при обработке она
|
||||
не обрабатывается как столбец. Это же касается и значения.
|
||||
|
||||
Например, давайте добавим условие, что каждое новое имя пользователя начинается с заглавной буквы
|
||||
|
||||
```php
|
||||
use goodboyalex\php_db_components_pack\classes\Condition;
|
||||
|
||||
$condition = new Condition('FUNC:SUBSTR(name, 1, 1)', "=", 'FUNC:UPPER(SUBSTR(name, 1, 1))
|
||||
```
|
||||
|
||||
в результате запрос будет содержать:
|
||||
```sql
|
||||
SUBSTR(name, 1, 1) = UPPER(SUBSTR(name, 1, 1)
|
||||
```
|
||||
|
||||
### 2. Метод `Parse`
|
||||
|
||||
**Назначение**: Разобрать условие, заданное в виде массива, и возвратить объект `Condition`.
|
||||
|
||||
**Синтаксис**:
|
||||
|
||||
```php
|
||||
public static function Parse(array $condition): Condition;
|
||||
```
|
||||
|
||||
**Описание**:
|
||||
|
||||
- **$condition**: Массив, содержащий три элемента: имя колонки, оператор и значение.
|
||||
- Метод преобразует массив в полноценный объект `Condition`.
|
||||
|
||||
**Пример использования**:
|
||||
|
||||
```php
|
||||
$parsedCondition = Condition::Parse(['age', '>', 18]);
|
||||
```
|
||||
|
||||
### 3. Метод `Get`
|
||||
|
||||
**Назначение**: Сформировать условие для SQL-запроса с защитой от SQL-инъекций.
|
||||
|
||||
**Синтаксис**:
|
||||
|
||||
```php
|
||||
public function Get(int $index = 0): Tuple;
|
||||
```
|
||||
|
||||
**Описание**:
|
||||
|
||||
- **$index**: Индексация для замены переменных (для предотвращения SQL-инъекций).
|
||||
- Метод возвращает кортеж (tuple), состоящий из двух частей:
|
||||
- SQL-строку с замещаемым параметром (`:paramX`), где X — номер индекса.
|
||||
- Массив с параметрами для последующего внедрения в запрос.
|
||||
|
||||
**Пример использования**:
|
||||
|
||||
```php
|
||||
[$sqlPart, $params] = $condition->Get();
|
||||
// $sqlPart будет выглядеть примерно так: "`age` > :param0"
|
||||
// $params будет содержать массив с фактическим значением: ["param0" => 18]
|
||||
```
|
||||
|
||||
## Пример использования
|
||||
|
||||
```php
|
||||
use goodboyalex\php_db_components_pack\Condition;
|
||||
|
||||
// Создаём условие для поиска пользователей по возрасту
|
||||
$condition = new Condition('age', '>', 18);
|
||||
|
||||
// Формируем условие для использования в SQL-запросе
|
||||
list($sql, $parameters) = $condition->Get();
|
||||
|
||||
// Теперь можем использовать $sql и $parameters в запросе
|
||||
$query = "SELECT * FROM users WHERE $sql";
|
||||
$stmt = $pdo->prepare($query);
|
||||
$stmt->execute($parameters);
|
||||
```
|
||||
|
||||
## Принцип работы
|
||||
|
||||
Класс `Condition` помогает избежать распространенных уязвимостей, таких как SQL-инъекции, предлагая безопасный способ
|
||||
формирования условий для SQL-запросов. Он активно используется в условиях запросов к базе данных, позволяя разработчику
|
||||
сосредоточиться на логике приложения, а не на технических аспектах формирования запросов.
|
||||
|
||||
[На главную](../../index.md)
|
||||
361
help/class_desc/classes/ConditionBuilder.md
Normal file
361
help/class_desc/classes/ConditionBuilder.md
Normal file
@ -0,0 +1,361 @@
|
||||
# Класс `ConditionBuilder`
|
||||
|
||||
Класс `ConditionBuilder` предназначен для удобного построения сложных условий запросов к базе данных. Он позволяет
|
||||
постепенно наращивать цепь условий, используя цепочечные методы и логические операторы (`AND`, `OR`, `NOT` и т.д.), что
|
||||
значительно упрощает формирование SQL-запросов.
|
||||
|
||||
## Пространство имён
|
||||
|
||||
```php
|
||||
namespace goodboyalex\php_db_components_pack\classes;
|
||||
```
|
||||
|
||||
## Автор и версия
|
||||
|
||||
- **Автор**: Александр Бабаев
|
||||
- **Версия**: 1.0
|
||||
- **Дата начала поддержки**: с версии 1.0
|
||||
|
||||
## Назначение
|
||||
|
||||
Класс `ConditionBuilder` позволяет гибко составлять сложные условия запросов к базе данных, последовательно добавляя
|
||||
условия и логические операторы. Это незаменимый инструмент для быстрого и простого создания запросов, основанных на
|
||||
многомерных фильтрах.
|
||||
|
||||
## Основные элементы класса
|
||||
|
||||
### Составляющие части
|
||||
|
||||
- **Логические операторы**: Предусмотрены основные логические операторы (`AND`, `OR`, `NOT`, `XOR`, `NAND`, `NOR`),
|
||||
позволяющие объединять условия с необходимой логической связью.
|
||||
- **Группа условий**: Условия могут быть объединены в группы, что позволяет выстраивать сложную иерархию условий.
|
||||
- **Защита от SQL-инъекций**: Встроенная защита от SQL-инъекций обеспечивается за счёт возврата готовых параметров
|
||||
запроса.
|
||||
|
||||
### Методы
|
||||
|
||||
#### 1. Конструктор (`__construct`)
|
||||
|
||||
**Назначение**: Создаёт пустой объект, который впоследствии наполняется условиями.
|
||||
|
||||
**Синтаксис**:
|
||||
|
||||
```php
|
||||
public function __construct ();
|
||||
```
|
||||
|
||||
**Описание**: Создаёт новый экземпляр класса `ConditionBuilder`, который далее будет использован для накопления условий
|
||||
и объединения их логическими операторами.
|
||||
|
||||
---
|
||||
|
||||
#### 2. Метод `Parse`
|
||||
|
||||
**Назначение**: Прочитать и разобрать массив условий, созданный вручную или динамически, и создать объект для дальнейшей
|
||||
работы.
|
||||
|
||||
**Синтаксис**:
|
||||
|
||||
```php
|
||||
public static function Parse(array $conditions): ConditionBuilder;
|
||||
```
|
||||
|
||||
**Описание**:
|
||||
|
||||
- Метод принимает массив условий и логических операторов.
|
||||
- Каждое условие представляется элемент ассоциативного массива, ключом которого является имя столбца, а значение
|
||||
представляет собой массив из (1) оператора и (2) значения.
|
||||
- В роли массива значений может выступать и просто значение, тогда за оператор берётся оператор `=`.
|
||||
- Логические операторы (`AND`, `OR`, ...) могут находиться между условиями.
|
||||
- Пример входящего массива:
|
||||
|
||||
```php
|
||||
["id" => 1, 'AND', "age" => ['>=', 18], 'OR', "profile" => ['<=', 12]]
|
||||
```
|
||||
|
||||
- Результатом работы метода является объект `ConditionBuilder`, содержащий всю необходимую информацию для формирования
|
||||
SQL-запроса.
|
||||
|
||||
---
|
||||
|
||||
#### 3. Метод `AddGroup`
|
||||
|
||||
**Назначение**: Добавляет группу условий, объединённых общим логическим оператором.
|
||||
|
||||
**Синтаксис**:
|
||||
|
||||
```php
|
||||
public function AddGroup(string $logicalOperator, array $conditions): ConditionBuilder;
|
||||
```
|
||||
|
||||
**Описание**:
|
||||
|
||||
- **$logicalOperator**: Логический оператор (`AND`, `OR`, и т.д.), который связывает условия в группе.
|
||||
- **$conditions**: Массив условий, относящихся к группе.
|
||||
- Метод добавляет группу условий и возвращает тот же объект `ConditionBuilder`, позволяя продолжить сборку цепочкой
|
||||
методов.
|
||||
|
||||
---
|
||||
|
||||
#### 4. Метод `Build`
|
||||
|
||||
**Назначение**: Формирует финальную строку SQL-запроса и массив параметров для защиты от SQL-инъекций.
|
||||
|
||||
**Синтаксис**:
|
||||
|
||||
```php
|
||||
public function Build(): Tuple;
|
||||
```
|
||||
|
||||
**Описание**:
|
||||
|
||||
- Метод возвращает кортеж (Tuple), состоящий из двух элементов:
|
||||
- SQL-строка с условием, готовым к выполнению.
|
||||
- Массив параметров, необходимых для последующей передачи в подготовленный SQL-запрос.
|
||||
- Позволяет легко интегрировать построенное условие в SQL-запрос.
|
||||
|
||||
---
|
||||
|
||||
#### 5. Метод `Count`
|
||||
|
||||
**Назначение**: Возвращает количество накопленных условий.
|
||||
|
||||
**Синтаксис**:
|
||||
|
||||
```php
|
||||
public function Count(): int;
|
||||
```
|
||||
|
||||
**Описание**: Метод возвращает целое число, показывающее, сколько условий было собрано на текущий момент.
|
||||
|
||||
---
|
||||
|
||||
#### 6. Метод `WhereEquals`
|
||||
|
||||
**Назначение**: Добавляет условие "равно".
|
||||
|
||||
**Синтаксис**:
|
||||
|
||||
```php
|
||||
public function WhereEquals(string $column, mixed $value): ConditionBuilder;
|
||||
```
|
||||
|
||||
**Описание**:
|
||||
|
||||
- **$column**: Имя колонки.
|
||||
- **$value**: Значение, с которым колонка сравнивается.
|
||||
- Метод добавляет условие в виде `WHERE column = value` и возвращает объект для продолжения цепочки.
|
||||
|
||||
---
|
||||
|
||||
#### 7. Метод `WhereNotEquals`
|
||||
|
||||
**Назначение**: Добавляет условие "не равно".
|
||||
|
||||
**Синтаксис**:
|
||||
|
||||
```php
|
||||
public function WhereNotEquals(string $column, mixed $value): ConditionBuilder;
|
||||
```
|
||||
|
||||
**Описание**:
|
||||
|
||||
- Аналогичен предыдущему методу, но добавляет условие вида `WHERE column <> value`.
|
||||
|
||||
---
|
||||
|
||||
#### 8. Метод `WhereGreaterThan`
|
||||
|
||||
**Назначение**: Добавляет условие "больше".
|
||||
|
||||
**Синтаксис**:
|
||||
|
||||
```php
|
||||
public function WhereGreaterThan(string $column, mixed $value): ConditionBuilder;
|
||||
```
|
||||
|
||||
**Описание**:
|
||||
|
||||
- Добавляет условие вида `WHERE column > value`.
|
||||
|
||||
---
|
||||
|
||||
#### 9. Метод `WhereLessThan`
|
||||
|
||||
**Назначение**: Добавляет условие "меньше".
|
||||
|
||||
**Синтаксис**:
|
||||
|
||||
```php
|
||||
public function WhereLessThan(string $column, mixed $value): ConditionBuilder;
|
||||
```
|
||||
|
||||
**Описание**:
|
||||
|
||||
- Добавляет условие вида `WHERE column < value`.
|
||||
|
||||
---
|
||||
|
||||
#### 10. Метод `WhereGreaterThanEqual`
|
||||
|
||||
**Назначение**: Добавляет условие "больше или равно".
|
||||
|
||||
**Синтаксис**:
|
||||
|
||||
```php
|
||||
public function WhereGreaterThanEqual(string $column, mixed $value): ConditionBuilder;
|
||||
```
|
||||
|
||||
**Описание**:
|
||||
|
||||
- Добавляет условие вида `WHERE column >= value`.
|
||||
|
||||
---
|
||||
|
||||
#### 11. Метод `WhereLessThanEqual`
|
||||
|
||||
**Назначение**: Добавляет условие "меньше или равно".
|
||||
|
||||
**Синтаксис**:
|
||||
|
||||
```php
|
||||
public function WhereLessThanEqual(string $column, mixed $value): ConditionBuilder;
|
||||
```
|
||||
|
||||
**Описание**:
|
||||
|
||||
- Добавляет условие вида `WHERE column <= value`.
|
||||
|
||||
---
|
||||
|
||||
#### 12. Метод `AddLogicalOperator`
|
||||
|
||||
**Назначение**: Добавляет логический оператор в цепочку условий.
|
||||
|
||||
**Синтаксис**:
|
||||
|
||||
```php
|
||||
public function AddLogicalOperator(string $operator): false|ConditionBuilder;
|
||||
```
|
||||
|
||||
**Описание**:
|
||||
|
||||
- **$operator**: Логический оператор (`AND`, `OR`, `NOT`, `XOR`, `NAND`, `NOR`).
|
||||
- Метод добавляет указанный оператор в последовательность условий и возвращает объект для продолжения цепочки. Если
|
||||
оператор неправильный, возвращает `false`.
|
||||
|
||||
---
|
||||
|
||||
#### 13. Метод `And`
|
||||
|
||||
**Назначение**: Добавляет логический оператор `AND`.
|
||||
|
||||
**Синтаксис**:
|
||||
|
||||
```php
|
||||
public function And(): ConditionBuilder;
|
||||
```
|
||||
|
||||
**Описание**: Удобный аналог метода `AddLogicalOperator`, предназначенный специально для оператора `AND`.
|
||||
|
||||
---
|
||||
|
||||
#### 14. Метод `Or`
|
||||
|
||||
**Назначение**: Добавляет логический оператор `OR`.
|
||||
|
||||
**Синтаксис**:
|
||||
|
||||
```php
|
||||
public function Or(): ConditionBuilder;
|
||||
```
|
||||
|
||||
**Описание**: Удобный аналог метода `AddLogicalOperator`, предназначенный специально для оператора `OR`.
|
||||
|
||||
---
|
||||
|
||||
#### 15. Метод `Not`
|
||||
|
||||
**Назначение**: Добавляет логический оператор `NOT`.
|
||||
|
||||
**Синтаксис**:
|
||||
|
||||
```php
|
||||
public function Not(): ConditionBuilder;
|
||||
```
|
||||
|
||||
**Описание**: Удобный аналог метода `AddLogicalOperator`, предназначенный специально для оператора `NOT`.
|
||||
|
||||
---
|
||||
|
||||
#### 16. Метод `Xor`
|
||||
|
||||
**Назначение**: Добавляет логический оператор `XOR`.
|
||||
|
||||
**Синтаксис**:
|
||||
|
||||
```php
|
||||
public function Xor(): ConditionBuilder;
|
||||
```
|
||||
|
||||
**Описание**: Удобный аналог метода `AddLogicalOperator`, предназначенный специально для оператора `XOR`.
|
||||
|
||||
---
|
||||
|
||||
#### 17. Метод `Nand`
|
||||
|
||||
**Назначение**: Добавляет логический оператор `NAND`.
|
||||
|
||||
**Синтаксис**:
|
||||
|
||||
```php
|
||||
public function Nand(): ConditionBuilder;
|
||||
```
|
||||
|
||||
**Описание**: Удобный аналог метода `AddLogicalOperator`, предназначенный специально для оператора `NAND`.
|
||||
|
||||
---
|
||||
|
||||
#### 18. Метод `Nor`
|
||||
|
||||
**Назначение**: Добавляет логический оператор `NOR`.
|
||||
|
||||
**Синтаксис**:
|
||||
|
||||
```php
|
||||
public function Nor(): ConditionBuilder;
|
||||
```
|
||||
|
||||
**Описание**: Удобный аналог метода `AddLogicalOperator`, предназначенный специально для оператора `NOR`.
|
||||
|
||||
## Пример использования
|
||||
|
||||
Допустим, у вас есть задача отобрать пользователей, чей возраст превышает 18 лет и они зарегистрированы позже
|
||||
определённой даты:
|
||||
|
||||
```php
|
||||
use goodboyalex\php_db_components_pack\classes\ConditionBuilder;
|
||||
|
||||
// Создаём объект ConditionBuilder
|
||||
$builder = new ConditionBuilder()->WhereGreaterThan('age', 18)->And()->WhereGreaterThan('registration_date', '2023-01-01');
|
||||
|
||||
// Собираем условия
|
||||
[$sqlFragment, $params] = $builder->Build();
|
||||
```
|
||||
|
||||
В результате можно будет создать такой запрос:
|
||||
|
||||
```sql
|
||||
SELECT *
|
||||
FROM `TABLE`
|
||||
WHERE (`age` > 18)
|
||||
AND (`registration_date` > '2023-01-01');
|
||||
```
|
||||
|
||||
## Принцип работы
|
||||
|
||||
Класс `ConditionBuilder` постепенно аккумулирует условия, создавая дерево зависимостей, состоящее из условий и
|
||||
логических операторов. За счёт этого появляется возможность легко создавать и редактировать сложные фильтры для запросов
|
||||
к базе данных.
|
||||
|
||||
[На главную](../../index.md)
|
||||
86
help/class_desc/classes/ConditionGroup.md
Normal file
86
help/class_desc/classes/ConditionGroup.md
Normal file
@ -0,0 +1,86 @@
|
||||
# Класс `ConditionGroup`
|
||||
|
||||
Класс `ConditionGroup` предназначен для группировки условий в SQL-запросах, позволяя комбинировать отдельные условия с
|
||||
помощью логических операторов (`AND`, `OR`, `NOT`, и т.д.) и формировать единое сложное выражение для использования в
|
||||
запросах к базе данных.
|
||||
|
||||
## Пространство имён
|
||||
|
||||
```php
|
||||
namespace goodboyalex\php_db_components_pack\classes;
|
||||
```
|
||||
|
||||
## Автор и версия
|
||||
|
||||
- **Автор**: Александр Бабаев
|
||||
- **Версия**: 1.0
|
||||
- **Дата начала поддержки**: с версии 1.0
|
||||
|
||||
## Назначение
|
||||
|
||||
Класс `ConditionGroup` позволяет группировать условия и соединять их логическим оператором, формируя составные условия
|
||||
для SQL-запросов. Это особенно полезно, когда нужно объединить несколько простых условий в одно комплексное.
|
||||
|
||||
## Важно
|
||||
|
||||
Все условия, входящие в `ConditionGroup` должны быть объеденины **одним единственным оператором**. То есть, вот такое
|
||||
условие не объединить в `ConditionGroup`:
|
||||
|
||||
```
|
||||
(условие 1 AND условие 2 OR условие 3)
|
||||
```
|
||||
|
||||
Для реализации такого условия, какие-то из условий должны быть заключены в подгруппу.
|
||||
|
||||
## Основные методы класса
|
||||
|
||||
1. **Конструктор (`__construct`)**
|
||||
Создаёт объект группы условий с возможностью указания логического оператора и самих условий.
|
||||
|
||||
2. **Формирование условий (`GetConditions`)**
|
||||
Формирует итоговую группу условий в виде пары: SQL-строка и массив параметров для безопасной передачи в запрос.
|
||||
|
||||
3. **Количество условий (`Count`)**
|
||||
Возвращает количество условий в группе.
|
||||
|
||||
## Пример использования
|
||||
|
||||
Допустим, у вас есть две группы условий: первая группа ищет пользователей от 18 и до 45 лет, вторая — пользователей с
|
||||
правами администратора или модератора. Вы хотите объединить эти условия с помощью оператора `OR`:
|
||||
|
||||
```php
|
||||
use goodboyalex\php_components_pack\Condition;
|
||||
use goodboyalex\php_components_pack\ConditionGroup;
|
||||
|
||||
// Первая группа условий: пользователи от 18 до 45 лет
|
||||
$group1 = new ConditionGroup(Condition::LOGIC_AND, [
|
||||
new Condition('age', '>=', 18),
|
||||
new Condition('age', '<=', 45)
|
||||
]);
|
||||
|
||||
// Вторая группа условий: администраторы
|
||||
$group2 = new ConditionGroup(Condition::LOGIC_OR, [
|
||||
new Condition('role', '=', 'admin'),
|
||||
new Condition('role', '=', 'moderator')
|
||||
]);
|
||||
|
||||
// Объединяем обе группы с оператором OR
|
||||
$combinedGroup = new ConditionGroup(Condition::LOGIC_OR, [
|
||||
$group1,
|
||||
$group2
|
||||
]);
|
||||
```
|
||||
|
||||
Группа `$combinedGroup` равносильна такому ограничению:
|
||||
|
||||
```
|
||||
((`age` >= 18) AND (`age` <= 45)) OR ((`role`='admin') OR (`role`='moderator'))
|
||||
```
|
||||
|
||||
## Принцип работы
|
||||
|
||||
Класс `ConditionGroup` собирает отдельные условия в группы и соединяет их с помощью логических операторов. Затем с
|
||||
помощью метода `GetConditions` формируются готовые SQL-условия, подходящие для встраивания в запрос с поддержкой
|
||||
механизма подставляемых параметров (placeholders), что обеспечивает защиту от SQL-инъекций.
|
||||
|
||||
[На главную](../../index.md)
|
||||
@ -58,7 +58,7 @@ class User implements IDBItem
|
||||
/**
|
||||
* @var string $Email Почта пользователя.
|
||||
*/
|
||||
#[NotNull, FieldName('user_mail')]
|
||||
#[NotNull, FieldName('user_mail'), Unique]
|
||||
public string $Email = '';
|
||||
}
|
||||
```
|
||||
|
||||
@ -1,4 +1,4 @@
|
||||
# Класс `DBConfig`
|
||||
# Модель `DBConfig`
|
||||
|
||||
## Описание
|
||||
|
||||
|
||||
97
help/class_desc/models/DBItemProperty.md
Normal file
97
help/class_desc/models/DBItemProperty.md
Normal file
@ -0,0 +1,97 @@
|
||||
# Класс `DBItemProperty`
|
||||
|
||||
Класс `DBItemProperty` предназначен для описания отдельного свойства объекта, реализующего интерфейс `IDBItem`. Он
|
||||
предоставляет полную информацию о свойствах объекта, предназначенных для хранения в базе данных, включая имя, значение,
|
||||
тип данных, правила преобразования и сравнение.
|
||||
|
||||
## Пространство имён
|
||||
|
||||
```php
|
||||
namespace goodboyalex\php_db_components_pack\models;
|
||||
```
|
||||
|
||||
## Автор и версия
|
||||
|
||||
- **Автор**: Александр Бабаев
|
||||
- **Версия**: 1.0
|
||||
- **Дата начала поддержки**: с версии 1.0
|
||||
|
||||
## Назначение
|
||||
|
||||
Класс `DBItemProperty` описывает отдельную сущность — объект и его свойства, предназначенного для хранения в базе
|
||||
данных. Помимо основного значения, он также хранит информацию о том, как это свойство будет отражаться в базе данных
|
||||
(например, имя колонки, тип данных, преобразователи и правила игнорирования).
|
||||
|
||||
## Основные элементы класса
|
||||
|
||||
### Поля
|
||||
|
||||
## Поля класса `DBItemProperty`
|
||||
|
||||
| Имя поля | Тип поля | Описание |
|
||||
|---------------|----------------|--------------------------------------------------------------------------------------------------------------|
|
||||
| Name | string | Имя свойства в объекте. |
|
||||
| Value | mixed | Текущее значение свойства (до преобразования). |
|
||||
| Column | DataBaseColumn | Объект, описывающий характеристики колонки в базе данных (тип данных, ограничения и т.д.). |
|
||||
| IsIgnored | bool | Признак, указывающий, что данное свойство игнорируется при сохранении в базу данных или загрузке из неё. | |
|
||||
| ConvertToDB | Closure | Замыкание, осуществляющее преобразование значения свойства в формат, подходящий для записи в базу данных. |
|
||||
| ConvertFromDB | Closure | Замыкание, осуществляющее обратное преобразование из формата базы данных в формат внутреннего представления. |
|
||||
| Compare | Closure | Замыкание, позволяющее сравнивать значения свойства. |
|
||||
|
||||
### Конструктор
|
||||
|
||||
Позволяет сконструировать объект с полной информацией о свойстве, включая имя, значение, связь с колонкой базы данных и
|
||||
средства преобразования и сравнения.
|
||||
|
||||
## Пример использования
|
||||
|
||||
Допустим, у вас есть объект пользователя, и вы хотите описать свойство `username` следующим образом:
|
||||
|
||||
```php
|
||||
use goodboyalex\php_db_components_pack\models\DBItemProperty;
|
||||
use goodboyalex\php_db_components_pack\models\DataBaseColumn;
|
||||
use goodboyalex\php_db_components_pack\enums\DBType;
|
||||
|
||||
// Создаём объект свойства username
|
||||
$property = new DBItemProperty(
|
||||
// Имя свойства
|
||||
'username',
|
||||
// Текущее значение
|
||||
'john_doe',
|
||||
// Характеристики колонки
|
||||
new DataBaseColumn(
|
||||
// - имя колонки в базе данных
|
||||
'user_name',
|
||||
// - тип данных (строка, макс. 255 символов)
|
||||
new Tuple(DBType::STRING, 255),
|
||||
// - NOT NULL
|
||||
true,
|
||||
// - UNIQUE
|
||||
true,
|
||||
// - не первичный ключ
|
||||
false,
|
||||
// - без внешнего ключа
|
||||
new Tuple(null, null),
|
||||
// - без проверок
|
||||
new ConditionBuilder(),
|
||||
// - значение по умолчанию
|
||||
''
|
||||
),
|
||||
// Не игнорируется
|
||||
false,
|
||||
// Преобразование в нижний регистр перед сохранением
|
||||
function ($value) { return strtolower($value); },
|
||||
// Преобразование в Title Case при получении
|
||||
function ($value) { return ucfirst($value); },
|
||||
// Функция сравнения
|
||||
function ($left, $right) { return strcmp($left, $right); }
|
||||
);
|
||||
```
|
||||
|
||||
## Дополнительная информация
|
||||
|
||||
Класс `DBItemProperty` является важной составляющей инфраструктуры для работы с объектами, предназначенными для хранения
|
||||
в базе данных. Он позволяет детально описывать свойства объектов, включая преобразования и правила загрузки/записи, что
|
||||
существенно упрощает интеграцию с базой данных и повышает гибкость работы с данными.
|
||||
|
||||
[На главную](../../index.md)
|
||||
84
help/class_desc/models/DataBaseColumn.md
Normal file
84
help/class_desc/models/DataBaseColumn.md
Normal file
@ -0,0 +1,84 @@
|
||||
# Модель `DataBaseColumn`
|
||||
|
||||
Класс `DataBaseColumn` предназначен для описания структуры отдельной колонки в базе данных. Он предоставляет подробную
|
||||
информацию о характеристиках колонки, таких как тип данных, ограничения на значения, связи с другими таблицами и многое
|
||||
другое.
|
||||
|
||||
## Пространство имён
|
||||
|
||||
```php
|
||||
namespace goodboyalex\php_db_components_pack\models;
|
||||
```
|
||||
|
||||
## Автор и версия
|
||||
|
||||
- **Автор**: Александр Бабаев
|
||||
- **Версия**: 1.0
|
||||
- **Дата начала поддержки**: с версии 1.0
|
||||
|
||||
## Назначение
|
||||
|
||||
Класс `DataBaseColumn` используется для точного описания характеристик колонки в базе данных. Он позволяет указать тип
|
||||
данных, длину, обязательность, уникальность, наличие первичного ключа, внешний ключ, проверку данных и прочие аспекты,
|
||||
влияющие на корректную работу с базой данных.
|
||||
|
||||
## Основные элементы класса
|
||||
|
||||
### Поля
|
||||
|
||||
## Поля класса `DataBaseColumn`
|
||||
|
||||
| Имя поля | Тип поля | Описание |
|
||||
|-----------------|------------------|--------------------------------------------------------------------------------------------------------------------------------|
|
||||
| Name | string | Имя колонки в базе данных. |
|
||||
| Type | Tuple | Тип данных колонки, где первый элемент — тип данных (например, `DBType::STRING`), второй — максимальная длина (например, 255). |
|
||||
| IsNotNull | bool | Признак, указывающий, разрешена ли установка значения `NULL` в колонку. |
|
||||
| IsUnique | bool | Признак, указывающий, что каждое значение в колонке должно быть уникальным. |
|
||||
| IsPrimaryKey | bool | Признак, указывающий, что колонка является первичным ключом. |
|
||||
| ForeignWith | Tuple | Внешний ключ, связанный с другой таблицей, где первый элемент — имя таблицы, второй — имя колонки. |
|
||||
| Check | ConditionBuilder | Контрольные условия для вносимых данных, представлены объектом `ConditionBuilder`. |
|
||||
| Default | mixed | Значение по умолчанию для колонки. Может быть любого подходящего типа данных. |
|
||||
| IsAutoIncrement | bool | Признак, указывающий, что значение колонки генерируется автоматически при добавлении новой записи (авто-инкремент). |
|
||||
|
||||
### Конструктор
|
||||
|
||||
Позволяет задать полную конфигурацию колонки, включая имя, тип данных, ограничения и связи.
|
||||
|
||||
## Пример использования
|
||||
|
||||
Допустим, у вас есть таблица пользователей, и вы хотите описать колонку с именем пользователя следующим образом:
|
||||
|
||||
```php
|
||||
use goodboyalex\php_db_components_pack\models\DataBaseColumn;
|
||||
use goodboyalex\php_db_components_pack\enums\DBType;
|
||||
|
||||
// Создаём объект колонки
|
||||
$column = new DataBaseColumn(
|
||||
// Имя колонки
|
||||
'username',
|
||||
// Тип данных (строка, максимум 255 символов)
|
||||
new Tuple(DBType::STRING, 255),
|
||||
// Запрет пустых значений (NOT NULL)
|
||||
true,
|
||||
// Уникальные значения (UNIQUE)
|
||||
true,
|
||||
// Не является первичным ключом
|
||||
false,
|
||||
// Без внешнего ключа
|
||||
new Tuple(null, null),
|
||||
// Без проверок
|
||||
new ConditionBuilder(),
|
||||
// Значение по умолчанию (пустая строка)
|
||||
'',
|
||||
// Авто-инкремент отключён
|
||||
false
|
||||
);
|
||||
```
|
||||
|
||||
## Дополнительная информация
|
||||
|
||||
Класс `DataBaseColumn` является мощным инструментом для детализации структуры колонок базы данных. Он предоставляет
|
||||
широкие возможности для настройки различных аспектов колонки, таких как тип данных, ограничения, связи и прочее. Это
|
||||
существенно облегчает работу с базой данных и способствует повышению качества проектирования моделей данных.
|
||||
|
||||
[На главную](../../index.md)
|
||||
@ -14,7 +14,9 @@
|
||||
|
||||
### Модели
|
||||
|
||||
- [DataBaseColumn](class_desc/models/DataBaseColumn.md)
|
||||
- [DBConfig](class_desc/models/DBConfig.md)
|
||||
- [DBItemProperty](class_desc/models/DBItemProperty.md)
|
||||
|
||||
### Перечисления
|
||||
|
||||
|
||||
@ -38,7 +38,13 @@
|
||||
if (count($ignoredOperations) === 0)
|
||||
// - то по умолчанию игнорируем все операции
|
||||
$ignoredOperations = [
|
||||
DBOperation::Insert, DBOperation::Get, DBOperation::Update, DBOperation::Delete, DBOperation::Count
|
||||
DBOperation::Insert,
|
||||
DBOperation::Get,
|
||||
DBOperation::Update,
|
||||
DBOperation::Delete,
|
||||
DBOperation::Count,
|
||||
DBOperation::CreateTable,
|
||||
DBOperation::DropTable
|
||||
];
|
||||
|
||||
// Инициализируем массив
|
||||
|
||||
@ -6,10 +6,10 @@
|
||||
namespace goodboyalex\php_db_components_pack\classes\tm_drivers;
|
||||
|
||||
use goodboyalex\php_components_pack\classes\ObjectArray;
|
||||
use goodboyalex\php_db_components_pack\classes\DataBaseColumn;
|
||||
use goodboyalex\php_db_components_pack\enums\DBDriver;
|
||||
use goodboyalex\php_db_components_pack\enums\DBType;
|
||||
use goodboyalex\php_db_components_pack\interfaces\ITableManager;
|
||||
use goodboyalex\php_db_components_pack\models\DataBaseColumn;
|
||||
use PDO;
|
||||
|
||||
/**
|
||||
|
||||
@ -6,10 +6,10 @@
|
||||
namespace goodboyalex\php_db_components_pack\classes\tm_drivers;
|
||||
|
||||
use goodboyalex\php_components_pack\classes\ObjectArray;
|
||||
use goodboyalex\php_db_components_pack\classes\DataBaseColumn;
|
||||
use goodboyalex\php_db_components_pack\enums\DBDriver;
|
||||
use goodboyalex\php_db_components_pack\enums\DBType;
|
||||
use goodboyalex\php_db_components_pack\interfaces\ITableManager;
|
||||
use goodboyalex\php_db_components_pack\models\DataBaseColumn;
|
||||
use PDO;
|
||||
|
||||
/**
|
||||
|
||||
@ -6,10 +6,10 @@
|
||||
namespace goodboyalex\php_db_components_pack\classes\tm_drivers;
|
||||
|
||||
use goodboyalex\php_components_pack\classes\ObjectArray;
|
||||
use goodboyalex\php_db_components_pack\classes\DataBaseColumn;
|
||||
use goodboyalex\php_db_components_pack\enums\DBDriver;
|
||||
use goodboyalex\php_db_components_pack\enums\DBType;
|
||||
use goodboyalex\php_db_components_pack\interfaces\ITableManager;
|
||||
use goodboyalex\php_db_components_pack\models\DataBaseColumn;
|
||||
use PDO;
|
||||
use PDOException;
|
||||
|
||||
|
||||
@ -6,10 +6,10 @@
|
||||
namespace goodboyalex\php_db_components_pack\classes\tm_drivers;
|
||||
|
||||
use goodboyalex\php_components_pack\classes\ObjectArray;
|
||||
use goodboyalex\php_db_components_pack\classes\DataBaseColumn;
|
||||
use goodboyalex\php_db_components_pack\enums\DBDriver;
|
||||
use goodboyalex\php_db_components_pack\enums\DBType;
|
||||
use goodboyalex\php_db_components_pack\interfaces\ITableManager;
|
||||
use goodboyalex\php_db_components_pack\models\DataBaseColumn;
|
||||
use PDO;
|
||||
use PDOException;
|
||||
|
||||
|
||||
@ -6,10 +6,10 @@
|
||||
namespace goodboyalex\php_db_components_pack\classes\tm_drivers;
|
||||
|
||||
use goodboyalex\php_components_pack\classes\ObjectArray;
|
||||
use goodboyalex\php_db_components_pack\classes\DataBaseColumn;
|
||||
use goodboyalex\php_db_components_pack\enums\DBDriver;
|
||||
use goodboyalex\php_db_components_pack\enums\DBType;
|
||||
use goodboyalex\php_db_components_pack\interfaces\ITableManager;
|
||||
use goodboyalex\php_db_components_pack\models\DataBaseColumn;
|
||||
use PDO;
|
||||
use PDOException;
|
||||
|
||||
|
||||
@ -3,7 +3,7 @@
|
||||
namespace goodboyalex\php_db_components_pack\interfaces;
|
||||
|
||||
use goodboyalex\php_components_pack\classes\ObjectArray;
|
||||
use goodboyalex\php_db_components_pack\classes\DataBaseColumn;
|
||||
use goodboyalex\php_db_components_pack\models\DataBaseColumn;
|
||||
use PDO;
|
||||
|
||||
/**
|
||||
@ -47,7 +47,7 @@
|
||||
/**
|
||||
* Разбирает столбец для SQL-запроса создания.
|
||||
*
|
||||
* @param DataBaseColumn $column Столбец таблицы.
|
||||
* @param \goodboyalex\php_db_components_pack\models\DataBaseColumn $column Столбец таблицы.
|
||||
*
|
||||
* @return string SQL-представление столбца.
|
||||
*/
|
||||
|
||||
@ -1,9 +1,8 @@
|
||||
<?php
|
||||
|
||||
namespace goodboyalex\php_db_components_pack\classes;
|
||||
namespace goodboyalex\php_db_components_pack\models;
|
||||
|
||||
use Closure;
|
||||
use goodboyalex\php_components_pack\extensions\StringExtension;
|
||||
|
||||
/**
|
||||
* Класс свойства класса, реализующего интерфейс IDBItem.
|
||||
@ -25,11 +24,6 @@
|
||||
*/
|
||||
public mixed $Value;
|
||||
|
||||
/**
|
||||
* @var string $FieldName Имя поля в таблице БД.
|
||||
*/
|
||||
public string $FieldName;
|
||||
|
||||
/**
|
||||
* @var DataBaseColumn $Column Информация об ячейке.
|
||||
*/
|
||||
@ -60,14 +54,13 @@
|
||||
*
|
||||
* @param string $name Имя свойства.
|
||||
* @param mixed|null $value Значение свойства (ещё не конвертированное!).
|
||||
* @param string $fieldName Имя поля в таблице БД.
|
||||
* @param DataBaseColumn $column Информация об ячейке.
|
||||
* @param bool $isIgnored Признак того, что свойство игнорируется при сохранении в / загрузке из БД.
|
||||
* @param callable|null $ConvertToDB Конвертер значения свойства в значение поля БД.
|
||||
* @param Closure|null $ConvertFromDB Конвертер значения поля БД в значение свойства.
|
||||
* @param Closure|null $Compare Функция сравнения значений свойства.
|
||||
*/
|
||||
public function __construct (string $name = '', mixed $value = null, string $fieldName = '',
|
||||
public function __construct (string $name = '', mixed $value = null,
|
||||
DataBaseColumn $column = new DataBaseColumn(), bool $isIgnored = false, ?callable $ConvertToDB = null,
|
||||
?Closure $ConvertFromDB = null, ?Closure $Compare = null)
|
||||
{
|
||||
@ -76,8 +69,7 @@
|
||||
$this->Name = $name;
|
||||
// - установка значения свойства (ещё не конвертированного)
|
||||
$this->Value = $value;
|
||||
// - установка имени поля в таблице БД
|
||||
$this->FieldName = StringExtension::IsNullOrWhitespace($fieldName) ? $name : $fieldName;
|
||||
|
||||
// - установка свойств столбца
|
||||
$this->Column = $column;
|
||||
// - установка признака того, что свойство игнорируется при сохранении в / загрузке из БД
|
||||
@ -1,8 +1,9 @@
|
||||
<?php
|
||||
|
||||
namespace goodboyalex\php_db_components_pack\classes;
|
||||
namespace goodboyalex\php_db_components_pack\models;
|
||||
|
||||
use goodboyalex\php_components_pack\classes\Tuple;
|
||||
use goodboyalex\php_db_components_pack\classes\ConditionBuilder;
|
||||
use goodboyalex\php_db_components_pack\enums\DBType;
|
||||
|
||||
/**
|
||||
@ -23,11 +23,11 @@
|
||||
use goodboyalex\php_db_components_pack\attributes\PrimaryKey;
|
||||
use goodboyalex\php_db_components_pack\attributes\Unique;
|
||||
use goodboyalex\php_db_components_pack\classes\ConditionBuilder;
|
||||
use goodboyalex\php_db_components_pack\classes\DataBaseColumn;
|
||||
use goodboyalex\php_db_components_pack\classes\DBItemProperty;
|
||||
use goodboyalex\php_db_components_pack\enums\DBOperation;
|
||||
use goodboyalex\php_db_components_pack\enums\DBType;
|
||||
use goodboyalex\php_db_components_pack\interfaces\IDBItem;
|
||||
use goodboyalex\php_db_components_pack\models\DataBaseColumn;
|
||||
use goodboyalex\php_db_components_pack\models\DBItemProperty;
|
||||
use PDO;
|
||||
use ReflectionClass;
|
||||
use ReflectionException;
|
||||
@ -235,7 +235,7 @@
|
||||
|
||||
|
||||
// - создаю объект свойства
|
||||
$item = new DBItemProperty($key, $value, $fieldName, $columnHeader, $isIgnore, $converterToDB,
|
||||
$item = new DBItemProperty($key, $value, $columnHeader, $isIgnore, $converterToDB,
|
||||
$converterFromDB, $compareFunc);
|
||||
|
||||
// - добавляю в массив
|
||||
@ -294,7 +294,7 @@
|
||||
continue;
|
||||
|
||||
// - получаю значение имени поля
|
||||
$fieldName = $property->FieldName;
|
||||
$fieldName = $property->Column->Name;
|
||||
|
||||
// - преобразую тип
|
||||
$value = call_user_func($property->ConvertToDB, $property->Value);
|
||||
@ -343,10 +343,10 @@
|
||||
continue;
|
||||
|
||||
// - получаю имя поля
|
||||
$fieldName = $property->FieldName;
|
||||
$fieldName = $property->Column->Name;
|
||||
|
||||
// - добавляю в массив отношений
|
||||
$propertiesRelationship[$fieldName] = [$property->Name, $property->ConverterFromDB];
|
||||
$propertiesRelationship[$fieldName] = [$property->Name, $property->ConvertFromDB];
|
||||
}
|
||||
|
||||
// Проходим элементы массива из БД
|
||||
|
||||
@ -8,7 +8,6 @@
|
||||
|
||||
use Exception;
|
||||
use goodboyalex\php_components_pack\classes\ObjectArray;
|
||||
use goodboyalex\php_db_components_pack\classes\DBItemProperty;
|
||||
use goodboyalex\php_db_components_pack\classes\tm_drivers\MSSQLTableManager;
|
||||
use goodboyalex\php_db_components_pack\classes\tm_drivers\MySQLTableManager;
|
||||
use goodboyalex\php_db_components_pack\classes\tm_drivers\OracleDBTableManager;
|
||||
@ -17,6 +16,7 @@
|
||||
use goodboyalex\php_db_components_pack\enums\DBDriver;
|
||||
use goodboyalex\php_db_components_pack\enums\DBOperation;
|
||||
use goodboyalex\php_db_components_pack\interfaces\IDBItem;
|
||||
use goodboyalex\php_db_components_pack\models\DBItemProperty;
|
||||
use PDO;
|
||||
|
||||
/**
|
||||
|
||||
@ -7,9 +7,9 @@
|
||||
|
||||
use Exception;
|
||||
use goodboyalex\php_db_components_pack\classes\ConditionBuilder;
|
||||
use goodboyalex\php_db_components_pack\classes\DBItemProperty;
|
||||
use goodboyalex\php_db_components_pack\enums\DBOperation;
|
||||
use goodboyalex\php_db_components_pack\interfaces\IDBItem;
|
||||
use goodboyalex\php_db_components_pack\models\DBItemProperty;
|
||||
use PDO;
|
||||
|
||||
/**
|
||||
@ -80,11 +80,11 @@
|
||||
/**
|
||||
* Для каждого свойства...
|
||||
*
|
||||
* @var DBItemProperty $property Свойство.
|
||||
* @var \goodboyalex\php_db_components_pack\models\DBItemProperty $property Свойство.
|
||||
*/
|
||||
foreach ($properties as $property) {
|
||||
// ... если это первичный ключ
|
||||
if ($property->IsPrimaryKey)
|
||||
if ($property->Column->IsPrimaryKey)
|
||||
// - то пропускаю его
|
||||
continue;
|
||||
|
||||
|
||||
Loading…
x
Reference in New Issue
Block a user