20250808

README.md

@@ -1,5 +1,94 @@
-# php_db_components_pack
+# 📌🇷🇺 Русская версия
 
-[RU] Набор компонентов для сайта на PHP для работы с базами данных
+---
 
-[EN] A set of components for PHP website for work with database
+## Пакет компонентов для работы с базами данных на PHP
+
+**PhpDbComponentsPack** — это пакет инструментов для эффективного взаимодействия с базами данных на языке
+программирования PHP. Данный пакет предоставляет разнообразные классы и компоненты, предназначенные для облегчения
+работы с базами данных, начиная от низкоуровневых операций и заканчивая высокоуровневыми конструкциями, такими как
+моделирование и обработка данных.
+
+### ✅ Функционал:
+
+- Базовые компоненты для взаимодействия с различными СУБД (MySQL, PostgreSQL, SQLite и др.).
+- Универсальные классы для построения SQL-запросов и выполнения операций с данными.
+- Гибкая настройка полей и моделей данных для использования в базе данных.
+- Поддержка авто-масштабируемых полей и автоинкрементных значений.
+- Средства для анализа и контроля данных.
+
+### ⚙️ Установка и использование:
+
+Установка осуществляется через Composer:
+
+```bash
+composer require goodboyalex/php_db_components_pack
+```
+
+Затем импортируйте нужные классы и начинайте использовать их:
+
+```php
+use goodboyalex\php_db_components_pack\classes\Database;
+use goodboyalex\php_db_components_pack\models\DataBaseColumn;
+
+// Пример использования
+$database = new Database(...);
+```
+
+### 🛠️ Поддерживаемые технологии:
+
+- PHP 8.4+
+- MySQL, PostgreSQL, SQLite, MS SQL
+- Компоненты основаны на PDO и популярных паттернах ORM
+
+### 💬 Вопросы и помощь:
+
+Подробную справку и руководство по работе с пакетом смотрите в [справочном руководстве](./help/index.md).
+
+---
+
+# 📌🇬🇧 English Version
+
+---
+
+## PHP Components Pack for Working with Databases
+
+**PhpDbComponentsPack** is a toolkit designed to simplify working with databases in the PHP programming language. This
+package provides various classes and components aimed at making database operations more efficient, ranging from
+low-level operations to high-level constructs such as data modeling and processing.
+
+### ✅ Features:
+
+- Basic components for interacting with different DBMS (MySQL, PostgreSQL, SQLite, etc.).
+- Universal classes for building SQL queries and performing data operations.
+- Flexible configuration of fields and data models for usage in databases.
+- Support for auto-scalable fields and autoincrement values.
+- Tools for analyzing and controlling data.
+
+### ⚙️ Installation & Usage:
+
+Installation via Composer:
+
+```bash
+composer require goodboyalex/php_db_components_pack
+```
+
+Then import necessary classes and start using them:
+
+```php
+use goodboyalex\php_db_components_pack\classes\Database;
+use goodboyalex\php_db_components_pack\models\DataBaseColumn;
+
+// Example usage
+$database = new Database(...);
+```
+
+### 🛠️ Supported Technologies:
+
+- PHP 8.4+
+- MySQL, PostgreSQL, SQLite, MS SQL
+- Components based on PDO and popular ORM patterns
+
+### 💬 Questions & Help:
+
+For detailed reference and user guide, please refer to the [reference manual](./help/index.md) (russian version only).

help/basic_usage/create_table.md

