20250807

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)