diff --git a/help/class_desc/attributes/DefaultValue.md b/help/class_desc/attributes/DefaultValue.md new file mode 100644 index 0000000..cc32e27 --- /dev/null +++ b/help/class_desc/attributes/DefaultValue.md @@ -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) \ No newline at end of file diff --git a/help/class_desc/attributes/DefaultValue.php b/help/class_desc/attributes/DefaultValue.php deleted file mode 100644 index 37cda52..0000000 --- a/help/class_desc/attributes/DefaultValue.php +++ /dev/null @@ -1,37 +0,0 @@ -Value = $value; - } - } \ No newline at end of file diff --git a/help/class_desc/attributes/FieldName.md b/help/class_desc/attributes/FieldName.md new file mode 100644 index 0000000..1aad753 --- /dev/null +++ b/help/class_desc/attributes/FieldName.md @@ -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) \ No newline at end of file diff --git a/help/class_desc/attributes/FieldName.php b/help/class_desc/attributes/FieldName.php deleted file mode 100644 index 96fe632..0000000 --- a/help/class_desc/attributes/FieldName.php +++ /dev/null @@ -1,37 +0,0 @@ -FieldName = $fieldName; - } - } \ No newline at end of file diff --git a/help/class_desc/attributes/ForeignKey.md b/help/class_desc/attributes/ForeignKey.md new file mode 100644 index 0000000..30dd05b --- /dev/null +++ b/help/class_desc/attributes/ForeignKey.md @@ -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) \ No newline at end of file diff --git a/help/class_desc/attributes/ForeignKey.php b/help/class_desc/attributes/ForeignKey.php deleted file mode 100644 index df29b7b..0000000 --- a/help/class_desc/attributes/ForeignKey.php +++ /dev/null @@ -1,44 +0,0 @@ -TableName = $table; - $this->FieldName = $fieldName; - } - } \ No newline at end of file diff --git a/help/class_desc/attributes/IgnoredInDB.md b/help/class_desc/attributes/IgnoredInDB.md new file mode 100644 index 0000000..8c4edaa --- /dev/null +++ b/help/class_desc/attributes/IgnoredInDB.md @@ -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) \ No newline at end of file diff --git a/help/class_desc/attributes/IgnoredInDB.php b/help/class_desc/attributes/IgnoredInDB.php deleted file mode 100644 index d1d6878..0000000 --- a/help/class_desc/attributes/IgnoredInDB.php +++ /dev/null @@ -1,47 +0,0 @@ -IgnoredOperations = new ObjectArray($ignoredOperations); - } - } \ No newline at end of file diff --git a/help/class_desc/attributes/NotNull.md b/help/class_desc/attributes/NotNull.md new file mode 100644 index 0000000..465321c --- /dev/null +++ b/help/class_desc/attributes/NotNull.md @@ -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) \ No newline at end of file diff --git a/help/class_desc/attributes/NotNull.php b/help/class_desc/attributes/NotNull.php deleted file mode 100644 index ff32b90..0000000 --- a/help/class_desc/attributes/NotNull.php +++ /dev/null @@ -1,30 +0,0 @@ -`, `<`, `>`, `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) \ No newline at end of file diff --git a/help/class_desc/classes/ConditionBuilder.md b/help/class_desc/classes/ConditionBuilder.md new file mode 100644 index 0000000..575ea92 --- /dev/null +++ b/help/class_desc/classes/ConditionBuilder.md @@ -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) \ No newline at end of file diff --git a/help/class_desc/classes/ConditionGroup.md b/help/class_desc/classes/ConditionGroup.md new file mode 100644 index 0000000..343fa2a --- /dev/null +++ b/help/class_desc/classes/ConditionGroup.md @@ -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) \ No newline at end of file diff --git a/help/class_desc/interfaces/IDBItem.md b/help/class_desc/interfaces/IDBItem.md index a557935..7e57300 100644 --- a/help/class_desc/interfaces/IDBItem.md +++ b/help/class_desc/interfaces/IDBItem.md @@ -58,7 +58,7 @@ class User implements IDBItem /** * @var string $Email Почта пользователя. */ - #[NotNull, FieldName('user_mail')] + #[NotNull, FieldName('user_mail'), Unique] public string $Email = ''; } ``` diff --git a/help/class_desc/models/DBConfig.md b/help/class_desc/models/DBConfig.md index 608364c..acc9bb4 100644 --- a/help/class_desc/models/DBConfig.md +++ b/help/class_desc/models/DBConfig.md @@ -1,4 +1,4 @@ -# Класс `DBConfig` +# Модель `DBConfig` ## Описание diff --git a/help/class_desc/models/DBItemProperty.md b/help/class_desc/models/DBItemProperty.md new file mode 100644 index 0000000..d3b6d63 --- /dev/null +++ b/help/class_desc/models/DBItemProperty.md @@ -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) \ No newline at end of file diff --git a/help/class_desc/models/DataBaseColumn.md b/help/class_desc/models/DataBaseColumn.md new file mode 100644 index 0000000..16e0c47 --- /dev/null +++ b/help/class_desc/models/DataBaseColumn.md @@ -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) \ No newline at end of file diff --git a/help/index.md b/help/index.md index 9cee6e1..d9f4c86 100644 --- a/help/index.md +++ b/help/index.md @@ -14,7 +14,9 @@ ### Модели +- [DataBaseColumn](class_desc/models/DataBaseColumn.md) - [DBConfig](class_desc/models/DBConfig.md) +- [DBItemProperty](class_desc/models/DBItemProperty.md) ### Перечисления diff --git a/sources/attributes/IgnoredInDB.php b/sources/attributes/IgnoredInDB.php index d1d6878..2b2888b 100644 --- a/sources/attributes/IgnoredInDB.php +++ b/sources/attributes/IgnoredInDB.php @@ -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 ]; // Инициализируем массив diff --git a/sources/classes/tm_drivers/MSSQLTableManager.php b/sources/classes/tm_drivers/MSSQLTableManager.php index 815401a..b1ddacf 100644 --- a/sources/classes/tm_drivers/MSSQLTableManager.php +++ b/sources/classes/tm_drivers/MSSQLTableManager.php @@ -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; /** diff --git a/sources/classes/tm_drivers/MySQLTableManager.php b/sources/classes/tm_drivers/MySQLTableManager.php index 1d9a781..9540890 100644 --- a/sources/classes/tm_drivers/MySQLTableManager.php +++ b/sources/classes/tm_drivers/MySQLTableManager.php @@ -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; /** diff --git a/sources/classes/tm_drivers/OracleDBTableManager.php b/sources/classes/tm_drivers/OracleDBTableManager.php index 3c4828d..0d89d04 100644 --- a/sources/classes/tm_drivers/OracleDBTableManager.php +++ b/sources/classes/tm_drivers/OracleDBTableManager.php @@ -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; diff --git a/sources/classes/tm_drivers/PostgreSQLTableManager.php b/sources/classes/tm_drivers/PostgreSQLTableManager.php index 8b1a110..8a627bf 100644 --- a/sources/classes/tm_drivers/PostgreSQLTableManager.php +++ b/sources/classes/tm_drivers/PostgreSQLTableManager.php @@ -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; diff --git a/sources/classes/tm_drivers/SQLiteTableManager.php b/sources/classes/tm_drivers/SQLiteTableManager.php index 30d496f..95e05a8 100644 --- a/sources/classes/tm_drivers/SQLiteTableManager.php +++ b/sources/classes/tm_drivers/SQLiteTableManager.php @@ -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; diff --git a/sources/interfaces/ITableManager.php b/sources/interfaces/ITableManager.php index 65d3e9b..6a05197 100644 --- a/sources/interfaces/ITableManager.php +++ b/sources/interfaces/ITableManager.php @@ -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-представление столбца. */ diff --git a/sources/classes/DBItemProperty.php b/sources/models/DBItemProperty.php similarity index 87% rename from sources/classes/DBItemProperty.php rename to sources/models/DBItemProperty.php index c37d73a..82ec2f7 100644 --- a/sources/classes/DBItemProperty.php +++ b/sources/models/DBItemProperty.php @@ -1,9 +1,8 @@ Name = $name; // - установка значения свойства (ещё не конвертированного) $this->Value = $value; - // - установка имени поля в таблице БД - $this->FieldName = StringExtension::IsNullOrWhitespace($fieldName) ? $name : $fieldName; + // - установка свойств столбца $this->Column = $column; // - установка признака того, что свойство игнорируется при сохранении в / загрузке из БД diff --git a/sources/classes/DataBaseColumn.php b/sources/models/DataBaseColumn.php similarity index 97% rename from sources/classes/DataBaseColumn.php rename to sources/models/DataBaseColumn.php index e12fe93..10da02d 100644 --- a/sources/classes/DataBaseColumn.php +++ b/sources/models/DataBaseColumn.php @@ -1,8 +1,9 @@ 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]; } // Проходим элементы массива из БД diff --git a/sources/traits/Database/DatabaseTableManagement.php b/sources/traits/Database/DatabaseTableManagement.php index d242e5c..f405ade 100644 --- a/sources/traits/Database/DatabaseTableManagement.php +++ b/sources/traits/Database/DatabaseTableManagement.php @@ -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; /** diff --git a/sources/traits/Database/DatabaseUpdate.php b/sources/traits/Database/DatabaseUpdate.php index c1b926a..7c303ad 100644 --- a/sources/traits/Database/DatabaseUpdate.php +++ b/sources/traits/Database/DatabaseUpdate.php @@ -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;