@@ -0,0 +1,78 @@
+# Создание таблицы
+
+Итак, в [прошлой статье](usage_preparation.md) мы создали класс для работы с базой данных. Далее, мы научимся создавать
+таблицу в базе данных.
+
+Перед созданием таблицы, нужно написать класс-модель, реализующий
+интерфейс [IDBItem](../class_desc/interfaces/IDBItem.md) и с помощью атрибутов:
+
+- [AutoIncrement](../class_desc/attributes/AutoIncrement.md),
+- [Check](../class_desc/attributes/Check.md),
+- [Compare](../class_desc/attributes/Compare.md),
+- [ConvertToDB](../class_desc/attributes/ConvertToDB.md),
+- [DataType](../class_desc/attributes/DataType.md),
+- [DefaultValue](../class_desc/attributes/DefaultValue.md),
+- [FieldName](../class_desc/attributes/FieldName.md),
+- [ForeignKey](../class_desc/attributes/ForeignKey.md),
+- [IgnoredInDB](../class_desc/attributes/IgnoredInDB.md),
+- [NotNull](../class_desc/attributes/NotNull.md),
+- [PrimaryKey](../class_desc/attributes/PrimaryKey.md),
+- [Unique](../class_desc/attributes/Unique.md)
+
+настроить столбцы и поля.
+
+Создадим далее макет класса, описывающего пользователя сайта.
+
+```php
+<?php
+
+namespace App\Models;
+
+use goodboyalex\php_db_components_pack\attributes\AutoIncrement;
+use goodboyalex\php_db_components_pack\attributes\FieldName;
+use goodboyalex\php_db_components_pack\attributes\NotNull;
+use goodboyalex\php_db_components_pack\attributes\PrimaryKey;
+use goodboyalex\php_db_components_pack\attributes\Unique;
+use goodboyalex\php_db_components_pack\interfaces\IDBItem;
+
+class User implements IDBItem
+{
+    /**
+    * @var int $Id Идентификатор пользователя.
+    */
+    #[PrimaryKey, NotNull, AutoIncrement, FieldName('id'), Unique]
+    public int $Id = 0;
+    
+    /**
+    * @var string $Name Имя пользователя.
+    */
+    #[NotNull, FieldName('user_name')]
+    public string $Name = '';
+    
+    /**
+    * @var string $Email Почта пользователя. 
+    */
+    #[NotNull, FieldName('user_mail'), Unique]
+    public string $Email = '';
+}
+```
+
+Итак, у нас в таблице должно быть **3 столбца**:
+
+| id | user_name | user_mail |
+|:--:|:---------:|:---------:|
+| -  |     -     |     -     |
+
+Значения во всех столбцах, кроме `user_name` должны быть уникальными, во всех столбцах не пустыми, а первичным ключом
+таблицы является столбец `id` с автозаполнением.
+
+Теперь давайте создадим таблицу `user`:
+
+```php
+if (!$db->CreateTable('user', "\\App\\Models\\User"))
+    throw new PDOException("Ошибка создания таблицы: users");
+```
+
+Таблица создана.
+
+[Предыдущий пункт](usage_preparation.md) | [На главную](../index.md) | [Следующий пункт](insert_data.md)

help/basic_usage/insert_data.md

@@ -0,0 +1,63 @@
+# Вставка данных
+
+Итак, в [прошлой статье](create_table.md) мы создали таблицу `users` в базе данных. Но она пока пуста. Далее, мы
+научимся добавлять данные в неё.
+
+Для добавления одной строки нужно воспользоваться
+методом [Insert](../class_desc/classes/Database.md).
+
+Создадим далее макет класса, описывающего пользователя сайта.
+
+```php
+<?php
+
+namespace App\Models;
+
+use goodboyalex\php_db_components_pack\attributes\AutoIncrement;
+use goodboyalex\php_db_components_pack\attributes\FieldName;
+use goodboyalex\php_db_components_pack\attributes\NotNull;
+use goodboyalex\php_db_components_pack\attributes\PrimaryKey;
+use goodboyalex\php_db_components_pack\attributes\Unique;
+use goodboyalex\php_db_components_pack\interfaces\IDBItem;
+
+class User implements IDBItem
+{
+    /**
+    * @var int $Id Идентификатор пользователя.
+    */
+    #[PrimaryKey, NotNull, AutoIncrement, FieldName('id'), Unique]
+    public int $Id = 0;
+    
+    /**
+    * @var string $Name Имя пользователя.
+    */
+    #[NotNull, FieldName('user_name')]
+    public string $Name = '';
+    
+    /**
+    * @var string $Email Почта пользователя. 
+    */
+    #[NotNull, FieldName('user_mail'), Unique]
+    public string $Email = '';
+}
+```
+
+Итак, у нас в таблице должно быть **3 столбца**:
+
+| id | user_name | user_mail |
+|:--:|:---------:|:---------:|
+| -  |     -     |     -     |
+
+Значения во всех столбцах, кроме `user_name` должны быть уникальными, во всех столбцах не пустыми, а первичным ключом
+таблицы является столбец `id` с автозаполнением.
+
+Теперь давайте создадим таблицу `user`:
+
+```php
+if (!$db->CreateTable('user', "\\App\\Models\\User"))
+    throw new PDOException("Ошибка создания таблицы: users");
+```
+
+Таблица создана.
+
+[Предыдущий пункт](create_table.md) | [На главную](../index.md) | [Следующий пункт](../index.md)

help/basic_usage/usage_preparation.md

@@ -31,4 +31,4 @@ $db = new Database($db_config, $onException);
 ```
 
 
-[На главную](../index.md) | [Следующий пункт](../index.md)
+[На главную](../index.md) | [Следующий пункт](create_table.md)

help/index.md

@@ -8,7 +8,8 @@
 
 ## Базовое использование:
 
-- [Подготовка к использованию](basic_usage/usage_preparation.md)
+1. [x] [Подготовка к использованию](basic_usage/usage_preparation.md)
+2. [x] [Создание таблицы](basic_usage/create_table.md)
 
 ## Описание интерфейсов, классов и перечислений: