DEV Community: Codegenie

Laravel env() Outside config/: Catch Deployment Bugs Before config:cache

Codegenie — Thu, 20 Aug 2026 11:45:01 +0000

The bug only appears after configuration caching

A Laravel application can behave perfectly during development and then fail after deployment because a service class reads an environment variable directly:

// app/Services/AcmeClient.php
$token = env('ACME_TOKEN');

Laravel's configuration cache changes the boot process. Once configuration has been cached, the framework does not load the application's .env file for normal requests or Artisan commands. A direct env() call outside a configuration file may therefore return only an externally supplied system value or its fallback.

The reliable pattern is to read the environment variable once from a configuration file:

// config/services.php
return [
    'acme' => [
        'token' => env('ACME_TOKEN'),
    ],
];

Application code should then use Laravel's configuration repository:

// app/Services/AcmeClient.php
$token = config('services.acme.token');

This is the primary fix. A package should never be used to justify keeping unsafe environment access in application code.

Environment drift is a separate problem

Even when every env() call is in the right place, teams still have to keep several environment contracts aligned. A project might contain .env, .env.testing, .env.production, .env.sample, or a template with a company-specific name.

Consider these files:

# .env
APP_NAME=Codegenie
ACME_TOKEN=local-secret

# .env.production
APP_NAME=Codegenie

The values are expected to differ, but the missing ACME_TOKEN key can still indicate an incomplete deployment contract. Other easy-to-miss cases include:

a duplicate active assignment in one file;
keys that differ only by case;
a key used by the application but declared nowhere;
an obsolete key that might no longer be consumed;
direct getenv(), $_ENV, or $_SERVER access;
a dynamic lookup such as env('SERVICE_'.$driver) that static analysis cannot resolve safely;
a Vite key referenced in frontend code but absent from the environment contract.

A useful manual review

Before adding tooling, a team can already reduce these failures with a small review:

