super-kernel / environment
Ordered external property sources and strict typed environment access for SuperKernel.
Requires
- php: >=8.4.27 <8.5
- ext-filter: *
- super-kernel/attribute: 1.0.0-rc.2
- symfony/dotenv: ^8.1.6
Requires (Dev)
- friendsofphp/php-cs-fixer: ^3.95.27
- phpunit/phpunit: ^13.4.5
Suggests
None
Provides
None
Conflicts
None
Replaces
None
This package is auto-updated.
Last update: 2026-11-20 01:12:46 UTC
README
English | 中文文档
SuperKernel Environment
super-kernel/environment reads external properties, such as environment variables and .env files, from ordered sources and returns them as strictly checked strings, integers, floats, and booleans.
Installation
composer require super-kernel/environment
The package needs the filter extension, which PHP includes by default, and installs symfony/dotenv to parse .env files.
What it provides
- An environment that reads properties from a list of sources, where a later source overrides an earlier one.
- Sources for arrays,
.envfiles, and the process environment. - Typed accessors that return
nullfor a missing property and reject an explicit value of the wrong kind. - One property name, such as
mail.port, for every source: process and.envsources read it asMAIL_PORT. - A container entry for
EnvironmentInterfacethat reads the process environment.
It does not:
- define defaults or check values for other components; your configuration sources do;
- change
$_ENV,$_SERVER, or the process environment when it reads a.envfile; - offer profiles, remote configuration, or reloading.
Quick start
Read typed values with defaults below the process environment. Save the script 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 the script with a process variable:
APP_DEBUG=yes php bin/environment.php
It prints:
bool(true)
int(4)
NULL
Public surface
| Name | Kind | Purpose |
|---|---|---|
SuperKernel\Environment\Contract\EnvironmentInterface |
Interface | has(), raw get(), and typed getString(), getInt(), getFloat(), and getBool(). |
SuperKernel\Environment\Environment |
Class | The environment over a list of sources, ordered from lowest to highest precedence. |
SuperKernel\Environment\Contract\PropertySourceInterface |
Interface | Implemented by a source: its name, whether it has a property, and the raw value. |
SuperKernel\Environment\PropertySource\ArrayPropertySource |
Class | Properties from an array, keyed by property name. |
SuperKernel\Environment\PropertySource\DotenvPropertySource |
Class | Properties from one .env file, optional by default. |
SuperKernel\Environment\PropertySource\ProcessEnvironmentPropertySource |
Class | Properties from the process environment. |
SuperKernel\Environment\Provider\EnvironmentProvider |
Class | The factory provider of EnvironmentInterface, reading the process environment only. |
Behavior to know
- Property names are lowercase, with dots or hyphens, such as
mail.portorapp.feature-flag. Any other name raisesSuperKernel\Environment\Exception\InvalidPropertyNameExceptionwith the messageProperty names must use non-empty lowercase dotted or kebab notation. - A typed accessor raises
SuperKernel\Environment\Exception\InvalidEnvironmentValueExceptionfor a value of the wrong kind, such asEnvironment property app.workers must be an integer; string provided.The message never contains the value. - Booleans accept
1,0,true,false,yes,no,on, andoff, in any case. - A required
.envfile that is missing, unreadable, or malformed raisesSuperKernel\Environment\Exception\PropertySourceLoadingException; a missing optional file contributes nothing. - The container's default environment does not read
.envfiles; an application adds one by providing its ownEnvironmentInterface.
Documentation
The developer documentation describes the sources, precedence, conversions, .env files, and use in an application with complete examples: SuperKernel Environment.
License
Released under the MIT License. See LICENSE.