PHPackages                             timdev/typed-config - 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. [Utility & Helpers](/categories/utility)
4. /
5. timdev/typed-config

ActiveLibrary[Utility & Helpers](/categories/utility)

timdev/typed-config
===================

Strongly-typed configuration for PHP applications

0.1.3(1y ago)1303[1 issues](https://github.com/timdev/typed-config/issues)1MITPHPPHP ~7.4.0 || ^8CI passing

Since Sep 11Pushed 1y ago1 watchersCompare

[ Source](https://github.com/timdev/typed-config)[ Packagist](https://packagist.org/packages/timdev/typed-config)[ RSS](/packages/timdev-typed-config/feed)WikiDiscussions main Synced 1mo ago

READMEChangelog (1)Dependencies (3)Versions (6)Used By (1)

timdev/typed-config
===================

[](#timdevtyped-config)

What's This?
------------

[](#whats-this)

A small library to provide strictly typed access to data in an array, intended for use with a nested array of application configuration data. Nested values are dereferenced with dotted strings.

Usage
-----

[](#usage)

### Install

[](#install)

Install this package with composer:

```
composer require timdev/typed-config
```

### Usage

[](#usage-1)

In a nutshell:

```
declare(strict_types=1);

// This should already be set in your php.ini, but this library depends on it,
// so you should verify that's set.
ini_set('assert.exception', 1);

// Could come from anywhere.
$configArray = [
    'myapp' => [
        'some-api' => [
            'baseUrl' => 'https://example.com/v1/',
            'timeout' => 30
        ],
        'allowed_ips' => [
            '192.168.0.1',
            '192.168.0.50'
        ],
        'optional_value' => null
    ]
];

$config = new Config($configArray);

// Methods have narrow return type declarations:
$baseUrl = $config->string('myapp.some-api.baseUrl');
$timeout = $config->int('myapp.some-api.timeout');
$allowed = $config->list('myapp.allowed_ips');

// Attempting to access an undefined value throws.
$port = $config->int('invalid.key');  // Throws \TimDev\TypedConfig\Exception\KeyNotFound

// Note that the main methods do not have nulalble return types.
$optional = $config->bool('myapp.optional_value'); // Also throws!

// Use ->nullable to access valeus that are defined, but might be null:
$optional = $config->nullable->bool('myapp.optional_value');
```

Assumptions and Design
----------------------

[](#assumptions-and-design)

In order to use this library effectively, it's important to understand its design and the assumptions that inform that design.

### Assumption: All valid configuration values are defined

[](#assumption-all-valid-configuration-values-are-defined)

As demonstrated in example above, client code attempting to access an undefined value will throw. Our opinion is that a library or application should ship a complete default configuration. This is always a win for users. This design means that users are alerted early when they try to access an invalid key due to a typo or transcription error.

If you think you need an optional configuration parameter, you should instead provide a default such as `null` or perhaps `[]`.

### Design: Relies on PHP's `assert()`

[](#design-relies-on-phps-assert)

[assert](https://www.php.net/assert) is a language construct with a very useful mechanism: they are optimized out in production. This library uses `assert()` to type-check your configuration values before they're returned from the various accessor-methods.

If you're unfamiliar with the configuration values that affect how [assert](https://www.php.net/assert)works, you should review the documentation and your environment's configuration before using this library. The short version is that you'll want to ensure that `assert.exception = 1` and `zend.assertion = 1` in your development and testing environments.

Because this library depends on assert(), the type checks are optimized away in production environments (where `zend.assertion = 0`). This reduces some overhead but means that configuration access that would throw an `AssertionError` in development will instead:

1. Throw a `TypeError`, or
2. Not throw anything, in the case of a hash/list mismatch.

Motivation
----------

[](#motivation)

We developed this while building an application with [mezzio](https://docs.mezzio.dev/), where configuration data are generally pulled from an array. Arrays are nice, but often cause you to have to:

1. Code defensively whenever you pull some value from your `$config` array.
2. Add assertions or comments to let your static analyzer of choice figure out what is happening.

This library is an attempt to improve that situation.

Alternatives
------------

[](#alternatives)

There are other libraries that approach the problem from different perspectives.

[selective-php/config](https://github.com/selective-php/config) takes a similar approach in that it provides strictly typed methods to fetch (possibly nullable) values. Unlike this library, it enforces types by casting values as it returns them. We take a more strict posture, and consider mismatched types to be an error in the software. Its nullable-typed methods return null if a config key is not defined, while we consider that to be an error as well.

[setbased/typed-config](https://github.com/SetBased/php-typed-config) is also similar. Like the previously discussed library, it will attempt to cast whatever it finds in the config data to the required type, and is more permissive about undefined config keys than this library is.

[league/config](https://config.thephpleague.com/) takes an even more strict approach by helping you define a strict schema for your configuration data. We really like that approach (at least for some contexts), but are somewhat bewildered that it provides a single `get(string $key): mixed` accessor.

To Do
-----

[](#to-do)

- Do some benchmarks and determine if our usage of [assert](https://www.php.net/assert) is actually providing any tangible benefit.

###  Health Score

25

—

LowBetter than 37% of packages

Maintenance23

Infrequent updates — may be unmaintained

Popularity15

Limited adoption so far

Community9

Small or concentrated contributor base

Maturity44

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 ~381 days

Total

4

Last Release

565d ago

PHP version history (3 changes)0.1.0PHP ^7.4 || ^8.0

0.1.2PHP ~7.4.0 || ~8.0.0 || ~8.1.0

0.1.3PHP ~7.4.0 || ^8

### Community

Maintainers

![](https://www.gravatar.com/avatar/4eb475c7f4d3d1df5053f83417bf4e756a35b59d1686cd7d379055da2828017f?d=identicon)[timdev](/maintainers/timdev)

---

Top Contributors

[![timdev](https://avatars.githubusercontent.com/u/513999?v=4)](https://github.com/timdev "timdev (16 commits)")

---

Tags

configurationarrayconfigdotdot-accessstrong typed

### Embed Badge

![Health badge](/badges/timdev-typed-config/health.svg)

```
[![Health](https://phpackages.com/badges/timdev-typed-config/health.svg)](https://phpackages.com/packages/timdev-typed-config)
```

###  Alternatives

[league/config

Define configuration arrays with strict schemas and access values with dot notation

564302.2M24](/packages/league-config)[symfony/options-resolver

Provides an improved replacement for the array\_replace PHP function

3.2k493.9M1.6k](/packages/symfony-options-resolver)[dflydev/dot-access-configuration

Given a deep data structure representing a configuration, access configuration by dot notation.

13414.5M4](/packages/dflydev-dot-access-configuration)[jbzoo/data

An extended version of the ArrayObject object for working with system settings or just for working with data arrays

891.6M23](/packages/jbzoo-data)[illuminatech/array-factory

Allows DI aware object creation from array definition

2159.6k6](/packages/illuminatech-array-factory)[selective/transformer

A strictly typed array transformer with dot-access, fluent interface and filters.

3817.8k1](/packages/selective-transformer)

PHPackages © 2026

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