README

通过选项类配置您的库的更好方式。

简单来说

像这样记录库的选项。如果您针对PHP 8.1，您应该声明选项为 'readonly'。

<?php
namespace Some\Namespace;

class MyOptions extends \Charm\AbstractOptions {

    const CACHE_OFF = 0;
    const CACHE_AUTO = 1;
    const CACHE_ON = 2;

    /**
     * Example option which is required.
     */
    public string $apiKey;

    /**
     * Example option which is not required.
     */
    public string $apiSecret = "";

    /**
     * Example option which must be among the MyOptions::CACHE_* constants.
     */
    public int $cache = self::CACHE_AUTO;

    /**
     * An integer value is required.
     */
    public int $ttl = 86400;
}

通过 new 关键字构造

<?php
$options = new Some\Namespace\MyOptions([
    'apiKey' => "some-value",
    'apiSecret' => "some-secret",
    'ttl' => 'short',
]);

通过 create() 方法构造

<?php
$options = YourOptions::create([
    'apiKey' => "some-value",
    'apiSecret' => "some-secret",
    'ttl' => 'short',
]);

可变性

如果声明为 public，则选项可变。如果声明为 protected 或 private，则只读。

在PHP 8.1中，您可以在公共属性上使用 readonly 关键字以获得非常小的性能提升。

声明选项类

<?php
class HttpClientOptions extends Charm\AbstractOptions {
    /**
     * Most permissive option. It is not required, and any scalar value is accepted.
     */
    public $anything_goes;

    
    /**
     * Class constants with a prefix which is an uppercase of a property name
     * is validated and allows only values among those constants.
     */
    const CACHE_OFF = 0;
    const CACHE_AUTO = 1;
    const CACHE_ON = 2;

    /**
     * Must be set to one of the above constants
     */
    public int $cache;
    


    /**
     * An strictly typed option which is required since it does not have a default.
     */
    public string $base_url;

    /**
     * Union types are OK if you are targetting PHP 8
     */
    public int|bool $either_int_or_boolean;

    /**
     * Allow nested options by declaring those as well:
     */
    public HttpClientCookieOptions $cookie_options;

    /**
     * Declare this function if you wish to automatically set some options or
     * perform custom validation
     */
    protected function finalize() {
        assert(str_starts_with($this->base_url, 'http', 'URL must start with "http"');
    }
}

设置选项

选项在构造函数中设置。

<?php
$httpClient = new HttpClient(new HttpClientOptions([
    'anything_goes_not_required' => "Hello World",
    'base_url' => 123,                                  // triggers a validation error (not string)
    'either_int_or_boolean' => false,
    'cookie_options' => [
        // configuration options for a HttpClientCookieOptions
    ],
]));

Reading Options
---------------

Options can be accessed directly as properties.

<?php echo $options->cookie_options->cookie_jar_file;

Alternatives for options that are private:

<?php // 获取一个stdClass选项映射 $accessibleOptions = $options->asObject(); // 你将收到一个新的stdClass，其中包含所有选项

// 通过ArrayAccess接口读取 $theOption = $options['a_private_option']; ?>

修改选项

如果您想从另一个实例“继承”，可以创建一个新的选项对象实例。

<?php
$heir = new HttpClientOptions(["some_overridden_options" => 123] + $ancestor);

使用选项类

提供示例以示完整。

<?php
class HttpClient {

    protected HttpClientOptions $options;

    public function __construct(HttpClientOptions $options) {
        $this->options = $options;
    }

}