nunomaduro/essentials — лучшие настройки для Laravel из коробки

Каждый Laravel-проект начинается с одного и того же ритуала: открываешь AppServiceProvider, добавляешь Model::shouldBeStrict(), включаешь HTTPS, запрещаешь деструктивные команды… Список растёт, а код в провайдере превращается в свалку «правильных настроек».

Nuno Maduro (автор Pest, Laravel Zero, Collision) собрал всё это в один пакет — nunomaduro/essentials. Установил — и проект сразу работает с лучшими практиками. Без копипасты, без забытых строк.

Требования: PHP 8.3+, Laravel 11+.

Установка

composer require nunomaduro/essentials

Всё. Пакет работает сразу после установки — все фичи включены по умолчанию.

Если нужно что-то отключить — публикуешь конфиг:

php artisan vendor:publish --tag=essentials-config

Появится файл config/essentials.php, где каждая фича — это true или false.

Что внутри

✅ Strict Models

Включает строгий режим для всех Eloquent-моделей. Это три вещи сразу:

Обращение к несуществующему атрибуту — выбросит исключение вместо тихого null.
Ленивая загрузка связей — заблокирована. Забыл with() — получишь ошибку, а не N+1.
Присвоение несуществующего атрибута — ошибка вместо молчаливого игнора.

Без пакета ты бы писал в AppServiceProvider:

Model::shouldBeStrict();

С Essentials — это уже включено.

Для новичков: строгие модели ловят баги на этапе разработки, а не в продакшене. Привыкнешь — будешь благодарен.

Для опытных: это то, что вы и так включаете руками. Теперь не нужно.

⚡️ Auto Eager Loading

Автоматически подгружает связи, указанные в свойстве $with модели.

class Post extends Model
{
    protected $with = ['author', 'tags'];
}

Каждый раз, когда ты получаешь Post, связи author и tags загрузятся сразу — без явного вызова with() в каждом запросе.

Зачем: убирает N+1 проблему на корню. Меньше забытых with() — меньше тормозов.

Unguarded Models (опционально)

Отключает mass assignment protection глобально. По умолчанию выключено — и это правильно.

Включать имеет смысл, если:

ты работаешь в доверенном окружении (CLI-скрипты, сидеры);
устал прописывать $fillable в каждой модели и контролируешь входные данные другими способами (Form Request, DTO).

// config/essentials.php
NunoMaduro\Essentials\Configurables\Unguard::class => true,

Осторожно: в публичных API без валидации это может быть опасно.

Immutable Dates

Заменяет стандартный Carbon на CarbonImmutable во всём приложении.

Проблема с мутабельными датами:

$start = now();
$end = $start->addDays(7); // $start тоже изменился!

С CarbonImmutable:

$start = now();
$end = $start->addDays(7); // $start остался прежним, $end — новый объект

Для новичков: если когда-то ловили баг, где дата «сама поменялась» — это именно та проблема. Immutable dates её убирают.

Для опытных: вы и так знаете, что мутабельные даты — источник боли. Теперь это включается одной строкой.

Force HTTPS

Принудительно генерирует все URL через https://.

Без этого url(), route(), asset() могут отдавать http:// — особенно за reverse proxy или load balancer. Классическая проблема, которую обычно решают через URL::forceScheme('https') в провайдере.

С Essentials — уже сделано.

Safe Console

Блокирует деструктивные Artisan-команды в продакшене:

db:wipe
migrate:fresh
migrate:refresh
migrate:reset

Одна случайная команда на боевом сервере — и базы нет. Safe Console не даст этому случиться.

Аналог ручной настройки:

DB::prohibitDestructiveCommands($this->app->isProduction());

Asset Prefetching

Настраивает Laravel Vite на более агрессивную предзагрузку ассетов. Браузер начинает скачивать JS/CSS раньше — страница загружается быстрее.

Мелочь, но приятная. Особенно для SPA и PWA.

Prevent Stray Requests

Настраивает HTTP-фасад так, чтобы в тестах любой незафейканный HTTP-запрос выбрасывал исключение.

// Без этой настройки незафейканный запрос тихо уйдёт в сеть
Http::get('https://api.example.com/users'); // реальный запрос в тесте!

// С Essentials — получишь исключение

Зачем: гарантирует, что тесты не зависят от внешних сервисов. Каждый HTTP-вызов должен быть явно замокан.

Fake Sleep

Автоматически фейкает Sleep фасад в тестах.

Если в коде есть Sleep::for(5)->seconds(), в тестах это не будет реально ждать 5 секунд. Тесты летают, а не тормозят.

️ Artisan-команды

Пакет добавляет три полезные команды.

`make:action`

Генерирует Action-класс — чистый способ организовать бизнес-логику:

php artisan make:action CreateUserAction

Создаст app/Actions/CreateUserAction.php:

<?php

declare(strict_types=1);

namespace App\Actions;

final readonly class CreateUserAction
{
    /**
     * Execute the action.
     */
    public function handle(): void
    {
        DB::transaction(function (): void {
            //
        });
    }
}

Обрати внимание: declare(strict_types=1), final readonly, транзакция — всё по best practices из коробки.

`essentials:pint`

Публикует расширенный конфиг для Laravel Pint. Стандартный pint.json в Laravel-проекте минимальный. Эта команда добавляет:

declare_strict_types — строгая типизация везде
final_class — классы final по умолчанию
ordered_class_elements — порядок элементов в классе
strict_comparison — === вместо ==

php artisan essentials:pint --backup

Флаг --backup сохранит текущий pint.json перед перезаписью.

`essentials:rector`

Публикует конфиг для Rector — инструмента автоматического рефакторинга:

удаление мёртвого кода
добавление type declarations
приватизация свойств и методов
early return
строгие boolean-проверки

php artisan essentials:rector --backup

Конфигурация

Все фичи управляются через config/essentials.php:

return [
    NunoMaduro\Essentials\Configurables\ShouldBeStrict::class  => true,
    NunoMaduro\Essentials\Configurables\Unguard::class         => false,
    NunoMaduro\Essentials\Configurables\ImmutableDates::class   => true,
    NunoMaduro\Essentials\Configurables\ForceHttps::class       => true,
    NunoMaduro\Essentials\Configurables\SafeConsole::class      => true,
    NunoMaduro\Essentials\Configurables\AssetPrefetching::class => true,
    // ...
];

Не нравится что-то — ставишь false. Всё прозрачно.

Кому подойдёт

Новичкам: пакет сразу включает настройки, до которых ты дойдёшь через месяцы граблей. Strict models поймают N+1, immutable dates спасут от мутабельных багов, Safe Console не даст снести базу. Один composer require — и проект уже настроен правильно.

Опытным: вы и так всё это делаете руками в AppServiceProvider. Essentials просто убирает этот бойлерплейт. Плюс бонусом — готовые конфиги для Pint и Rector, генератор Action-классов.

Командам: единый стандарт настроек для всех проектов. Не нужно помнить, что включить — пакет сделает это за вас.

Итог

nunomaduro/essentials — это не революция. Это здравый смысл, упакованный в один пакет. Каждая из его фич — то, что опытные Laravel-разработчики и так настраивают вручную. Разница в том, что теперь это одна команда вместо десяти строк в провайдере.

Установил, опубликовал конфиг, отключил ненужное — и работаешь. Просто и по делу.

composer require nunomaduro/essentials