Добавлены строки документации

upload/engine/inc/maharder/_includes/classes/DataManager.php

@@ -12,6 +12,12 @@
 // Код распространяется по лицензии MIT                         =
 //===============================================================
 
+/**
+ * Абстрактный класс DataManager, представляющий базовый функционал для менеджеров данных.
+ *
+ * Класс служит основой для реализации логики работы с данными, например, взаимодействия с базой данных.
+ * Конкретные реализации должны быть определены в наследниках этого класса.
+ */
 
 abstract class DataManager {
 	/**

upload/engine/inc/maharder/_includes/classes/LogGenerator.php

@@ -19,6 +19,12 @@
 	require_once (DLEPlugins::Check(MH_INCLUDES . '/extras/paths.php'));
 }
 
+/**
+ * Абстрактный класс для управления процессом логирования. Класс включает в себя базовый функционал для записи логов
+ * в файлы, базу данных и отправки уведомлений в Telegram.
+ *
+ * @since 170.2.10
+ */
 abstract class LogGenerator {
 
 	/**

upload/engine/inc/maharder/_includes/classes/MhAjax.php

@@ -1,16 +1,37 @@
 <?php
 
 
-
+/**
+ * Вспомогательный класс для работы с системой управления DLE (Data Life Engine),
+ * загрузкой данных и проверкой ресурсов. Содержит набор методов, облегчающих
+ * выполнение AJAX-запросов, валидацию и взаимодействие с внешними и внутренними ресурсами.
+ *
+ */
 class MhAjax {
 	use AssetsChecker;
 	use UpdatesChecker;
 	use DataLoader;
 	use DleData;
 
+	/**
+	 * Конструктор класса MhAjax.
+	 *
+	 * Инициализирует объект класса, содержащего вспомогательные методы
+	 * для работы с DLE, загрузкой данных и проверкой ресурсов.
+	 */
 	public function __construct() {
 	}
 
+	/**
+	 * Возвращает URL панели администратора DLE.
+	 *
+	 * Использует глобальный массив настроек DLE `$config` для формирования полного URL.
+	 * Формат возвращаемого значения: http(s)://your-site.com/admin_path.
+	 *
+	 * @global array $config Глобальный массив конфигурации DLE.
+	 * @return string Конечный URL панели администратора DLE.
+	 */
+
 	public function getDleUrl() {
 		global $config;
 

upload/engine/inc/maharder/_includes/classes/TwigFilter.php

@@ -4,12 +4,18 @@
 use Cycle\Database\Query\SelectQuery;
 use JetBrains\PhpStorm\ExpectedValues;
 
+/**
+ * Класс для создания и обработки фильтров данных, а также для работы с сортировкой и стандартными фильтрами для шаблонов.
+ */
 class TwigFilter {
 	private RepositoryInterface $repository;
 
 	/**
-	 * @param RepositoryInterface $repository
+	 * Конструктор класса.
+	 *
+	 * @param RepositoryInterface $repository Репозиторий, используемый для получения данных.
 	 */
+
 	public function __construct(RepositoryInterface $repository) { $this->setRepository($repository); }
 
 	/**
@@ -62,10 +68,10 @@ public function createFilter(
 	 * @param string $select Имя SQL-колонки, используемой в запросе для группировки данных.
 	 *
 	 * @return array Ассоциативный массив, где ключи — значения фильтров, а значения — отображаемые имена фильтров.
-	 *
-	 * @see __ Используется для локализации первой строки массива фильтров.
+	 * @throws \Throwable
 	 * @see translate Вызванный косвенно через функцию __.
 	 * @see getRepository Используется для получения данных из базы через методы репозитория.
+	 * @see __ Используется для локализации первой строки массива фильтров.
 	 */
 	public function createFilterChoices($name, $select): array {
 		$filter = [

upload/engine/inc/maharder/_includes/database/BasisModel.php

@@ -17,29 +17,93 @@
 use Cycle\Annotated\Annotation\Entity;
 use Cycle\Annotated\Annotation\Table\Index;
 
+/**
+ * Базовый абстрактный класс модели, представляющий типовую сущность базы данных.
+ * Класс используется для создания типовых моделей с общими свойствами, такими как
+ * уникальный идентификатор (`id`), дата создания (`createdAt`) и дата последнего обновления (`updatedAt`).
+ * Предназначен для расширения в конкретных классах моделей, которые реализуют бизнес-логику
+ * и определяют дополнительные свойства и методы.
+ * ## Свойства:
+ * - **`id`** — уникальный первичный ключ записи.
+ * - **`createdAt`** — дата и время создания записи.
+ * - **`updatedAt`** — дата последнего обновления записи (null, если данных об изменениях нет).
+ * ## Методы:
+ * Класс предоставляет доступные методы для получения базовой информации о записи:
+ * - `getId()` — возвращает уникальный идентификатор сущности.
+ * - `getCreatedAt()` — возвращает дату и время создания записи.
+ * - `getUpdatedAt()` — возвращает дату последнего обновления или null, если обновления не было.
+ * - `getColumnVal(string $name)` — возвращает значение конкретного столбца по его имени (реализуется в наследниках).
+ * ## Аннотации:
+ * Класс использует аннотации для указания схемы базы данных с помощью библиотеки `Cycle ORM`.
+ * Например:
+ * - `#[Column()]` определяет параметры поля таблицы.
+ * - `#[Index()]` задаёт индексированные столбцы (например, `created_at` для быстрого поиска).
+ * ## Расширяемость:
+ * - Класс **абстрактный**. Для его использования необходимо создать наследника и, как минимум,
+ * реализовать метод `getColumnVal()`, который позволяет получить значение столбца.
+ */
 #[Index(columns: ['created_at'])]
 abstract class BasisModel {
+	/**
+	 * ID сущности (уникальный первичный ключ).
+	 *
+	 * @var int $id
+	 */
 	#[Column(type: 'bigPrimary', primary: true, autoincrement: true)]
 	protected int $id;
 
+	/**
+	 * Дата и время создания записи. Автоматически проставляется при создании.
+	 *
+	 * @var \DateTimeImmutable $createdAt
+	 */
 	#[Column(type: 'datetime', default: 'CURRENT_TIMESTAMP')]
 	protected \DateTimeImmutable $createdAt;
 
+	/**
+	 * Дата и время последнего обновления записи. Может быть равна null.
+	 * Автоматически обновляется при изменении записи.
+	 *
+	 * @var \DateTimeImmutable|null $updatedAt
+	 */
 	#[Column(type: 'datetime', nullable: true, default: 'CURRENT_TIMESTAMP')]
 	protected ?\DateTimeImmutable $updatedAt = null;
 
+	/**
+	 * Получить уникальный идентификатор сущности.
+	 *
+	 * @return int Уникальный идентификатор сущности.
+	 */
 	public function getId(): int {
 		return $this->id;
 	}
 
+	/**
+	 * Получить дату и время создания записи.
+	 *
+	 * @return \DateTimeImmutable Дата и время создания записи.
+	 */
 	public function getCreatedAt(): DateTimeImmutable {
 		return $this->createdAt;
 	}
 
+	/**
+	 * Получить дату и время последнего обновления записи, если доступно.
+	 *
+	 * @return \DateTimeImmutable|null Дата и время последнего обновления или null, если обновления не было.
+	 */
 	public function getUpdatedAt(): ?DateTimeImmutable {
 		return $this->updatedAt;
 	}
 
+	/**
+	 * Получить значение столбца по его имени.
+	 *
+	 * @param string $name Имя столбца.
+	 *
+	 * @return mixed Значение столбца.
+	 * @throws \InvalidArgumentException Если имя столбца не найдено.
+	 */
 	abstract public function getColumnVal(string $name): mixed;
 
 }

upload/engine/inc/maharder/_includes/database/BasisRepository.php

@@ -17,19 +17,47 @@
 use Cycle\Schema\Definition\Entity;
 
 
+/**
+ * Базовый репозиторий для работы с сущностями.
+ * Предоставляет методы для получения первой, последней записей, лимитированного списка и общего количества элементов.
+ */
 class BasisRepository extends Repository implements RepositoryInterface {
 
-	public function getFirst() : ?Entity {
+	/**
+	 * Получает первую запись из базы данных, отсортированную по колонке `created_at` по возрастанию.
+	 *
+	 * @return Entity|null Возвращает первую сущность или null, если записи отсутствуют.
+	 */
+	public function getFirst(): ?Entity {
 		return $this->select()->orderBy('created_at')->limit(1)->fetchOne();
 	}
-	public function getLast() : ?Entity {
+
+	/**
+	 * Получает последнюю запись из базы данных, отсортированную по колонке `created_at` по убыванию.
+	 *
+	 * @return Entity|null Возвращает последнюю сущность или null, если записи отсутствуют.
+	 */
+	public function getLast(): ?Entity {
 		return $this->select()->orderBy('created_at', 'DESC')->limit(1)->fetchOne();
 	}
 
+	/**
+	 * Получает список записей, лимитированный заданным количеством и смещением.
+	 *
+	 * @param int $total Количество записей для выборки.
+	 * @param int $start Смещение начала выборки. По умолчанию - 0.
+	 *
+	 * @return array Массив сущностей, соответствующих указанным критериям.
+	 */
 	public function limit(int $total, int $start = 0): array {
 		return $this->select()->limit($total)->offset($start)->fetchAll();
 	}
 
+	/**
+	 * Получает общее количество записей в базе данных.
+	 *
+	 * @return int Количество записей.
+	 */
 	public function total(): int {
 		return $this->select()->count();
 	}