PHPackages                             code-distortion/options - 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. code-distortion/options

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

code-distortion/options
=======================

Flexible, expressive option handling

0.6.1(1y ago)026.1k2MITPHPPHP 7.0.\* | 7.1.\* | 7.2.\* | 7.3.\* | 7.4.\* | 8.0.\* | 8.1.\* | 8.2.\* | 8.3.\* | 8.4.\*CI passing

Since Nov 3Pushed 5mo ago1 watchersCompare

[ Source](https://github.com/code-distortion/options)[ Packagist](https://packagist.org/packages/code-distortion/options)[ Docs](https://github.com/code-distortion/options)[ RSS](/packages/code-distortion-options/feed)WikiDiscussions master Synced 4d ago

READMEChangelog (10)Dependencies (6)Versions (16)Used By (2)

Options
=======

[](#options)

[![Latest Version on Packagist](https://camo.githubusercontent.com/599f4d3347c18e1031f6c2c253cebd57d19e8524cc68b27082649f24d833140d/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f762f636f64652d646973746f7274696f6e2f6f7074696f6e732e7376673f7374796c653d666c61742d737175617265)](https://packagist.org/packages/code-distortion/options)[![PHP Version](https://camo.githubusercontent.com/fc938f3a4835b52c2a9130b7f455bbf867cd4ea2b3d1566ef8464eca13274717/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f5048502d372e30253230746f253230382e342d626c75653f7374796c653d666c61742d737175617265)](https://camo.githubusercontent.com/fc938f3a4835b52c2a9130b7f455bbf867cd4ea2b3d1566ef8464eca13274717/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f5048502d372e30253230746f253230382e342d626c75653f7374796c653d666c61742d737175617265)[![GitHub Workflow Status](https://camo.githubusercontent.com/a6adaa831801ebb4bd23d0f1159db219cc718555f37e4e513913ba3e81a22342/68747470733a2f2f696d672e736869656c64732e696f2f6769746875622f616374696f6e732f776f726b666c6f772f7374617475732f636f64652d646973746f7274696f6e2f6f7074696f6e732f72756e2d74657374732e796d6c3f6272616e63683d6d6173746572267374796c653d666c61742d737175617265)](https://github.com/code-distortion/options/actions)[![Buy The World a Tree](https://camo.githubusercontent.com/dc3f77a9b22c3bc83c7b7d863bf138a7ca3418f1826b0b16d073d0aa87c16bc4/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f74726565776172652d2546302539462538432542332d6c69676874677265656e3f7374796c653d666c61742d737175617265)](https://plant.treeware.earth/code-distortion/options)[![Contributor Covenant](https://camo.githubusercontent.com/902d296a65b2997bada7e7717fd929d9177f3bd95414cbb5ea2ed843c680f314/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f636f6e7472696275746f72253230636f76656e616e742d76322e3125323061646f707465642d6666363962342e7376673f7374796c653d666c61742d737175617265)](.github/CODE_OF_CONDUCT.md)

***code-distortion/options*** is a PHP library for managing options in a flexible and expressive way.

```
use CodeDistortion\Options\Options;

$results = Options::new('sendEmails sendSms !sendSlack plan=gold value=123.45')->all();

// [ 'sendEmails' => true,
//   'sendSms' => true,
//   'sendSlack' => false,
//   'plan' => 'gold',
//   'value' => 123.45 ]
```

Table of Contents
-----------------

[](#table-of-contents)

- [Installation](#installation)
- [Usage](#usage)
    - [Simple Usage](#simple-usage)
    - [Programmatic Usage](#programmatic-usage)
- [Specifying Default Values](#specifying-default-values)
- [Restricting Options](#restricting-options)
- [Validation](#validation)
- [Fluent Interface](#fluent-interface)
- [Which Types Of Values Can I Specify?](#which-types-of-values-can-i-specify)
    - [Expressive String Format](#expressive-string-format)
    - [Array Key-Value-Pairs](#array-key-value-pairs)

Installation
------------

[](#installation)

Install the package via composer:

```
composer require code-distortion/options
```

Usage
-----

[](#usage)

### Simple Usage

[](#simple-usage)

Specify values by passing them to `Options::new()`. This will take your set of options and break them down into individual ones.

An instance of `Options` is returned. Call `all()` on it to get the resolved values.

```
use CodeDistortion\Options\Options;

$results = Options::new('sendEmails sendSms !sendSlack')->all();
// or
$results = Options::new()->options('sendEmails sendSms !sendSlack')->all();

// [ 'sendEmails' => true,
//   'sendSms' => true,
//   'sendSlack' => false ]
```

`all()` will return the options in alphabetical order.

### Programmatic Usage

[](#programmatic-usage)

You can also interact with your `Options` instance in a more programmatic fashion.

```
use CodeDistortion\Options\Options;

$options = Options::new('sendEmails sendSms !sendSlack');
// or
$options = Options::new()->options('sendEmails sendSms !sendSlack');

$has = $options->has('sendEmails');   // true
$has = $options->has('sendTweet');    // false
$value = $options->get('sendEmails'); // true
$value = $options->get('sendTweet');  // null
```

Calling `options()` multiple times will *replace* the previous options.

However you can *amend* the existing options by calling `amendOptions()`. This allows you to add or override existing options with new ones.

```
$myOptions = 'sendEmails sendSms sendSlack';
$extraOptions = '!sendSms';
$options = Options::new()
    ->options($myOptions)
    ->amendOptions($extraOptions);
```

Specifying Default Values
-------------------------

[](#specifying-default-values)

You can apply default values to use by passing them to `defaults()`. The default values will be applied for any options that aren't specified when calling `options()`.

It doesn't matter which order you call `defaults()` and `resolve()` in.

```
$options = Options::new()
    ->defaults('sendEmails sendSms sendSlack')
    ->options('!sendEmails');

$options->get('sendEmails'); // false
$options->get('sendSms');    // true
```

Calling `defaults()` multiple times will *replace* the previous defaults.

However you can *amend* the existing defaults by calling `amendDefaults()`. This allows you to add or override existing defaults with new ones.

```
$defaults = 'sendEmails sendSms sendSlack';
$quietModeDefaults = '!sendSms';
$options = Options::new()
    ->defaults($defaults)
    ->amendDefaults($quietModeDefaults);
```

Restricting Options
-------------------

[](#restricting-options)

You can restrict the possible options to those available in the defaults by calling `restrictUnexpected()`.

Options passed to `options()` that aren't present in the defaults will generate an `InvalidOptionException`.

```
// the 'sendTweet' option is allowed because restrictUnexpected() was not called
$options = Options::new()
    ->defaults('sendEmails sendSms !sendSlack')
    ->options('sendTweet');

// InvalidOptionException: "The option "sendTweet" was not expected"
$options = Options::new()
    ->defaults('sendEmails sendSms !sendSlack')
    ->restrictUnexpected()
    ->options('sendTweet');
```

Validation
----------

[](#validation)

You can validate the options by passing a callback to `validator()`.

Each option will be passed to your callback, letting you choose if it's valid.

If your callback returns false, that option will be ignored.

```
$validatorCallback = function (string $name, $value, bool $wasExpected): bool {
    return is_bool($value); // ensure the value is a boolean
};

// sendEmails is ignored because it's not a boolean
Options::new()
    ->validator($validatorCallback)
    ->defaults('sendEmails sendSms !sendSlack')
    ->options('sendEmails=yes');
```

You can also pass a second parameter to `validator()` instructing it to throw an exception if a value is invalid.

```
// InvalidOptionException: "The option "sendEmails" and/or it's value "yes" are not allowed"
Options::new()
    ->validator($validatorCallback, true) // options('sendEmails=yes');
```

Fluent Interface
----------------

[](#fluent-interface)

The `options()`, `amendOptions()`, `defaults()`, `amendDefaults()`, `restrictUnexpected()` and `validator()` methods can be chained together, and can be called in any order.

```
// instantiate
$options = new Options();
$options = new Options($myOptions);
$options = Options::new();
$options = Options::new($myOptions);

// call and chain any of these, in any order
$options->options($myOptions)
    ->amendOptions($extraOptions)
    ->defaults($defaults)
    ->amendDefaults($extraDefaults)
    ->restrictUnexpected()
    ->validator($validatorCallback);
```

```
// then consult your Options instance like normal
$results = $options->all();
$has = $options->has('sendEmails');
$value = $options->get('sendEmails');
```

Which Types Of Values Can I Specify?
------------------------------------

[](#which-types-of-values-can-i-specify)

### Expressive String Format

[](#expressive-string-format)

You can specify values as strings, with or without modifiers.

```
'myVal' // ['myVal' => true]

// with modifiers
'+myVal' // ['myVal' => true]
'-myVal' // ['myVal' => false]
'!myVal' // ['myVal' => false]

// special values
'myVal=true'   // ['myVal' => true] (boolean true)
'myVal=false'  // ['myVal' => false] (boolean false)
'myVal=null'   // ['myVal' => null] (actual null)
'myVal=100'    // ['myVal' => 100] (an integer)
'myVal=123.45' // ['myVal' => 123.45] (a float)

// strings
'myVal='          // ['myVal' => '']
'myVal=somevalue' // ['myVal' => 'somevalue']

// quoted value strings
'myVal="true"'           // ['myVal' => 'true'] (not a boolean)
'myVal="some value"'     // ['myVal' => 'some value']
'myVal="some \"value\""' // ['myVal' => 'some "value"']
"myVal='some value'"     // ['myVal' => 'some value']
"myVal='some \'value\''" // ['myVal' => "some 'value'"]
"myVal=\"new\nline\""    // ['myVal' => "new\nline"]

// quoted key strings
'"my val"=true'     // ['my val' => true]
'"my \"val\""=true' // ['my "val"' => true]
"'my val'=true"     // ['my val' => true]
"'my \'val\''=true" // ["my 'val'" => true]
```

Multiple string values can be passed together at the same time, separated with spaces "` `" or a comma "`,`" (or both):

```
'myVal1=abc +myVal2 -myVal3'   // ['myVal1' => 'abc', 'myVal2' => true, 'myVal3' => false']
'myVal1=abc,+myVal2,-myVal3'   // ['myVal1' => 'abc', 'myVal2' => true, 'myVal3' => false']
'myVal1=abc, +myVal2, -myVal3' // ['myVal1' => 'abc', 'myVal2' => true, 'myVal3' => false']
```

### Array Key-Value-Pairs

[](#array-key-value-pairs)

Regular expressions are used to examine the string values above. You may wish to use them for convenience, or use plain arrays like below for faster speed.

```
['myVal' => true]
['myVal' => false]
['myVal' => 'some value']
['my val' => 'some value']
// etc
```

***Note:*** You can specify non-scalar values when passing key-value-pair arrays (e.g. nested arrays), however they aren't dealt with in any special way. They are currently treated like scalar values.

Testing This Package
--------------------

[](#testing-this-package)

- Clone this package: `git clone https://github.com/code-distortion/options.git .`
- Run `composer install` to install dependencies
- Run the tests: `composer test`

Changelog
---------

[](#changelog)

Please see [CHANGELOG](CHANGELOG.md) for more information on what has changed recently.

### SemVer

[](#semver)

This library uses [SemVer 2.0.0](https://semver.org/) versioning. This means that changes to `X` indicate a breaking change: `0.0.X`, `0.X.y`, `X.y.z`. When this library changes to version 1.0.0, 2.0.0 and so forth, it doesn't indicate that it's necessarily a notable release, it simply indicates that the changes were breaking.

Treeware
--------

[](#treeware)

This package is [Treeware](https://treeware.earth). If you use it in production, then we ask that you [**buy the world a tree**](https://plant.treeware.earth/code-distortion/options) to thank us for our work. By contributing to the Treeware forest you’ll be creating employment for local families and restoring wildlife habitats.

Contributing
------------

[](#contributing)

Please see [CONTRIBUTING](.github/CONTRIBUTING.md) for details.

### Code of Conduct

[](#code-of-conduct)

Please see [CODE\_OF\_CONDUCT](.github/CODE_OF_CONDUCT.md) for details.

### Security

[](#security)

If you discover any security related issues, please email  instead of using the issue tracker.

Credits
-------

[](#credits)

- [Tim Chandler](https://github.com/code-distortion)

License
-------

[](#license)

The MIT License (MIT). Please see [License File](LICENSE.md) for more information.

###  Health Score

45

—

FairBetter than 92% of packages

Maintenance57

Moderate activity, may be stable

Popularity23

Limited adoption so far

Community11

Small or concentrated contributor base

Maturity73

Established project with proven stability

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

Recently: every ~196 days

Total

15

Last Release

474d ago

PHP version history (7 changes)v0.1.0PHP ^7.1

0.5.3PHP ^7.1|^8.0

0.5.4PHP ^7.1 | ^8.0

0.5.5PHP 7.1.\* | 7.2.\* | 7.3.\* | 7.4.\* | 8.0.\* | 8.1.\*

0.5.7PHP 7.1.\* | 7.2.\* | 7.3.\* | 7.4.\* | 8.0.\* | 8.1.\* | 8.2.\*

0.5.8PHP 7.1.\* | 7.2.\* | 7.3.\* | 7.4.\* | 8.0.\* | 8.1.\* | 8.2.\* | 8.3.\*

0.6.0PHP 7.0.\* | 7.1.\* | 7.2.\* | 7.3.\* | 7.4.\* | 8.0.\* | 8.1.\* | 8.2.\* | 8.3.\* | 8.4.\*

### Community

Maintainers

![](https://avatars.githubusercontent.com/u/56794290?v=4)[Tim](/maintainers/code-distortion)[@code-distortion](https://github.com/code-distortion)

---

Top Contributors

[![code-distortion](https://avatars.githubusercontent.com/u/56794290?v=4)](https://github.com/code-distortion "code-distortion (54 commits)")

---

Tags

Settingsoptionsparametersdefault

###  Code Quality

TestsPHPUnit

Static AnalysisPHPStan

Code StylePHP\_CodeSniffer

Type Coverage Yes

### Embed Badge

![Health badge](/badges/code-distortion-options/health.svg)

```
[![Health](https://phpackages.com/badges/code-distortion-options/health.svg)](https://phpackages.com/packages/code-distortion-options)
```

###  Alternatives

[symfony/options-resolver

Provides an improved replacement for the array\_replace PHP function

3.2k493.9M1.6k](/packages/symfony-options-resolver)[chillerlan/php-settings-container

A container class for immutable settings objects. Not a DI container.

3427.3M21](/packages/chillerlan-php-settings-container)[graste/params

Array wrapper that eases the retrieval of values. Has parameters, options and settings and traits for inclusion in other libraries.

107.0k](/packages/graste-params)[lexxpavlov/settingsbundle

Symfony2/3/4 Settings bundle provides flexible settings (Boolean, Integer, Float, String, Text, Html), easily configurable with Sonata Admin

104.5k](/packages/lexxpavlov-settingsbundle)

PHPackages © 2026

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