Правила нейминга в PHP Laravel: Полное Руководство

В мире разработки программного обеспечения стандарты и соглашения играют ключевую роль в обеспечении читаемости, поддерживаемости и расширяемости кода. Laravel, один из самых популярных PHP-фреймворков, придерживается определенных правил нейминга, которые помогают разработчикам создавать чистый и организованный код. В этой статье мы подробно рассмотрим правила нейминга в Laravel, включая основные пункты и их дополнительные подпункты, чтобы вы могли следовать лучшим практикам при разработке своих проектов.

Классы и модели:

• Стиль именования:
  • Имена классов и моделей пишутся в стиле StudlyCase (каждое слово с заглавной буквы без разделителей), например, User, ArticleCategory.
• Единственное число:
  • Модели называются в единственном числе, чтобы отражать одну сущность, например, User, Comment.
• Неймспейсы:
  • Классы размещаются в соответствующих пространствах имен, например, модели в App\Models.
• Абстрактные классы и интерфейсы:
  • Имена могут содержать префиксы или суффиксы, такие как Base, Interface, например, BaseModel, UserInterface.

Контроллеры:

• Суффикс Controller:
  • Все контроллеры заканчиваются на Controller, например, UserController, PostController.
• Расположение:
  • Контроллеры находятся в директории App\Http\Controllers.
• Ресурсные контроллеры:
  • Используют стандартные методы CRUD: index, create, store, show, edit, update, destroy.
• Поддиректории:
  • Для организации могут использоваться поддиректории, например, Admin\UserController.

Методы контроллеров:

• Стиль именования:
  • Имена методов пишутся в camelCase, начиная с маленькой буквы.
• Стандартные методы:
  • Для ресурсных контроллеров используются стандартные имена методов.
• Дополнительные методы:
  • Имена должны быть описательными, например, searchUsers, exportData.

Маршруты (Routes):

• Именованные маршруты:
  • Используются в snake_case, например, user_profile, article_show.
• Группировка маршрутов:
  • Маршруты могут быть сгруппированы по префиксам или пространствам имен.
• Middleware в маршрутах:
  • Имена middleware пишутся в camelCase.

Переменные и методы:

• Переменные:
  • Имена пишутся в camelCase, например, $userName, $totalCount.
• Методы:
  • Имена методов функций и классов также в camelCase.
• Осмысленные имена:
  • Имена должны отражать суть переменной или метода.

Константы:

• Стиль именования:
  • Имена в верхнем регистре с подчеркиваниями, например, MAX_ATTEMPTS, API_KEY.
• Глобальные константы:
  • Избегайте глобальных констант, используйте классы для их определения.
• Константы классов:
  • Определяются внутри класса с ключевым словом const.

Таблицы базы данных:

• Имена таблиц:
  • В snake_case и во множественном числе, например, users, blog_posts.
• Поля таблиц:
  • Имена полей в snake_case, например, first_name, created_at.
• Внешние ключи:
  • Имена внешних ключей обычно в формате singular_model_id, например, user_id.

Миграции:

• Имена файлов:
  • Начинаются с временной метки и описывают действие, например, 2023_10_12_000000_create_users_table.php.
• Классы миграций:
  • В StudlyCase, отражают действие, например, CreateUsersTable.
• Методы:
  • Используются стандартные методы up и down.

Связи (Relationships):

• Имена методов:
  • В camelCase, соответствуют имени связанной модели, например, posts, comments.
• Типы связей:
  • hasOne, hasMany, belongsTo, belongsToMany.
• Имена промежуточных таблиц:
  • Для связей many-to-many, например, role_user.

Виды (Views):

• Имена файлов:
  • В snake_case, например, index.blade.php, user_profile.blade.php.
• Структура директорий:
  • Используйте поддиректории для организации, например, users/profile.blade.php.
• Компоненты:
  • Имена компонентов в kebab-case, например, <x-alert-message />.

Middleware и Form Requests:

• Имена Middleware:
  • В StudlyCase, например, CheckAge, Authenticate.
• Имена Form Requests:
  • Заканчиваются на Request, например, StorePostRequest.
• Расположение:
  • Middleware в App\Http\Middleware, Form Requests в App\Http\Requests.

Пространства имен (Namespaces):

• Структура:
  • Соответствуют структуре каталогов, например, App\Http\Controllers.
• Стиль именования:
  • В StudlyCase.
• Использование:
  • Упрощает автозагрузку классов.

Конфигурационные файлы:

• Имена файлов:
  • В snake_case, например, app.php, database.php.
• Ключи конфигурации:
  • Также в snake_case.
• Константы конфигурации:
  • Должны быть осмысленными, например, default_timeout.

События и слушатели (Events and Listeners):

• Имена событий:
  • В StudlyCase, отражают событие, например, UserRegistered.
• Имена слушателей:
  • Заканчиваются на Listener, например, SendWelcomeEmail.
• Расположение:
  • События в App\Events, слушатели в App\Listeners.

Пакеты Composer:

• Имена пакетов:
  • Формат vendor/package-name в kebab-case, например, laravel/framework.
• Версионирование:
  • Используйте семантическое версионирование.
• Автозагрузка:
  • Следуйте стандарту PSR-4 для автозагрузки.

PSR Стандарты:

• PSR-1:
  • Базовый стандарт кодирования для PHP.
• PSR-12:
  • Расширение PSR-1, включает рекомендации по форматированию.
