nunomaduro/essentials

Essentials

Essentials provide better defaults for your Laravel applications including strict models, automatically eagerly loaded relationships, immutable dates, and more!

Requires PHP 8.3+, Laravel 11+.

Note: This package modifies the default behavior of Laravel. It is recommended to use it in new projects or when you are comfortable with the changes it introduces.

Installation

⚡️ Get started by requiring the package using Composer:

composer require nunomaduro/essentials

Features

All features are optional and configurable in config/essentials.php.

You may publish the configuration file with:

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

Table of Contents

• Strict Models
• Auto Eager Loading
• Optional Unguarded Models
• Immutable Dates
• Force HTTPS
• Safe Console
• Asset Prefetching
• Prevent Stray Requests
• Fake Sleep
• Artisan Commands
  • make:action
  • essentials:pint
  • essentials:rector

✅ Strict Models

Improves how Eloquent handles undefined attributes, lazy loading, and invalid assignments.

• Accessing a missing attribute throws an error.
• Lazy loading is blocked unless explicitly allowed.
• Setting undefined attributes throws instead of failing silently.

Why: Avoids subtle bugs and makes model behavior easier to reason about.

---

⚡️ Auto Eager Loading

Automatically eager loads relationships defined in the model's $with property.

Why: Reduces N+1 query issues and improves performance without needing with() everywhere.

---

🔓 Optional Unguarded Models

Disables Laravel's mass assignment protection globally (opt-in).

Why: Useful in trusted or local environments where you want to skip defining $fillable.

---

🕒 Immutable Dates

Uses CarbonImmutable instead of mutable date objects across your app.

Why: Prevents unexpected date mutations and improves predictability.

---

🔒 Force HTTPS

Forces all generated URLs to use https://.

Why: Ensures all traffic uses secure connections by default.

---

🛑 Safe Console

Blocks potentially destructive Artisan commands in production (e.g., migrate:fresh).

Why: Prevents accidental data loss and adds a safety net in sensitive environments.

---

🚀 Asset Prefetching

Configures Laravel Vite to preload assets more aggressively.

Why: Improves front-end load times and user experience.

---

🔄 Prevent Stray Requests

Configures Laravel Http Facade to prevent stray requests.

Why: Ensure every HTTP calls during tests have been explicitly faked.

---

😴 Fake Sleep

Configures Laravel Sleep Facade to be faked.

Why: Avoid unexpected sleep during testing cases.

🏗️ Artisan Commands

make:action

Quickly generates action classes in your Laravel application:

php artisan make:action CreateUserAction

This creates a clean action class at 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 {
            //
        });
    }
}

Actions help organize business logic in dedicated classes, promoting single responsibility and cleaner controllers.

essentials:pint

Laravel Pint is included by default in every Laravel project and is a great tool to keep your code clean and consistent. But it is configured very minimally by default. This command will publish a configuration file for Pint that includes the following:

• "declare_strict_types" - Enforces strict types in all files.
• "final_class" - Enforces final classes by default.
• "ordered_class_elements" - Orders class elements by visibility and type.
• "strict_comparison" - Enforces strict comparison in all files.
• and more...

php artisan essentials:pint {--force} {--backup}

Options:

• --force - Overwrites the existing configuration file without asking for confirmation.
• --backup - Creates a backup of the existing configuration file.

essentials:rector

Rector is a powerful tool for refactoring and improving your codebase. This command will publish a configuration file for Rector that includes the following:

• "deadCode" - Removes dead code from your codebase.
• "codeQuality" - Improves code quality by applying best practices.
• "typeDeclarations" - Adds type declarations to your codebase.
• "privatization" - Privatizes class properties and methods where possible.
• "earlyReturn" - Enforces early return statements in your codebase.
• "strictBooleans" - Enforces strict boolean checks in your codebase.

php artisan essentials:rector {--force} {--backup}

Options:

• --force - Overwrites the existing configuration file without asking for confirmation.
• --backup - Creates a backup of the existing configuration file.

Configuration

All features are configurable through the essentials.php config file. By default, most features are enabled, but you can disable any feature by setting its configuration value to false:

// config/essentials.php
return [
    NunoMaduro\Essentials\Configurables\ShouldBeStrict::class => true,
    NunoMaduro\Essentials\Configurables\Unguard::class => false,
    // other configurables...
];

You may also publish the stubs used by this package:

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

Roadmap

• Better defaults before each test case
• Better Pint configuration by default
• General cleanup of the skeleton
• Additional configurables for common Laravel patterns

License

Essentials was created by Nuno Maduro under the MIT license.