PHPackages                             jenson/convict - 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. jenson/convict

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

jenson/convict
==============

Configuration management. PHP implementation of node-convict

0.0.3(9y ago)113MITPHP

Since Mar 7Pushed 9y ago1 watchersCompare

[ Source](https://github.com/jsol/php-convict)[ Packagist](https://packagist.org/packages/jenson/convict)[ RSS](/packages/jenson-convict/feed)WikiDiscussions master Synced 3w ago

READMEChangelogDependencies (1)Versions (4)Used By (0)

php-convict
===========

[](#php-convict)

This is a php implementation of node-convict, with some additional features and some features yet to be implemented.

Install
-------

[](#install)

```
composer require jenson/convict
```

\##TODO

This is far from a completed library yet, even if it works.

The following needs to be done:

- Unit tests
- More formats
- Loading several config files at the same time
- More unit tests
- Prettying up the code
- More examples and documentation.
- Implement an optional strict check where errors are thrown if configuration is set that is not defined in the scheme.
- Better exception handling
- Even more unit tests.

Usage
-----

[](#usage)

First define a scheme and then get and set values from that scheme:

```
$scheme = '{
  "about": "Special keyword containing a short description of the program",
  "key": {
    "to": {
      "value": {
        "doc": "A value that we can set and get",
        "format": "*",
        "arg": "value",
        "shortarg": "v",
        "env": "PHP_VALUE",
        "default": "foo bar"
      }
    }
  }
}';

$config = new \Convict\Convict($scheme);

$config->validate();

$config->set('key.to.value', 'a value');
$config->get('key.to.value');
$config->get('key');
```

Can be started with

```
PHP_VALUE=val php demo.php
php demo.php --value=val
php demo.php --value val
php demo.php -vval
php demo.php --help
```

\##API

### Constructor

[](#constructor)

#### Parameters

[](#parameters)

**filename | json-string Scheme** The scheme to load, either as a filename or as a JSON string.

**Array Options** Defaults to an empty array. Valid options:

*nohelp => true* Turn of the automatic command line help.

\####Throws Throws an \\Exception if the scheme is invalid.

### Convict->get

[](#convict-get)

\####Parameters **string key** Defaults to empty. Use a dot notation to address configuration values.

\####Returns **null** If the key does not exist **mixed** If the key points to a leaf then that value is returned. If the key points to a part of the configuration tree then that sub-part is returned. An empty key returns the entire config tree.

\####Throws Should not throw an exception.

### Convict->set

[](#convict-set)

\####Parameters **string key** The key to set the value for. Use a dot notation to address configuration values. If the key doesnt exist then it will be created. **mixed value** The value to set

\####Returns Does not return anything

\####Throws Should not throw an exception.

\####Note The values set are not persisted in any way. Use Convict->writeFile to save them.

Only the leafs can carry values, and if a new leaf is created then the value on the previous position will be discarded. Example:

```
$config->set('a', 'x');
$config->get('a'); // => string 'x'

$config->set('a.b', 'y');
$config->get('a'); // => array ('b' => 'y')

$config->set('a.c', 'z');
$config->get('a'); // => array ('b' => 'y', 'c' => 'z')
```

### Convict->addFormat

[](#convict-addformat)

Set a custom format for the validator to use. Just use the class name in the format field in the scheme. Case insensitive.

### Parameters

[](#parameters-1)

**Convict\\Validator\\Validator format** An instance of a class implementing the Validator interface.

\####Returns Does not return anything

\####Throws Should not throw an exception.

\####The Validator interface *validate ($key, $value)* Should throw a Validator\\ValidationException for invalid values. *coerce ($value)* Should return a value that has been formated to fit the application.

### Convict->validate

[](#convict-validate)

#### Parameters

[](#parameters-2)

No parameters

#### Returns

[](#returns)

Does not return any value

#### Throws

[](#throws)

Will throw either a Validator\\ValidationException or an \\Exception depending on the circumstances.

#### Note

[](#note)

For convenience sake this function will set the uncaught exception handler function to handle the events it throws out. After the validation it will restore the previous exception handler.

### Convict->loadFile

[](#convict-loadfile)

#### Parameters

[](#parameters-3)

**Array | filename files** Will go through all the filenames in the array and load them in order. Also accepts a single file name.

### Returns

[](#returns-1)

Does not return any value.

### Throws

[](#throws-1)

Does not throw any exception.

### Convict->loadConfigJson

[](#convict-loadconfigjson)

#### Parameters

[](#parameters-4)

**Array | string jsons** Will go through all the JSON strings and load them to the config as if the were loaded from a file. Can also handle single JSON entries.

#### Returns

[](#returns-2)

Does not return anything

#### Throws

[](#throws-2)

Nope.

\##The config file

A config file is loaded with

```
$config->loadFile('path/to/file');
```

and a file that matches the scheme above can look like this

```
/*
* The about block in the scheme will be written here
* as a top comment when generating a config file.
*/
{
  // Can be nested to an arbitrary depth.
  "key": {
    "to": {
      "value": "Foo bar"
    }
  }
}
```

It is not fully json5 compatible, but comments are allowed (and encouraged).

The library can write a config file with

```
$config->writeConfig('path/to/file');
```

and will use the special about field in the scheme and all the doc fileds as comments.

\##Precedence The rules of precedence are:

1. Command line argument
2. Environment variable
3. Configuration file value
4. Default value
5. Throw an exception because we dont know what to do.

\##The scheme ###Format Validate the value with this format. Does not apply to runtime config::set's.

Supported formats:

- any | \*: No validation and no coercion.
- boolean: True-ish or false-ish (includes the string true, yes, 1 etc. Coerces to strict true/false.
- duration: Miliseconds or a duration string such as 5.4d, 3,2h, 100s etc (yes, it takes both . and ,). Coerces to an int representing miliseconds.
- nat: Natural number. No fractions and above zero. Coerces to int.
- path: Not implemented yet. Should verify that it is an existing path.
- Port: Valid port number.
- Size: Either bytes or a size string such as 50m or 2.3G.

You can add a new format at runtime through config::addFormat(Convict\\Validator\\Validator).

\###Arg Look for this as a long form command argument. Uses getopt in the background, so add :: afterwards to make it optional.

\###Shortarg Same as arg, but governs the short form (-X etc).

\###Env Load from this environment variable.

\###Default Use this value if nothing else comes along. Note that this will also be subjected to the format rules. This is optional, but if it is omitted and not added at runtime then an exception will be thrown when the config is instanciated.

\##Autogenerated help Per default the config listens for -h and --help and will print a help message and exit. This can be turned of by passing the option "nohelp" => true.

```
$config = new \Convict\Convict($scheme, [ 'nohelp' => true ]);
```

###  Health Score

25

—

LowBetter than 36% of packages

Maintenance20

Infrequent updates — may be unmaintained

Popularity7

Limited adoption so far

Community7

Small or concentrated contributor base

Maturity55

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

Total

3

Last Release

3394d ago

### Community

Maintainers

![](https://www.gravatar.com/avatar/f2babff5a621507c171a50d627c612ed0fad66ab851c1379995a41f3957f0389?d=identicon)[jsol](/maintainers/jsol)

---

Top Contributors

[![jsol](https://avatars.githubusercontent.com/u/8709156?v=4)](https://github.com/jsol "jsol (8 commits)")

---

Tags

configurationconfigenvironment variablescommand line arguments

###  Code Quality

TestsPHPUnit

### Embed Badge

![Health badge](/badges/jenson-convict/health.svg)

```
[![Health](https://phpackages.com/badges/jenson-convict/health.svg)](https://phpackages.com/packages/jenson-convict)
```

###  Alternatives

[symfony/options-resolver

Provides an improved replacement for the array\_replace PHP function

3.2k514.6M1.9k](/packages/symfony-options-resolver)[league/config

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

565323.7M35](/packages/league-config)[dflydev/dot-access-configuration

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

13414.5M4](/packages/dflydev-dot-access-configuration)[dmishh/settings-bundle

Database centric Symfony configuration management. Global and per-user settings supported.

114256.9k1](/packages/dmishh-settings-bundle)[jbtronics/settings-bundle

A symfony bundle to easily create typesafe, user-configurable settings for symfony applications

9558.8k3](/packages/jbtronics-settings-bundle)[caseyamcl/configula

A simple, but versatile, PHP config loader

42148.7k6](/packages/caseyamcl-configula)

PHPackages © 2026

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