Search application-owned PHP files for env( and move valid reads into config/.
Compare the key inventories of the environment files that represent complete environments.
Treat commented assignments in non-active templates as documentation, not active values.
Check phpunit.xml and .env.testing together.
Review Vite import.meta.env and loadEnv() usage.
Run the application with configuration cached before deployment.

Do not compare or print secret values while performing this review. Environment URLs, credentials, application keys, and tokens are supposed to differ between environments.

Automating the development feedback loop

I maintain Laravel Env Guard through Codegenie to automate this review for current Laravel applications.

Install it as a development dependency:

composer require --dev codegenie-be/laravel-env-guard

Laravel package discovery registers the guard automatically. By default it runs only during console boots in the local environment. It does not require a separate audit command or a specially named .env.example file.

Each guarded audit reads the current project files directly and checks:

unsafe env() and Illuminate\Support\Env::get() calls outside config/;
direct raw environment access for project-owned keys;
duplicate, case-mismatched, missing, and possibly unused keys;
drift across automatically discovered plaintext .env and .env.* files;
explicit reference or comparison files when a project configures them;
PHPUnit, Vite, Blade, Docker, workflow, and other application-owned usage covered by the scanner.

Blocking findings fail fast by default. Warnings and errors are written to STDERR as a compact key-only report during Artisan commands.

Secret handling is a hard boundary

The guard compares keys, never values. Its reports, exceptions, and logs do not include environment values. It performs no telemetry or network requests, never modifies .env files, and does not synchronize secrets.

Encrypted environment files are intentionally excluded because auditing them would require decryption. Production and normal HTTP scanning are disabled by default. The package is a development guard, not a secret manager or deployment system.

Likely-unused diagnostics also require judgment: a key may be consumed by infrastructure, a package, Docker, a process manager, or code outside the configured scan paths. Projects can explicitly ignore legitimate external keys and patterns.

A gradual rollout works best

For an existing application, I recommend this order:

Install the package on a branch.
Fix direct env() usage outside config/ first.
Review duplicate and case-mismatch errors.
Decide which environment files are complete peers and which are partial Vite-style layers.
Suppress only intentional external or infrastructure-owned cases.
Verify the result with config:cache and the normal test suite.

The current release, v1.2.1, supports Laravel 12 and 13 across their valid PHP 8.2–8.5 combinations. The package is also available on Packagist.

Disclosure: I maintain this open-source package through Codegenie. I am especially interested in technical feedback about renamed environment templates, partial environment layers, framework keys, and false-positive or false-negative edge cases. Please do not include real environment values or secrets in reports.

Laravel .env changes not reflected after deployment: causes and a safe shared-hosting fallback

Codegenie — Tue, 11 Aug 2026 19:28:32 +0000

Changing a production .env file and still seeing the old database host, mail settings, application URL, or feature flag is a familiar Laravel deployment surprise.

Usually, Laravel is doing exactly what it was told to do: use a cached configuration snapshot.

Disclosure: Codegenie maintains the open-source package discussed near the end of this article. The normal Laravel deployment commands remain the preferred solution.

Why the new value is ignored

Laravel's configuration files read environment variables and expose them through the configuration repository:

// config/services.php
return [
    'example' => [
        'endpoint' => env('EXAMPLE_ENDPOINT'),
    ],
];

Application code should then read the configuration value:

$endpoint = config('services.example.endpoint');

When you run:

php artisan config:cache

Laravel combines the configuration into a cached snapshot. Once that snapshot exists, the framework does not load the application's .env file during requests or Artisan commands. That is why editing .env alone does not change the value your application sees.

Laravel also recommends calling env() only from configuration files. Calling env() directly from controllers, jobs, or services can return null after configuration has been cached.

The official explanation is in Laravel's configuration caching documentation.

The normal production fix

A reliable deployment should rebuild the cache after the new code and environment configuration are in place:

composer install --no-dev --optimize-autoloader
php artisan config:cache

If the application uses route caching, rebuild that too:

php artisan route:cache

If you intentionally do not want cached configuration, clear it instead:

php artisan config:clear

The important part is that the cache command belongs to the deployment process. Run it on every release, after all relevant files and environment settings have been updated.

For deployments with release directories, build caches inside the new release before switching the live symlink. That avoids serving a half-updated application.

Why FTP and shared hosting make this harder

The ideal flow assumes you can execute PHP CLI commands during deployment.

On shared hosting that assumption may be false:

the site is uploaded through FTP;
cPanel or Plesk provides no useful deploy hook;
SSH is unavailable;
PHP functions such as exec() are disabled;
the old cache file survives while .env or config/*.php changes.

Clearing a browser cache or application data cache does not solve this. Configuration cache and route cache are deployment artifacts, not regular response or database cache.

A web request could notice the problem, but timing matters. Laravel reads cached configuration while the application is bootstrapping. Middleware and normal service providers run too late to prevent that request from loading stale configuration.

What a safe fallback needs to do

A useful fallback should protect correctness without pretending to replace a deployment pipeline.

It should:

run before Laravel consumes cached configuration or routes;
detect relevant source changes without reading or storing secret values;
stop stale cache from being used immediately;
rebuild through PHP CLI when that is available;
degrade safely when shell execution is unavailable;
use locks and exact source signatures to avoid racing repairs;
avoid enabling cache types the application was not already using.

That design is the basis of Laravel Config Cache Guard.

How the fallback works

Install it with one Composer command:

composer require codegenie-be/laravel-config-cache-guard

Composer loads the guard before bootstrap/app.php. It compares metadata for relevant sources such as .env, configuration files, route files, and route bootstrap files. It tracks timestamps, sizes, and filesystem metadata—not environment values.

When the sources are unchanged, the request continues normally.

When an existing config cache is stale, the guard prevents Laravel from using it. When an existing route cache is stale, the guard bypasses it using a signature-based cache path.

If PHP CLI execution is available, it can rebuild before Laravel boots.

If exec() is disabled, the current request continues without the known-stale deployment cache. The guard writes an internal pending marker, and the package service provider rebuilds through Laravel's own Artisan::call() after the response. A following request can then use the refreshed cache.

There is no public repair endpoint, no repair token, and no telemetry.

Defaults that avoid surprising applications

The package does not automatically turn on config caching for every project.

If no config cache exists, config-cache creation remains disabled unless you explicitly opt in:

CONFIG_CACHE_GUARD_CREATE_CONFIG_CACHE=true

Route guarding starts only when the application already has route cache.

This matters because a correctness guard should not silently change an application's caching policy.

You can optionally inspect the integration with:

php artisan config-cache-guard:status

That status command is verification, not a second installation step.

Limitations

This fallback still needs a writable Laravel bootstrap cache directory.

Without exec(), repair happens after the current response. The first request runs without stale deployment cache, but it may be uncached. The next request uses the rebuilt cache if repair succeeded.

Custom bootstrap paths selected later in application code cannot always be discovered before Laravel boots.

And most importantly: if your platform supports reliable deployment hooks, keep using the standard Laravel cache commands. The package is a safety net for restricted hosting, not a replacement for a healthy deployment process and not a promise to make every website faster.

Compatibility and testing

The current release supports Laravel 12 and 13 on non-EOL PHP versions. Its test suite installs fresh Laravel applications and verifies real HTTP requests, including Linux and Windows scenarios and the exec()-disabled repair path.

The source, demo, security notes, and deployment recipes are available on GitHub.

If you deploy Laravel through FTP, cPanel, Plesk, or another restricted host, technical feedback is especially welcome. Which deployment limitations have you encountered, and how do you currently prevent stale configuration from reaching users?

Laravel Livewire Multi-Step Forms: Validation and Safe Submission

Codegenie — Wed, 09 Jul 2025 14:40:30 +0000

Updated for the stable v1.0.0 package release (August 2026). The original project has been refactored from a demo application into an installable Composer package for Laravel 12–13 and Livewire 3–4.

Long forms are easier to complete when they are split into focused steps, but the server-side contract still matters: users must not be able to skip validation, submit before the review step, or inject values outside configured choices.

I built Laravel Livewire Multi-Step Form as a small, configuration-driven package that handles that reusable flow while leaving persistence, authorization, mail, redirects, and rate limiting in your application.

Install it

composer require codegenie-be/laravel-livewire-multistep-form

Requirements:

PHP 8.2 through supported PHP 8.x releases
Laravel 12 or 13
Livewire 3.6+ or 4.x

Laravel package discovery registers the component automatically.

Define fields, not a second application

Pass a field configuration to the registered Livewire component:

<livewire:codegenie-multistep-form
    :fields="[
        'name' => [
            'rules' => 'required|string|min:2|max:120',
            'label' => 'Name',
            'step' => 1,
            'type' => 'text',
        ],
        'email' => [
            'rules' => 'required|email|max:255',
            'label' => 'Email address',
            'step' => 2,
            'type' => 'email',
        ],
        'topic' => [
            'rules' => 'required|string',
            'label' => 'Topic',
            'step' => 2,
            'type' => 'select',
            'options' => [
                'general' => 'General question',
                'support' => 'Support',
            ],
        ],
        'message' => [
            'rules' => 'required|string|min:10|max:5000',
            'label' => 'Message',
            'step' => 3,
            'type' => 'textarea',
        ],
    ]"
/>

Steps start at 1 and remain consecutive. The package currently supports text-like inputs, textarea, and select fields. File uploads, repeaters, nested names, checkboxes, and radio groups are intentionally outside v1.0.0.

Validation is enforced on the server

Each Next action validates only the current step. Final submission is accepted only from the generated review step, then validates the complete form again.

Select option keys form a server-side allow-list. If final validation fails, the wizard returns to the first invalid step and requests focus for that field.

For Laravel rule objects, closures, or application-sensitive validation details, extend the component and keep those rules out of public Livewire state:

use Codegenie\LivewireMultistepForm\Livewire\MultiStepForm;
use Illuminate\Validation\Rule;

class ContactWizard extends MultiStepForm
{
    protected function serverValidationRules(): array
    {
        return [
            'email' => [Rule::unique('users', 'email')],
        ];
    }
}

Your application owns the submission

The base component deliberately does not write to a database or send mail. Extend it when you need server-side persistence:

protected function handleSubmission(array $data): void
{
    ContactRequest::query()->create($data);
}

Only configured, validated fields reach this hook. Authorization, rate limiting, retention, redirects, and other application concerns remain yours.

Accessibility, localization, and styling

The default view includes semantic form and fieldset markup, associated labels and errors, progressbar metadata, visible focus states, focus management, reduced-motion handling, and instance-scoped IDs.

English, Dutch, and French interface translations ship with the package. The Blade view and translations can be published when an application needs custom copy or markup.

The view uses Tailwind utility classes but ships no compiled frontend assets. Tailwind 3 projects add the vendor view path to content; Tailwind 4 projects add it with @source.

Try or inspect it

The package is MIT licensed. Compatibility is tested across Laravel 12–13, Livewire 3–4, and applicable PHP 8.2–8.5 combinations, including minimum dependency sets.

Disclosure: I maintain this open-source package through Codegenie. Feedback on validation edge cases, accessibility, and real-world Livewire 4 usage is especially welcome.