README

📦 Описание

Laravel Favorites — это универсальный модуль для создания полиморфных связей между владельцем и любыми избираемыми сущностями. Позволяет одному владельцу (профилю, пользователю и т.п.) добавлять в избранное объекты разных моделей, таких как товары, статьи, профили, комментарии и др.

Пакет поддерживает:

• организацию избранного по папкам с уникальными названиями,
• работу с UUID и timestamps "из коробки",
• строгую привязку избранного к конкретному владельцу.

🎯 Подходит для

• 💼 Электронной коммерции — покупатель может сохранять избранные товары, бренды или подборки.
• 📚 Контент-платформ — читатель может добавлять в избранное статьи, авторов или хештеги.
• 📊 B2B/CRM систем — пользователь может группировать клиентов, документы или сделки в "избранное" для быстрого доступа.

🧭 Оглавление

• Системные требования
• Установка
• Как использовать
  • ➕ Добавление в избранное
  • ➖ Удаление из избранного
  • 📂 Работа с папками
  • 📄 Получение избранного
• Кастомизация
  • 🔄 Пример: замена логики добавления
• 🤝 Сотрудничество
• 📄 Лицензия

🛠 Системные требования

• PHP 8.1 или выше
• Laravel 10.x или выше
• Composer для управления зависимостями

📥 Установка

Установите пакет через Composer:

composer require alyakin/favorites

Файл конфигурации отсутствует — модуль готов к использованию сразу после установки и регистрации провайдера.

⚙️ Как использовать

Сервисы можно получить через сервис-контейнер Laravel:

use \Alyakin\Favorites\Services\{FavoriteService, FavoriteFolderService};

$favoritesService = app(FavoriteService::class);
$folderService = app(FavoriteFolderService::class);

Ниже представлены базовые сценарии использования.

➕ Добавление в избранное

// Добавить объект в избранное
$favoritesService->addToFavorites($ownerId, $model);

// Добавить в конкретную папку:
$favoritesService->addToFavorites($ownerId, $model, 'read later');

➖ Удаление из избранного

// Удалить объект из избранного:
$favoritesService->removeFromFavorites($ownerId, $model);

📂 Работа с папками

// Создать папку
$folderService->createFolder($ownerId, 'Папка');

// Переименовать папку
$folderService->renameFolder($ownerId, $folderId, $newName);

// Переместить элемент в папку:
$favoritesService->moveToFolder($favoriteId, $folderId);

// Получить все папки владельца:
$folderService->getAllFoldersForOwner($ownerId);

// Удалить папку:
// ⚠️ ВНИМАНИЕ! При удалении папки будут также удалены все избранные элементы внутри неё.
$folderService->deleteFolder($ownerId, $folderId);

📄 Получение избранного

// Получить все избранные элементы владельца:
$favoritesService->getFavorites($ownerId);

// Получить избранные в конкретной папке:
$favoritesService->getFavorites($ownerId, 'funy');

// Проверить, находится ли объект в избранном:
$favoritesService->isFavorited($ownerId, $model);

🎛 Кастомизация

Пакет спроектирован с учетом расширяемости и адаптации под проект.

• Вы можете заменить модель владельца, передавая любой UUID-совместимый ownerId.
• Папки не являются обязательными — можно использовать избранное и без них.
• Вся бизнес-логика изолирована в сервисах (FavoriteService, FavoriteFolderService) и может быть легко расширена или переопределена через DI-контейнер.
• Названия таблиц, столбцов и ключей соответствуют общим стандартам Laravel и могут быть переопределены при необходимости.

🔄 Пример: замена логики добавления

Создайте свой кастомный сервис:

class CustomFavoriteService extends \Alyakin\Favorites\Services\FavoriteService {
    // ...
}

Переопределите нужный метод:

public function addToFavorites(string $ownerId, Model $model, ?string $folderName = null): Favorite
{
    // своя логика — например, логирование
    \Log::info('Добавление в избранное', ['owner_id' => $ownerId]);

    return parent::addToFavorites($ownerId, $model, $folderName);
}

Зарегистрируйте в AppServiceProvider:

$this->app->bind(
    \Alyakin\Favorites\Services\FavoriteService::class,
    \App\Services\CustomFavoriteService::class
);

Теперь Laravel будет использовать вашу реализацию вместо базовой.

🤝 Сотрудничество

Мы открыты к предложениям и улучшениям!

• Сообщайте об ошибках через Issues
• Присылайте Pull Requests с улучшениями
• Предлагайте идеи по расширению функциональности

📄 Лицензия

This package is open-source and available under the MIT License.