README

code-distortion/options 是一个用于简单、灵活和表达性强的选项管理的 PHP 库。

use CodeDistortion\Options\Options;

$results = Options::parse('sendAlerts dailyLimit=123.45 !applyDailyLimit currency=AUD plan="Silver Plan"');
// [ 'sendAlerts' => true,
//   'dailyLimit' => 123.45,
//   'applyDailyLimit' => false,
//   'currency' => 'AUD',
//   'plan' => 'Silver Plan' ]

// when used programatically
$options = Options::resolve('sendEmails sendSms !sendSlack');
$value = $options->get('sendEmails'); // true
$value = $options->get('sendSlack'); // false

安装

使用 composer 安装此包

composer require code-distortion/options

使用方法

parse() 方法将接受您的字符串并将其分解成单独的选项

use CodeDistortion\Options\Options;

$results = Options::parse('sendEmails sendSms !sendSlack');
// [ 'sendEmails' => true,
//   'sendSms' => true,
//   'sendSlack' => false ]

值类型

您可以将选项值指定为 表达性字符串 或 键值对数组。

表达性字符串格式

'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]

多个字符串值可以合并在一起，并用空格 " " 或逗号 ,（或两者）分隔

'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']

注意： 使用正则表达式来检查上述字符串值。您可能希望使用它们以方便起见，或者使用下面的纯数组以获得更快的速度。

数组键值对

您可以直接指定为数组来指定值

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

注意： 您可以使用此库指定非标量值（例如嵌套数组），但它们不会被特别处理。它们目前被当作标量值处理。

在代码中使用

您可以使用 Options 实例以编程方式处理值。resolve() 方法将解析输入并返回一个 Options 对象，然后您可以在代码中查询它

$options = Options::resolve('sendEmails sendSms !sendSlack');
$has = $options->has('sendEmails'); // true
$has = $options->has('sendTweet');  // false
$value = $options->get('sendEmails'); // true
$value = $options->get('sendTweet');  // null

指定默认值

您可以通过调用 defaults() 来指定要使用的默认回退值

// set the defaults for the first time (or replaces them completely)
$defaults = 'sendEmails sendSms !sendSlack';
$options = Options::defaults($defaults);

// add to the existing defaults (overriding where necessary)
$quietModeDefaults = '!sendSms';
$options->addDefaults($quietModeDefaults);

// retrieve the defaults back as an array
$options->getDefaults();

解析具有默认值的选项集

要结合默认值和自定义值，请使用 defaults() 方法，然后调用 resolve()

// combine default and custom values
$defaults = 'sendEmails sendSms !sendSlack';
$userPrefs = '!sendEmails sendSms';
$options = Options::defaults($defaults)->resolve($userPrefs);

// check if particular options exist
$has = $options->has('sendEmails'); // true
$has = $options->has('sendTweet');  // false
$has = $options->hasDefault('sendSlack'); // true
$has = $options->hasCustom('sendSlack');  // false

// retrieve individual values from $options
$value = $options->get('sendEmails'); // false
$value = $options->get('sendTweet');  // null
$value = $options->getDefault('sendEmails'); // true
$value = $options->getCustom('sendEmails');  // false

// get the results combined
$results = $options->all();
// [ 'sendEmails' => false,
//   'sendSms' => true,
//   'sendSlack' => false ]

注意： 如果您指定了默认值，任何传递给 resolve() 且不在默认值中出现的值将生成异常，除非在之前调用过 allowUnexpected()

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

// the 'sendTweet' option is now allowed because allowUnexpected() was called
$options = Options::defaults('sendEmails sendSms !sendSlack')->allowUnexpected()->resolve('sendTweet');

验证

如果您想验证给定的值，可以将回调闭包传递给 validator()。每个选择值都将传递到您的回调以检查其有效性。如果它返回一个假值，将引发异常。

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

// InvalidOptionException: "The option "sendEmails" and/or it's value "yes" are not allowed"
Options::validator($callback)->defaults('sendEmails sendSms !sendSlack')->resolve('sendEmails=yes');

链式调用

以下方法可以链式调用，并且任何方法都可以静态调用以实例化一个 Options 对象

$options = Options::allowUnexpected()->validator($callback)->defaults($defaults)->addDefaults($extraDefaults)->resolve($customValues); // chainable
$results = $options->all();

测试

composer test

变更日志

有关最近更改的更多信息，请参阅 CHANGELOG。

SemVer

此库使用 SemVer 2.0.0 版本控制。这意味着对 X 的更改表示重大更改：0.0.X、0.X.y、X.y.z。当此库更改为版本 1.0.0、2.0.0 等时，这并不一定表示它是一个值得注意的版本，它仅仅表示更改是破坏性的。

实体树

此包是 实体树。如果您在生产环境中使用它，那么我们请求您 为世界种一棵树 以感谢我们的工作。通过为实体树森林做出贡献，您将为当地家庭创造就业机会并恢复野生动物栖息地。

贡献

有关详细信息，请参阅 CONTRIBUTING。

行为准则

有关详细信息，请参阅 CODE_OF_CONDUCT。

安全性

如果您发现任何与安全相关的问题，请通过电子邮件 tim@code-distortion.net 反馈，而不是使用问题跟踪器。

致谢

• Tim Chandler

许可证

MIT许可证（MIT）。更多信息请参阅 许可证文件。