• Инструменты:
  • Используйте PHP_CodeSniffer для проверки соответствия.

Документация и комментарии:

• PHPDoc:
  • Используйте для документирования классов и методов.
• Стиль комментариев:
  • Ясные и краткие комментарии.
• Теги:
  • Стандартные теги @param, @return, @throws.

Исключения и ошибки:

• Имена исключений:
  • Заканчиваются на Exception, например, InvalidUserException.
• Расположение:
  • В директории App\Exceptions.
• Сообщения об ошибках:
  • Должны быть информативными.

Сервисы и репозитории:

• Имена сервисов:
  • В StudlyCase, например, PaymentService.
• Имена репозиториев:
  • Заканчиваются на Repository, например, UserRepository.
• Расположение:
  • Сервисы в App\Services, репозитории в App\Repositories.

Команды и консольные команды:

• Имена классов:
  • Заканчиваются на Command, например, ClearCacheCommand.
• Имена методов:
  • Основной метод handle().
• Имена команд:
  • В kebab-case, например, cache:clear.

Провайдеры услуг (Service Providers):

• Имена классов:
  • Заканчиваются на ServiceProvider, например, AuthServiceProvider.
• Расположение:
  • В App\Providers.
• Методы:
  • Стандартные методы register() и boot().

Шаблоны Blade:

• Директивы Blade:
  • Имена пользовательских директив в snake_case.
• Композеры видов:
  • Имена классов в StudlyCase, например, ProfileComposer.
• Расположение:
  • В App\Http\View\Composers.

API и ресурсные контроллеры:

• Имена маршрутов API:
  • Используйте префиксы версий, например, /api/v1/users.
• Контроллеры API:
  • Можно размещать в App\Http\Controllers\Api.
• Имена методов:
  • Стандартные методы для RESTful API.

Тестирование:

• Имена классов тестов:
  • Заканчиваются на Test, например, UserTest.
• Методы тестов:
  • Начинаются с test, например, testUserCreation().
• Расположение:
  • В tests\Unit и tests\Feature.

Помощники (Helpers):

• Функции-помощники:
  • Имена в snake_case, например, format_date().
• Расположение:
  • В файлах, подключаемых через Composer или автозагрузку.
• Осмысленные имена:
  • Должны ясно отражать функциональность.

Фасады (Facades):

• Имена классов:
  • В StudlyCase, например, Cache, Auth.
• Расположение:
  • В Illuminate\Support\Facades или App\Facades.
• Использование:
  • Обеспечивают статический интерфейс к классам в контейнере службы.

Переводы и локализация:

• Файлы переводов:
  • Имена в snake_case, например, validation.php.
• Ключи переводов:
  • Структурированы и осмысленны, например, auth.failed.
• Расположение:
  • В директории resources/lang/{locale}.

Почтовые уведомления (Mailables):

• Имена классов:
  • В StudlyCase, например, OrderShipped.
• Расположение:
  • В App\Mail.
• Методы:
  • Стандартные методы build().

Уведомления (Notifications):

• Имена классов:
  • В StudlyCase, например, ResetPasswordNotification.
• Расположение:
  • В App\Notifications.
• Каналы уведомлений:
  • Имена методов в camelCase, например, toMail(), toDatabase().

Глобальные вспомогательные функции:

• Имена функций:
  • В snake_case, например, abort_if(), config().
• Избегание конфликтов:
  • Не переопределяйте существующие функции PHP.
• Документация:
  • Обязательно документируйте каждую функцию.

Логи и журналирование:

• Каналы логирования:
  • Имена в config/logging.php в snake_case, например, single, stack.
• Использование:
  • Используйте фасад Log с осмысленными сообщениями.

Сеансы (Sessions):

• Конфигурация:
  • Имена драйверов и опций в snake_case.
• Ключи сессии:
  • Имена ключей в snake_case, например, user_id.

Кэширование:

• Ключи кэша:
  • Осмысленные и уникальные, например, user_{$id}_profile.
• Теги кэша:
  • Используйте для группировки, имена в snake_case.

Очереди и задания (Jobs):

• Имена классов заданий:
  • В StudlyCase, например, SendEmailJob.
• Расположение:
  • В App\Jobs.
• Методы:
  • Основной метод handle().

Политики (Policies):

• Имена классов:
  • Заканчиваются на Policy, например, PostPolicy.
• Расположение:
  • В App\Policies.
• Методы:
  • Именуются по действиям, например, view, create, update.

Поставщики привязки (Bindings):

• Имена интерфейсов и реализаций:
  • Интерфейсы с суффиксом Interface, реализации с осмысленными именами.
• Привязка в контейнере:
  • Используйте осмысленные ключи при привязке.

Маршрутизация консольных команд:

• Имена команд:
  • В kebab-case, отражают действие, например, make:model.
• Описание команд:
  • Должно быть кратким и информативным.

События вещания (Broadcasting):

• Имена каналов:
  • В snake_case, например, private-chat.
• Имена событий:
  • Как и обычные события, в StudlyCase.

Eloquent Scopes:

• Имена локальных областей:
  • В camelCase, начинаются с scope, например, scopeActive.
• Имена глобальных областей:
  • Классы в StudlyCase, например, ActiveScope.

Метаданные и комментарии SQL:

• Имена индексов:
  • В snake_case, обычно включают имена таблиц и полей, например, users_email_unique.
• Комментарии:
• Используйте для описания сложных запросов.