PHPackages improvframework/configuration - 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. improvframework/configuration ActiveLibrary[Utility & Helpers](/categories/utility) improvframework/configuration ============================= An opinionated Configuration object for parsing Key-Value arrays. 0.2.1(10y ago)05811[1 issues](https://github.com/improvframework/configuration/issues)BSD-3-ClausePHPPHP >=5.6.0CI failing Since Jun 10Pushed 6y ago1 watchersCompare [ Source](https://github.com/improvframework/configuration)[ Packagist](https://packagist.org/packages/improvframework/configuration)[ Docs](https://github.com/improvframework/configuration)[ RSS](/packages/improvframework-configuration/feed)WikiDiscussions master Synced 4w ago READMEChangelog (3)Dependencies (11)Versions (4)Used By (0) [![Build Status](https://camo.githubusercontent.com/defcab8ceec07729dad3755c0c1500daddc8ad60895ad75d9add4f8a720f6e20/68747470733a2f2f7472617669732d63692e6f72672f696d70726f766672616d65776f726b2f636f6e66696775726174696f6e2e7376673f6272616e63683d6d6173746572)](https://travis-ci.org/improvframework/configuration)[![Dependency Status](https://camo.githubusercontent.com/e26ad8a8bba610694c533f1623cfb8210dc9feb8a27f7d12c5240384a3fddfad/68747470733a2f2f7777772e76657273696f6e6579652e636f6d2f757365722f70726f6a656374732f3537353939313334373735376130303033346463346639352f62616467652e7376673f7374796c653d666c6174)](https://www.versioneye.com/user/projects/575991347757a00034dc4f95)[![Code Climate](https://camo.githubusercontent.com/509feb0e07922e5b81d5196a86ed8f8280d62fdd7061a4111db3abf2fb85bfa5/68747470733a2f2f636f6465636c696d6174652e636f6d2f6769746875622f696d70726f766672616d65776f726b2f636f6e66696775726174696f6e2f6261646765732f6770612e737667)](https://codeclimate.com/github/improvframework/configuration)[![Coverage Status](https://camo.githubusercontent.com/a0d2a35930088bfddc4b3d7f72e6db95cce50c561ae140949608e90e10ee4da3/68747470733a2f2f636f766572616c6c732e696f2f7265706f732f696d70726f766672616d65776f726b2f636f6e66696775726174696f6e2f62616467652e7376673f6272616e63683d6d617374657226736572766963653d676974687562)](https://coveralls.io/github/improvframework/configuration?branch=master)[![HHVM Status](https://camo.githubusercontent.com/2f999de3021d36417eb3aaeddc0ba8a07f94381f05a00ba7f45dba2098261c8f/687474703a2f2f6868766d2e683463632e64652f62616467652f696d70726f766672616d65776f726b2f636f6e66696775726174696f6e2e737667)](http://hhvm.h4cc.de/package/improvframework/configuration) Improv Framework - Configuration ================================ [](#improv-framework---configuration) An opinionated Configuration object for parsing Key-Value arrays. Overview -------- [](#overview) Almost all applications require some sort of runtime Configuration. Often, this is done via environment variables, XML or YML files, Property files, etc. Regardless of the mechanism, the configuration typically exists as an array of string Key-Value pairs at some point during application bootstrapping. In many cases, multiple values will have to be encoded into a single entry, which will need to be parsed and transformed into something meaningful to the application. Some values, like a list a single string of multiple IP addresses (e.g.). might need to be extracted into an array of the same, while other values may simply require conversion to native integers or booleans. Aside from the primitive mappings, each application will likely have a unique set of necessary transformations than any other. There may be times when an incoming set of Key-Value pairs contains several more tuples than a specific, "configurable" portion of an application may need. This is particularly common for Dockerized services wherein there are many environment variables, but only some of them are intended to affect the *application's* behavior; the balance is typically used for container or OS -level instruction. The bootstrapping portion of an application may receive *all* Key-Value pairs from the environment, although it is really only concerned with a small few. Similarly, there may be components or subcomponents within the application that also demand tailored config, but unrelated to any other portion of the software. In these cases, it is sometimes desirable to limit the scope of any "Configuration" object to only those items with which a specific portion of the application is concerned. The `\Improv\Configuration` library aims to ease the parsing of Key-Value pairs into objects that are useful within the context of a specific application, without requiring extension or bloating of the Configuration object, itself. Further, it provides the ability to quickly organize related configurations into dedicated objects as desired. Package Installation -------------------- [](#package-installation) ### Using Composer (Recommended) [](#using-composer-recommended) ``` composer require improvframework/configuration ``` ### Manual [](#manual) Each release is available for download from the [releases page on Github](https://github.com/improvframework/configuration/releases). Alternatively, you may fork, clone, and [build the package](#buildpackage). Then, install into the location of your choice. This package conforms to PSR-4 autoloading standards. Usage ----- [](#usage) Suppose some set of environment variables, the means by which they end up "in" the environment aside (Mesos, `docker run -e""`, `docker-compose.yml`, etc): ``` APP_DEBUG_ON="0" APP_DEBUG_VERBOSITY="4" APP_DB_READ_POOL="mysql://dbname=appname;host=1.1.1.1|mysql://dbname=appname;host=2.2.2.2" APP_DB_READ_USER="username" APP_DB_READ_PASS="password" APP_DB_WRITE_POOL="mysql://dbname=appname;host=2.2.0.0" APP_DB_WRITE_USER="username" APP_DB_WRITE_PASS="password" APP_MAX_LOGIN_ATTEMPTS="3" APP_WHITELIST_CIDR="123.456.7.8/32|123.456.255/12," APP_SOMESERVICE_API_KEY="oJE5Zh1HUATturnZFHgHuYEZk1q30TWkdIQ" APP_SOMESERVICE_API_SECRET="4vqK8XYZef1KygvHxROhjGRPAhMteHdMD6LD0a" APP_SOMESERVICE_API_URL="https://api.example.com/v1.5" NGINX_MAX_BODY_SIZE="4M" NGINX_SENDFILE="off" PHPFPM_HEADER_SIZE="4M" PHPFPM_BUFFER_COUNT="16" FPM_BUFFER_SIZE="1M" ``` ### Basic Key Reading [](#basic-key-reading) Read in all configuration, do some existence checking, and pluck a couple elements out: ``` $config = new \Improv\Configuration($_ENV); $config->has('APP_DEBUG_VERBOSITY'); // true $config->has('SOME_OTHER_KEY'); // false $config->get('APP_DEBUG_VERBOSITY'); // string(1) "4" $config->get('PHPFPM_BUFFER_COUNT'); // string(2) "16" ``` ### Prefix Filtration [](#prefix-filtration) The environment variables above are nicely "namespaced" to indicate their intention/direction within the container. If our application is really only concerned with the variables that are prefixed with `APP_`, we can filter to just those by passing a second parameter during instantiation. Note here that when the key is requested, you no longer need to specify the prefix: ``` $config = new \Improv\Configuration($_ENV, 'APP_'); $config->get('DEBUG_VERBOSITY'); // string(1) "4" $config->get('APP_DEBUG_VERBOSITY'); // throws InvalidKeyException $config->get('PHPFPM_BUFFER_COUNT'); // throws InvalidKeyException ``` This becomes particularly useful when registering and referencing various configurations within, say, a container and services within the application are only interested in certain variables. The `withPrefix` method will take a given, "base" Configuration object and return a new one from it, applying another layer of filtering by prefix on from the keys in the base. ``` $container['config.app'] = function () { return new \Improv\Configuration($_ENV, 'APP_'); }; $container['config.debug'] = function (Container $container) { $base = $container->get('config.app'); return $base->withPrefix('DEBUG_'); }; $container['config.db'] = function (Container $container) { $base = $container->get('config.app'); return $base->withPrefix('DB_'); }; $container['config.api'] = function (Container $container) { $base = $container->get('config.app'); return $base->withPrefix('SOMESERVICE_API_'); }; // ... // $container['database.read'] = function (Container $container) { $dbconfig = $container->get('config.db'); return new Database( $dbconfig->get('READ_POOL'), $dbconfig->get('READ_USER'), $dbconfig->get('READ_PASS') ); }; // ... // $container['api.service'] = function (Container $container) { $apiconfig = $container->get('config.api'); return new ApiService( $apiconfig->get('URL'), $apiconfig->get('KEY'), $apiconfig->get('SECRET') ); }; ``` ### Mapping Values [](#mapping-values) The values pulled out of the environment most often come through as strings, and may also be encoded in some way, for example multiple values delimited by pipes, semi-colons or commas. It may be desirable to map strings to primitive types like `int` or `bool`, and to explode delimited strings into arrays or even objects. This library supports this behavior. With no action, values come out "as is". ``` $config = new \Improv\Configuration($_ENV, 'APP_'); $config->get('DEBUG_ON'); // string(1) "0" $config->get('DEBUG_VERBOSITY'); // string(1) "4" $config->get('MAX_LOGIN_ATTEMPTS'); // string(1) "3" $config->get('APP_WHITELIST_CIDR'); // string(29) "123.456.7.8/32|123.456.255/12" $config->get('DB_READ_POOL'); // string(71) "mysql://dbname=appname;host=1.1.1.1|mysql://dbname=appname;host=2.2.2.2" ``` The `map` method can be used to specify translations using built-in methods or callbacks. Additionally, multiple keys can be targeted for the same mapping at once: ``` $config = new \Improv\Configuration($_ENV, 'APP_'); // Use the built-in boolean mapper $config->map('DEBUG_ON')->toBool(); // Assign multiple keys at once, using built-in int mapper $config->map('DEBUG_VERBOSITY', 'MAX_LOGIN_ATTEMPTS')->toInt(); // Invoke the "using" method to and callback to parse values $config->map( 'WHITELIST_CIDR', 'DB_READ_POOL' )->using( function($val) { return explode('|', $val); } ); // Now, all future retrievals from any part of the application // will spit out the translated value(s) // ... // $config->get('DEBUG_ON'); // bool(false) $config->get('DEBUG_VERBOSITY'); // int(4) $config->get('MAX_LOGIN_ATTEMPTS'); // int(3) $config->get('WHITELIST_CIDR'); // array(2) { // [0] => string(14) "123.456.7.8/32" // [1] => string(14) "123.456.255/12" // } ``` The `using` method can take any valid `callable`, the signature of which should accept a single string value as input. The `callable` can return any value relevant to the application - primitives or even full-blown objects. A callable may also exist as any class that implements the `__invoke($value)` method. This makes it possible to share "Maps", inject dependencies, etc. ``` class DelimiterMap { private $delimiter; public function __construct($delimiter) { $this->delimiter = $delimiter; } public function __invoke($value) { return explode($this->delimiter, $value); } } // ... // $config->map('WHITELIST_CIDR')->using(new DelimiterMap('|')); ``` Notes and Issues ---------------- [](#notes-and-issues) Please note that this is a new package, currently in beta. Feel free to reach out with ideas, bug reports, or contribution questions. Additional Documentation ------------------------ [](#additional-documentation) You may [run the API Doc build target](#buildtargets) to produce and peruse API documentation for this package. Running the Build/Test Suite ----------------------------------------------------------------- [](#running-the-buildtest-suite) This package makes extensive use of the [Phing](https://www.phing.info/ "Click to Learn More") build tool. Below is a list of notable build targets, but please feel free to peruse the `build.xml` file for more insight. ### Default Target [](#default-target) `./vendor/bin/phing` will execute the `build` target (the same as executing `./vendor/bin/phing build`). This performs a linting, syntax check, runs all static analysis tools, the test suite, and produces API documentation. ### "Full" Packaging Target [](#full-packaging-target) Executing `./vendor/bin/phing package` will run all above checks and, if passing, package the source into a shippable file with only the relevant source included therein. ### Selected Individual Targets [](#selected-individual-targets) - Run the Tests - `./vendor/bin/phing test` - `./vendor/bin/phpunit` - Perform Static Analysis - `./vendor/bin/phing static-analysis` - The generated reports are in `./build/output/reports` - Produce API Documentation - `./vendor/bin/phing documentapi` - The generated documentation is in `./build/docs/api` - Build Package from Source - `./vendor/bin/phing package` - The artifacts are in `./build/output/artifacts` [![License](https://camo.githubusercontent.com/34be563e113979706201ffab73fdb8cea31b76ea3c5eb8d4e15f90d491d8cc4a/68747470733a2f2f706f7365722e707567782e6f72672f696d70726f766672616d65776f726b2f636f6e66696775726174696f6e2f6c6963656e7365)](https://packagist.org/packages/improvframework/configuration)[![Latest Stable Version](https://camo.githubusercontent.com/b1ea75e19279e325032ddc102397064d48b0b8081a4c553513b7cde07aefdc04/68747470733a2f2f706f7365722e707567782e6f72672f696d70726f766672616d65776f726b2f636f6e66696775726174696f6e2f762f737461626c65)](https://packagist.org/packages/improvframework/configuration)[![Latest Unstable Version](https://camo.githubusercontent.com/3d93605da98036d76c11e57c86125bc1154ff1c94ec0815a570f15abfbb11ab9/68747470733a2f2f706f7365722e707567782e6f72672f696d70726f766672616d65776f726b2f636f6e66696775726174696f6e2f762f756e737461626c65)](https://packagist.org/packages/improvframework/configuration)[![Total Downloads](https://camo.githubusercontent.com/6622886e1d5cc08ca3fedf5c1238bc01b25591a46a3338487b2afd5b30702d9c/68747470733a2f2f706f7365722e707567782e6f72672f696d70726f766672616d65776f726b2f636f6e66696775726174696f6e2f646f776e6c6f616473)](https://packagist.org/packages/improvframework/configuration) ### Health Score 25 — LowBetter than 35% of packages Maintenance20 Infrequent updates — may be unmaintained Popularity14 Limited adoption so far Community8 Small or concentrated contributor base Maturity50 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 ~2 days Total 3 Last Release 3668d ago ### Community Maintainers ![](https://www.gravatar.com/avatar/7c588349ae21df6915ac10b1931eafc8fd8f5e65e56e18658de82085ff2c876e?d=identicon)[jimdelois](/maintainers/jimdelois) --- Top Contributors [![jimdelois](https://avatars.githubusercontent.com/u/1907498?v=4)](https://github.com/jimdelois "jimdelois (13 commits)") --- Tags keywords ### Code Quality TestsPHPUnit Code StylePHP\_CodeSniffer ### Embed Badge ![Health badge](/badges/improvframework-configuration/health.svg) ``` [![Health](https://phpackages.com/badges/improvframework-configuration/health.svg)](https://phpackages.com/packages/improvframework-configuration) ``` ### Alternatives [arcanedev/seo-helper SEO Helper is a framework agnostic package that provides tools & helpers for SEO (Laravel supported). 331469.8k4](/packages/arcanedev-seo-helper) PHPackages © 2026 [Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)