PHPackages                             env-interop/interface - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [Parsing & Serialization](/categories/parsing)
4. /
5. env-interop/interface

ActiveLibrary[Parsing & Serialization](/categories/parsing)

env-interop/interface
=====================

Interoperable environment interfaces for PHP.

1.x-dev(3mo ago)6312MITPHPPHP ^8.4CI passing

Since Dec 24Pushed 3mo agoCompare

[ Source](https://github.com/env-interop/interface)[ Packagist](https://packagist.org/packages/env-interop/interface)[ Docs](https://github.com/env-interop/interface)[ RSS](/packages/env-interop-interface/feed)WikiDiscussions 1.x Synced 1mo ago

READMEChangelog (3)Dependencies (3)Versions (4)Used By (2)

Env-Interop Standard Interface Package
======================================

[](#env-interop-standard-interface-package)

Env-Interop provides an interoperable package of standard interfaces for loading and parsing environment files, and encapsulating environment variables, in PHP 8.4 or later. It reflects, refines, and reconciles the common practices identified within [several pre-existing projects](./README-RESEARCH.md).

The standards provided in this package are also informed by:

-
-
-

The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in [BCP 14](https://www.rfc-editor.org/info/bcp14) ([RFC 2119](https://datatracker.ietf.org/doc/html/rfc2119), [RFC 8174](https://datatracker.ietf.org/doc/html/rfc8174)).

Interfaces
----------

[](#interfaces)

- [*EnvLoaderService*](#envloaderservice) interface affords loading environment variables parsed from environment files into `$_ENV` (and possibly elsewhere).
- [*EnvParserService*](#envparserservice) interface affords parsing a string for environment variables.
- [*EnvSetterService*](#envsetterservice) interface affords adding or replacing an environment variable in `$_ENV` (and possibly elsewhere).
- [*EnvGetter*](#envgetter) affords getting environment variable values.
- [*EnvThrowable*](#envthrowable) interface extends [*Throwable*](https://php.net/Throwable) to mark an [*Exception*](https://php.net/Exception) as environment-related.
- [*EnvLoaderThrowable*](#envloaderthrowable) interface extends [*EnvThrowable*](#envthrowable) to mark an [*Exception*](https://php.net/Exception) as related to environment file loading.
- [*EnvParserThrowable*](#envparserthrowable) interface extends [*EnvThrowable*](#envthrowable) to mark an [*Exception*](https://php.net/Exception) as related to environment string parsing.
- [*EnvInvalidThrowable*](#envinvalidthrowable) interface extends [*EnvThrowable*](#envthrowable) to mark an [*Exception*](https://php.net/Exception) as related to environment variable invalidity.
- [*EnvTypeAliases*](#envtypealiases) interface provides PHPStan type aliases to aid static analysis.

### *EnvLoaderService*

[](#envloaderservice)

[*EnvLoaderService*](#envloaderservice) interface affords loading environment variables parsed from environment files into `$_ENV` (and possibly elsewhere).

- Notes:

    - **This is not a general-purpose configuration utility.** Instead, it is specifically for settings that change depending on the deployment environment.
    - **No environment file name is specified.** Typically, the file name will be `.env`, but consumers can specify any file name they like.
    - **No environment file format is specified.** Implementations might load from DotEnv, INI, JSON, XML, PHP, or any other environment file format.
    - **Only `$_ENV` loading is required.** Cf. the [*EnvSetterService*](#envsetterservice)interface notes.

#### *EnvLoaderService* Methods

[](#envloaderservice-methods)

- ```
    public function loadEnv(string $filename) : $this;
    ```

    - Adds environment variables to `$_ENV` (and possibly elsewhere) as parsed from an environment file.
    - Directives:

        - Implementations MUST throw [*EnvLoaderThrowable*](#envloaderthrowable) if `$filename`does not exist, is not a file, is not readable, or if reading from `$filename` fails.
        - Implementations MUST parse the contents of `$filename` for environment variables using logic equivalent to that of the [*EnvParserService*](#envparserservice) method `parseEnv()`.
        - Implementations MUST process each parsed environment variable using logic equivalent to that of the [*EnvSetterService*](#envsetterservice) method `addEnv()`.
    - Notes:

        - **Existing environment variables are not replaced.** This presumes that the existing environment variables are definitive, and only adds new variables to the environment.
- ```
    public function loadEnvIfReadable(string $filename) : $this;
    ```

    - An alias to `loadEnv()` that does not throw [*EnvLoaderThrowable*](#envloaderthrowable) when the environment file is not readable.
    - Directives:

        - Implementations MUST treat this method as an alias to `loadEnv()`, and MUST suppress [*EnvLoaderThrowable*](#envloaderthrowable).
    - Notes:

        - **Sometimes an environment file is optional.** For example, one strategy is to have a `.env` only in development, but not in production. Another is to have a base `.env` file as well as an optional deployment-specific environment file. This method allows that the non-readability of a file is not an error by catching [*EnvLoaderThrowable*](#envloaderthrowable).
- ```
    public function replaceEnv(string $filename) : $this;
    ```

    - Replaces environment variables in `$_ENV` (and possibly elsewhere) as parsed from an environment file.
    - Directives:

        - Implementations MUST throw [*EnvLoaderThrowable*](#envloaderthrowable) if `$filename`does not exist, is not a file, is not readable, or if reading from `$filename` fails.
        - Implementations MUST parse the contents of `$filename` for environment variables using logic equivalent to that of the [*EnvParserService*](#envparserservice) method `parseEnv()`.
        - Implementations MUST process each parsed environment variable using logic equivalent to that of the [*EnvSetterService*](#envsetterservice) method `setEnv()`.
    - Notes:

        - **Existing environment variables will be replaced.** This presumes that the environment file is definitive, and will overwrite existing variables.
- ```
    public function replaceEnvIfReadable(string $filename) : $this;
    ```

    - An alias to `replaceEnv()` that does not throw [*EnvLoaderThrowable*](#envloaderthrowable)when the environment file is not readable.
    - Directives:

        - Implementations MUST treat this method as an alias to `replaceEnv()` and MUST suppress [*EnvLoaderThrowable*](#envloaderthrowable).
    - Notes:

        - **Sometimes an environment file is optional.** For example, one strategy is to have a `.env` only in development, but not in production. Another is to have a base `.env` file as well as an optional deployment-specific environment file. This method allows that the non-readability of a file is not an error by catching [*EnvLoaderThrowable*](#envloaderthrowable).

### *EnvParserService*

[](#envparserservice)

[*EnvParserService*](#envparserservice) interface affords parsing a string for environment variables.

- Notes:

    - **No environment string syntax is specified.** Implementations may parse DotEnv, INI, JSON, XML, PHP, or any other syntax.

#### *EnvParserService* Methods

[](#envparserservice-methods)

- ```
    public function parseEnv(string $contents) : env_parsed_array;
    ```

    - Parses the `$contents` to return an array of environment variables.
    - Directives:

        - Implementations MUST throw [*EnvParserThrowable*](#envparserthrowable) if parsing fails.
        - Implementations MAY validate the parsed variables; implementations doing so MUST throw [*EnvInvalidThrowable*](#envinvalidthrowable) on invalidity.
        - Implementations MAY sanitize, normalize, transform, or otherwise modify the parsed variables.

### *EnvSetterService*

[](#envsetterservice)

[*EnvSetterService*](#envsetterservice) interface affords adding or replacing an environment variable in `$_ENV` (and possibly elsewhere).

- Notes:

    - **Only `$_ENV` operation is required.** Implementations might also choose to operate on other environment variable locations such as `$_SERVER`, [`putenv()`](https://php.net/putenv), [`apache_setenv()`](https://php.net/apache_setenv), and so on.

#### *EnvSetterService* Methods

[](#envsetterservice-methods)

- ```
    public function addEnv(string $name, string|int|float|bool|null $value) : void;
    ```

    - Adds an environment variable to `$_ENV` (and possibly elsewhere) if it is not already set.
    - Directives:

        - Implementations MUST NOT modify `$_ENV[$name]` when it is already set or when `$value` is `null`; otherwise ...

            - Implementations MUST set `$_ENV[$name]` to string `0` when the `$value` is boolean `false`.
            - Implementations MUST set `$_ENV[$name]` to string `1` when the `$value` is boolean `true`.
            - Implementations MUST set `$_ENV[$name]` to a `(string)` cast of the `$value` in all other cases.
        - Implementations MAY add the environment variable `$name` as appropriate to other environment locations, if and only if `$name`is not already set in that location.
    - Notes:

        - **String representations of `false` and empty-string can be easy to confuse.** The rules specified above guarantee that a `0`represents `false`, and that an empty string is just that: an empty string. (Consumers may still cast these string values as desired.)
        - **Add environment variables in non-`$_ENV` locations as desired.**Some implementations might also add to the `$_SERVER`array, others might use [`putenv()`](https://php.net/putenv), and so on.
- ```
    public function setEnv(string $name, string|int|float|bool|null $value) : void;
    ```

    - Replaces an environment variable in `$_ENV` (and possibly elsewhere).
    - Directives:

        - Implementations MUST unset `$_ENV[$name]` when the `$value` is `null`.
        - Implementations MUST set `$_ENV[$name]` to string `0` when the `$value` is boolean `false`.
        - Implementations MUST set `$_ENV[$name]` to string `1` when the `$value` is boolean `true`.
        - Implementations MUST set `$_ENV[$name]` to a `(string)` cast of the `$value` in all other cases.
        - Implementations MAY replace the environment variable `$name` as appropriate in other environment locations.
    - Notes:

        - **String representations of `null`, `false`, and empty-string can be easy to confuse.** The rules specified above guarantee that a missing environment variable represents `null`, that a string `0` represents `false`, and that an empty string is just that: an empty string. (Consumers may still cast these string values as desired.)
        - **Replace environment variables in non-`$_ENV` locations as desired.** Some implementations might also do replacements in the `$_SERVER` array, others might use [`putenv()`](https://php.net/putenv), and so on.

### *EnvGetter*

[](#envgetter)

[*EnvGetter*](#envgetter) affords getting environment variable values.

- Directives:

    - Implementations SHOULD treat this as an interface to a value object, but MAY treat it as a global values reader.
- Notes:

    - **Prefer copying environment variables into the implementation.** For example, copy `$_ENV` into a property, then retrieve values from that property. However, some implementations may find it necessary to read from the global environment directly.
    - **Consider placing environment validation logic in the constructor.**Value objects are expected to self-validate, so checking for missing or improperly-formatted environment variables is a normal behavior here.

#### *EnvGetter* Methods

[](#envgetter-methods)

- ```
    public function getEnv(string $name) : ?string;
    ```

    - Returns the `$name` environment variable value as a string, or `null` if it is not set in the environment.

### *EnvThrowable*

[](#envthrowable)

[*EnvThrowable*](#envthrowable) interface extends [*Throwable*](https://php.net/Throwable) to mark an [*Exception*](https://php.net/Exception) as environment-related.

It adds no class members.

### *EnvLoaderThrowable*

[](#envloaderthrowable)

[*EnvLoaderThrowable*](#envloaderthrowable) interface extends [*EnvThrowable*](#envthrowable) to mark an [*Exception*](https://php.net/Exception) as related to environment file loading.

It adds no class members.

### *EnvParserThrowable*

[](#envparserthrowable)

[*EnvParserThrowable*](#envparserthrowable) interface extends [*EnvThrowable*](#envthrowable) to mark an [*Exception*](https://php.net/Exception) as related to environment string parsing.

It adds no class members.

### *EnvInvalidThrowable*

[](#envinvalidthrowable)

[*EnvInvalidThrowable*](#envinvalidthrowable) interface extends [*EnvThrowable*](#envthrowable) to mark an [*Exception*](https://php.net/Exception) as related to environment variable invalidity.

It adds no class members.

### *EnvTypeAliases*

[](#envtypealiases)

[*EnvTypeAliases*](#envtypealiases) interface provides PHPStan type aliases to aid static analysis.

- ```
    env_parsed_array array

    ```

    - An `array` of variable names and values as parsed from the contents of an environment file.

Implementations
---------------

[](#implementations)

- Directives:

    - Implementations MAY define additional class members not defined in these interfaces.
- Notes:

    - **Reference implementations** may be found at .

Q & A
---------

[](#q--a)

### Why not use a general-purpose configuration system?

[](#why-not-use-a-general-purpose-configuration-system)

Environment configuration is specific to the *deployment* and not to the *application*. This nuance means a general-purpose configuration system would have to be constrained specifically to suit the purpose of declaring environment variables. Cf. :

> An app's config is everything that is likely to vary between deploys (staging, production, developer environments, etc).
>
> ...
>
> Note that this definition of "config" does not include internal application config, such as config/routes.rb in Rails, or how code modules are connected in Spring. This type of config does not vary between deploys, and so is best done in the code.
>
> Env vars are easy to change between deploys without changing any code; unlike config files, there is little chance of them being checked into the code repo accidentally; and unlike custom config files, or other config mechanisms such as Java System Properties, they are a language- and OS-agnostic standard.

With all that in mind, Env-Interop defines standard interfaces around the constraints of deployment-specific, not general-purpose, configuration.

### Why is there no validation interface?

[](#why-is-there-no-validation-interface)

Of the researched projects, a minority check to see if required environment variables are set. Of those, only one does any further validation of the environment variable values themselves.

As such, Env-Interop advises that environment value validation is the responsibility of an [*EnvParserService*](#envparserservice) and/or of an [*EnvGetter*](#envgetter) value object.

---

###  Health Score

37

—

LowBetter than 83% of packages

Maintenance80

Actively maintained with recent releases

Popularity12

Limited adoption so far

Community10

Small or concentrated contributor base

Maturity40

Maturing project, gaining track record

 Bus Factor1

Top contributor holds 100% of commits — single point of failure

How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window.

**Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores.

**Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement.

**Maturity (30%)** — Project age, version count, PHP version support, and release stability.

###  Release Activity

Cadence

Every ~14 days

Total

3

Last Release

107d ago

### Community

Maintainers

![](https://avatars.githubusercontent.com/u/25754?v=4)[Paul M. Jones](/maintainers/pmjones)[@pmjones](https://github.com/pmjones)

---

Top Contributors

[![pmjones](https://avatars.githubusercontent.com/u/25754?v=4)](https://github.com/pmjones "pmjones (14 commits)")

---

Tags

parserloaderenvironmentenvgettersetter

###  Code Quality

Static AnalysisPHPStan

Type Coverage Yes

### Embed Badge

![Health badge](/badges/env-interop-interface/health.svg)

```
[![Health](https://phpackages.com/badges/env-interop-interface/health.svg)](https://phpackages.com/packages/env-interop-interface)
```

###  Alternatives

[nikic/php-parser

A PHP parser written in PHP

17.4k902.6M1.8k](/packages/nikic-php-parser)[doctrine/lexer

PHP Doctrine Lexer parser library that can be used in Top-Down, Recursive Descent Parsers.

11.2k910.8M118](/packages/doctrine-lexer)[erusev/parsedown

Parser for Markdown.

15.0k151.8M732](/packages/erusev-parsedown)[league/commonmark

Highly-extensible PHP Markdown parser which fully supports the CommonMark spec and GitHub-Flavored Markdown (GFM)

3.0k404.0M702](/packages/league-commonmark)[masterminds/html5

An HTML5 parser and serializer.

1.8k242.8M229](/packages/masterminds-html5)[sabberworm/php-css-parser

Parser for CSS Files written in PHP

1.8k191.2M65](/packages/sabberworm-php-css-parser)

PHPackages © 2026

[Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)