English | 中文文档
Package: super-kernel/environment · Packagist · Documentation index
super-kernel/environment is where an application reads values from outside its code: process environment variables, .env files, and arrays it builds itself. It combines these sources in a fixed order and converts their raw values strictly, so that a typo such as MAIL_PORT=25x fails loudly instead of becoming 25 or a silent default.
The package returns raw values only. Defaults and the checks a component needs belong to the application's configuration sources and to the components, typically through super-kernel/config.
SuperKernel\Environment\Environment implements SuperKernel\Environment\Contract\EnvironmentInterface:
| Method | Returns |
|---|---|
has($name) |
Whether any source has the property, also when its value is null |
get($name) |
The raw value: string, int, float, bool, or null |
getString($name) |
The value as a string; true and false become 'true' and 'false' |
getInt($name) |
An integer, from an integer or a string that is exactly an integer |
getFloat($name) |
A finite float, from an integer, a float, or a numeric string |
getBool($name) |
A boolean, from a boolean, 0 or 1, or the strings 1, 0, true, false, yes, no, on, off in any case, with surrounding spaces ignored |
Every typed accessor returns null when no source has the property or the winning value is null. Any other value that does not fit raises SuperKernel\Environment\Exception\InvalidEnvironmentValueException, whose message names the property, the expected kind, and the type it received, never the value, since external values may be secrets. Nothing falls back to a default.
A script that reads typed values, saved as bin/environment.php:
<?php
declare(strict_types=1);
use SuperKernel\Environment\Environment;
use SuperKernel\Environment\PropertySource\ArrayPropertySource;
use SuperKernel\Environment\PropertySource\ProcessEnvironmentPropertySource;
require dirname(__DIR__) . '/vendor/autoload.php';
$environment = new Environment([
new ArrayPropertySource('defaults', ['app.debug' => 'off', 'app.workers' => '4']),
new ProcessEnvironmentPropertySource(),
]);
var_dump($environment->getBool('app.debug'));
var_dump($environment->getInt('app.workers'));
var_dump($environment->getString('app.name'));Run it with a process variable:
APP_DEBUG=yes php bin/environment.phpIt prints:
bool(true)
int(4)
NULL
A script that shows the failures, saved as bin/invalid.php:
<?php
declare(strict_types=1);
use SuperKernel\Environment\Environment;
use SuperKernel\Environment\Exception\InvalidEnvironmentValueException;
use SuperKernel\Environment\Exception\InvalidPropertyNameException;
use SuperKernel\Environment\PropertySource\ArrayPropertySource;
require dirname(__DIR__) . '/vendor/autoload.php';
$environment = new Environment([
new ArrayPropertySource('settings', ['db.password' => 's3cret', 'cache.ttl' => null]),
]);
try {
$environment->getInt('db.password');
} catch (InvalidEnvironmentValueException $exception) {
echo $exception->getMessage(), PHP_EOL;
}
try {
$environment->get('DB_PASSWORD');
} catch (InvalidPropertyNameException $exception) {
echo $exception->getMessage(), PHP_EOL;
}
var_dump($environment->has('cache.ttl'), $environment->getInt('cache.ttl'));php bin/invalid.php prints:
Environment property db.password must be an integer; string provided.
Property names must use non-empty lowercase dotted or kebab notation.
bool(true)
NULL
A property name is lowercase letters and digits, starting with a letter, in segments joined by . or -, such as mail.port or app.feature-flag. Every source uses the same name. The process and .env sources look it up as an environment variable: dots and hyphens become underscores and letters become uppercase, so app.feature-flag reads APP_FEATURE_FLAG. Any other name, such as DB_PASSWORD or Mail.Port, is rejected with InvalidPropertyNameException rather than guessed.
new Environment($sources) takes a list of SuperKernel\Environment\Contract\PropertySourceInterface, ordered from lowest to highest precedence: the last source that has a property wins. A source that holds null for a property still wins, so the result is null. Sources are read as they are; the environment changes none of them. Put defaults first and the process environment last, so that a variable set for one run overrides everything else.
ArrayPropertySource($name, $values)holds an array keyed by property name; values must be scalars ornull. Use it for defaults built in code and in tests.ProcessEnvironmentPropertySourcereads the process environment throughgetenv()at each lookup.DotenvPropertySource($path, $optional = true)reads one.envfile, described below.
DotenvPropertySource parses the file once, when it is created, with symfony/dotenv, and keeps that snapshot. It never writes to $_ENV, $_SERVER, or the process environment, so getenv() does not see the values.
- A missing file contributes nothing when the source is optional, the default; with
$optionalset tofalseit raisesPropertySourceLoadingException. - An unreadable or malformed file always raises
PropertySourceLoadingException, with the parser's exception as its previous one. name()returnsdotenv:followed by the path, for diagnostics.
The file, saved in the project directory as .env:
MAIL_HOST=smtp.example.com
MAIL_PORT=2525A script that reads it, saved as bin/dotenv.php:
<?php
declare(strict_types=1);
use SuperKernel\Environment\Environment;
use SuperKernel\Environment\PropertySource\DotenvPropertySource;
use SuperKernel\Environment\PropertySource\ProcessEnvironmentPropertySource;
require dirname(__DIR__) . '/vendor/autoload.php';
$dotenv = new DotenvPropertySource(dirname(__DIR__) . '/.env');
$environment = new Environment([$dotenv, new ProcessEnvironmentPropertySource()]);
echo $environment->getString('mail.host'), ':', $environment->getInt('mail.port'), PHP_EOL;
var_dump(getenv('MAIL_HOST'));
var_dump(new DotenvPropertySource(dirname(__DIR__) . '/.env.local')->has('mail.host'));php bin/dotenv.php prints the following; the last line reads a file that does not exist:
smtp.example.com:2525
bool(false)
bool(false)
SuperKernel\Environment\Provider\EnvironmentProvider carries #[FactoryProvider(EnvironmentInterface::class)] and supplies an environment over the process environment only. To read a .env file as well, the application declares its own EnvironmentInterface with #[Provider(EnvironmentInterface::class)], which takes precedence over the factory provider, and puts the .env source below the process source.
The application reads the environment in its configuration sources: each typed value with its default, so that a missing property uses the default and an invalid one fails. Components then receive typed configuration, never raw properties.
An environment with a .env file, saved as src/Env/AppEnvironment.php:
<?php
declare(strict_types=1);
namespace Src\Env;
use SuperKernel\Attribute\Provider;
use SuperKernel\Contract\BasePathInterface;
use SuperKernel\Environment\Contract\EnvironmentInterface;
use SuperKernel\Environment\Environment;
use SuperKernel\Environment\PropertySource\DotenvPropertySource;
use SuperKernel\Environment\PropertySource\ProcessEnvironmentPropertySource;
#[Provider(EnvironmentInterface::class)]
final readonly class AppEnvironment implements EnvironmentInterface
{
private Environment $environment;
public function __construct(BasePathInterface $basePath)
{
$this->environment = new Environment([
new DotenvPropertySource($basePath . '/.env'),
new ProcessEnvironmentPropertySource(),
]);
}
public function has(string $name): bool
{
return $this->environment->has($name);
}
public function get(string $name): string|int|float|bool|null
{
return $this->environment->get($name);
}
public function getString(string $name): ?string
{
return $this->environment->getString($name);
}
public function getInt(string $name): ?int
{
return $this->environment->getInt($name);
}
public function getFloat(string $name): ?float
{
return $this->environment->getFloat($name);
}
public function getBool(string $name): ?bool
{
return $this->environment->getBool($name);
}
}A configuration interface, saved as src/Mail/MailConfig.php:
<?php
declare(strict_types=1);
namespace Src\Mail;
use SuperKernel\Contract\SingleConfigInterface;
interface MailConfig extends SingleConfigInterface
{
public function host(): string;
public function port(): int;
}A configuration source that reads the environment with defaults, saved as src/Mail/EnvironmentMailConfig.php:
<?php
declare(strict_types=1);
namespace Src\Mail;
use SuperKernel\Attribute\Configuration;
use SuperKernel\Environment\Contract\EnvironmentInterface;
#[Configuration(MailConfig::class)]
final readonly class EnvironmentMailConfig implements MailConfig
{
private string $host;
private int $port;
public function __construct(EnvironmentInterface $environment)
{
$this->host = $environment->getString('mail.host') ?? 'localhost';
$this->port = $environment->getInt('mail.port') ?? 25;
}
public function host(): string
{
return $this->host;
}
public function port(): int
{
return $this->port;
}
}A script that reads the configuration, saved as bin/mail.php:
<?php
declare(strict_types=1);
use Src\Mail\MailConfig;
use SuperKernel\Context\ApplicationContext;
use SuperKernel\Contract\ConfigInterface;
require dirname(__DIR__) . '/vendor/autoload.php';
$mail = ApplicationContext::getContainer()->get(ConfigInterface::class)->get(MailConfig::class);
echo $mail->host(), ':', $mail->port(), PHP_EOL;Build the project and run the script with and without a process variable:
skernel build
php bin/mail.php
MAIL_PORT=465 php bin/mail.phpWith the .env file above, it prints smtp.example.com:2525, then smtp.example.com:465; without the file, localhost:25.
A source implements PropertySourceInterface: name() returns a non-empty name for diagnostics, has($name) reports whether the source holds the property, also with a null value, and get($name) returns the raw string, int, float, bool, or null. Environment rejects anything in its list that is not a source with InvalidPropertySourceException.
Every exception of the package implements SuperKernel\Environment\Exception\EnvironmentExceptionInterface.
| Situation | Message |
|---|---|
A name that is not lowercase dotted or kebab notation (InvalidPropertyNameException) |
Property names must use non-empty lowercase dotted or kebab notation. |
A value that is not an integer (InvalidEnvironmentValueException) |
Environment property <name> must be an integer; <type> provided. |
A value that is not a finite number (InvalidEnvironmentValueException) |
Environment property <name> must be a finite number; <type> provided. |
A value that is not a recognized boolean (InvalidEnvironmentValueException) |
Environment property <name> must be a boolean; <type> provided. |
A missing required .env file (PropertySourceLoadingException) |
Required dotenv file <path> does not exist. |
An unreadable .env file (PropertySourceLoadingException) |
Unable to read dotenv file <path>. |
A malformed .env file (PropertySourceLoadingException, parser exception as previous) |
Unable to parse dotenv file <path>. |
Sources that are not a list (InvalidPropertySourceException) |
Environment property sources must be a list. |
An entry that is not a source (InvalidPropertySourceException) |
Environment property sources must implement SuperKernel\Environment\Contract\PropertySourceInterface; <type> provided. |
An empty array source name (InvalidPropertySourceException) |
A property source name must not be empty. |
An array source key that is not a string (InvalidPropertySourceException) |
Property source keys must be canonical strings; <type> provided. |
An array source value that is not a scalar or null (InvalidPropertySourceException) |
Property source value for <name> must be scalar or null; <type> provided. |
super-kernel/attributedeclares the#[FactoryProvider]Attribute on the provider;super-kernel/dicreates the environment and lets an application#[Provider]take precedence.super-kernel/configsources read the environment and build the configuration objects that components receive.super-kernel/metadatasuppliesBasePathInterface, the project directory where an application keeps its.envfile.
Do not use environment-variable names. getInt('MAIL_PORT') raises Property names must use non-empty lowercase dotted or kebab notation. Use the property name, mail.port, which the process and .env sources map to MAIL_PORT.
Do not catch conversion errors to apply a default. An explicit value of the wrong kind is a mistake in the deployment, reported as Environment property <name> must be an integer; string provided. Apply a default only to null, with ?? $default, and let invalid values fail.
Do not expect a .env file to set environment variables. DotenvPropertySource keeps its values to itself, so getenv() and code that reads $_ENV do not see them. Read properties through EnvironmentInterface.
Do not read the environment inside components. Components receive typed configuration; the application's configuration sources read the environment and choose defaults, so each component's values come from one place.