Weave Code
Env Bundle Laravel Package
nbgrp/env-bundle
nbgrp/env-bundle is a PHP package that simplifies environment variable management. It provides a clean, consistent way to load, organize, and access .env settings, helping keep configuration separate from code and easy to adapt across development, staging, and production.
Bundle with a few useful Symfony environment variable processors.
Frequently asked questions about Env Bundle
- What is nbgrp/env-bundle and what problem does it solve?
- nbgrp/env-bundle is a Composer package that brings structured environment variable handling to Symfony applications. Instead of scattering getenv() calls throughout your code, you declare env processors in dependency injection configuration to resolve, cast, transform, and validate values. That gives you consistent behavior across local, staging, and production environments.
- Does nbgrp/env-bundle work with Laravel applications?
- Only partially. The package is built around Symfony's dependency injection container and does not ship a Laravel service provider, facade, or publishable Laravel config, so it is not a drop-in Laravel package. Laravel applications running on Symfony 7 components can reuse the same patterns, but most Laravel teams will find the framework's own env() helper and config caching cover the same ground. Evaluate whether you specifically need container-build-time validation before adopting it.
- Which Laravel and PHP versions does nbgrp/env-bundle v3.0.0 require?
- Version 3.0.0 adds Symfony 7 support and drops the older Symfony major, which effectively aligns it with Laravel 11 and later, since Laravel's HTTP, console, and event layers are built on Symfony packages. Confirm the exact PHP floor in the package's composer.json before planning runtime images. Applications on Laravel 10 or earlier must stay on the 2.x line or schedule a framework upgrade first.
- How do I install nbgrp/env-bundle with Composer?
- Install it with composer require nbgrp/env-bundle and choose the constraint deliberately: ^3.0 for Symfony 7 and Laravel 11+ projects, or ^2.0 if you are still on older Symfony components. Committing an explicit major-version pin prevents an accidental upgrade the next time someone runs composer update. After installing, diff any published config against your existing settings and run your full test suite.
- How do env processors cast and transform environment variables?
- Env processors are declared in configuration and applied to variables so values arrive typed and normalized instead of as raw strings. You use them to cast values such as booleans, integers, or lists, and to transform formats before the container injects them into services. Because the logic lives in configuration, it is reviewable and identical across environments rather than duplicated in application code.
- How does nbgrp/env-bundle validate required environment variables?
- Validation runs at container build time, so a missing or malformed required value fails during cache warmup or container compilation instead of at runtime under traffic. That fail-fast behavior means broken configuration surfaces in CI or at deploy rather than as a 500 error for the first user. It also means your build pipeline must supply required values, or provide a safe mechanism for doing so.
- Is upgrading from 2.x to 3.0 a breaking change and what should I check?
- Treat v3.0.0 as a breaking release. The headline change is Symfony 7 support with older Symfony majors dropped, and the notes enumerate toolchain work such as psalm PHP-version handling and linter rule updates rather than an explicit breaking-change list. Read the readme diff before upgrading, pin ^3.0 in a branch, run the full test suite, and compare published config and assets against the installed version.
- How do I stay on the 2.x branch and is it still maintained?
- Pin ^2.0 explicitly in composer.json so a routine composer update cannot pull the major bump. The release history shows parallel maintenance branches, which suggests 2.x continues to receive fixes, but the exact support window is not stated publicly, so confirm it on the issue tracker. Treat the move to 3.x as a scheduled task tied to your Laravel upgrade.
- Can nbgrp/env-bundle conflict with my application's symfony/* constraints?
- Yes, and that is the most common failure mode for packages that bump Symfony majors. Because the bundle depends on symfony components, its constraints can collide with your application's own Symfony requirements and Composer will refuse to resolve. Before upgrading, run composer why-not symfony/framework-bundle with your target version to see which constraint is blocking the update.
- How do I test configuration that uses nbgrp/env-bundle?
- Build the container inside a test with the required env values set, then assert that processors produce the expected typed values. Add negative tests that omit or malform a required variable and assert the build fails, since that fail-fast behavior is the point of the package. Keep those tests in CI so a later config change cannot silently reintroduce a raw getenv() call.
Weaver
How can I help you explore Laravel packages today?