README

英文 / 日语

Web IDL

提供按照WebIDL (Web IDL)类型进行值转换的实用工具类，以帮助进行PHP类型声明。

描述

此库使Web IDL定义的类型声明帮助API和异常在PHP中可用。此库是为Web标准API实现者设计的，不打算直接用于PHP项目。

如果您希望用户同时安装此库和您的库，请将"esperecyan/webidl": "^2.1.0"添加到您的库的composer.json文件中的require属性中，如下所示。

{
	"name": "esperecyan/url",
	"description": "Makes the algorithms and APIs defined by URL Standard available on PHP.",
	"require": {
		"php": ">=7.4",
		"esperecyan/webidl": "^2.1.0"
	},
	"autoload": {
		"psr-4": {
			"esperecyan\\url\\": "src/"
		}
	},
}

有关Composer的详细信息，请参阅Composer文档。

示例

<?php
require_once 'vendor/autoload.php';

use esperecyan\webidl\TypeHinter;
use esperecyan\webidl\DOMException;

class EventTarget
{
    private $eventListeners = [];
    
    public function addEventListener($type, $callback, $capture = false)
    {
        $listener = [
            'type' => TypeHinter::to('DOMString', $type, 0),
            'callback' => TypeHinter::to('EventListener?', $callback, 1, [
                'EventListener' => 'single operation callback interface',
            ]),
            'capture' => TypeHinter::to('boolean', $type, 2),
        ];
        if (!is_null($listener->callback) && !in_array($listener, $this->eventListeners, true)) {
            $this->eventListeners[] = $listener;
        }
    }
}

(new EventTarget())->addEventListener('load', 'invalid argument');

上述示例将抛出链式异常

• InvalidArgumentException: 期望一个操作回调接口（一个对象、数组或可调用对象），但在esperecyan/webidl/src/lib/ObjectType.php的第66行得到了'无效参数'
• InvalidArgumentException: 期望EventListener?（EventListener或null）在esperecyan/webidl/src/lib/NullableType.php的第29行
• InvalidArgumentException: Argument 2 passed to EventTarget::addEventListener() is not of the expected type in esperecyan/webidl/src/TypeHinter.php在第45行

有关实际示例，请参阅esperecyan/url的源代码。

类型声明帮助API

所有方法都是静态的，必须从类方法中调用。

esperecyan\webidl\TypeHinter::to($type, $value, $argNum, $pseudoTypes)

根据给定的IDL类型转换给定的值。如果值不可转换，它将抛出包括方法名等消息的DomainException或InvalidArgumentException。

string $type

传递IDL类型（例如，USVString）。

• 如果是接口类型（不包括回调接口），传递完全限定的类名或接口名（例如，esperecyan\webidl\TypeError）。此外，不需要开头的反斜杠。
• 如果是整数类型，可以使用[EnforceRange]扩展属性或[Clamp]扩展属性（例如，[Clamp] octet）。
• 支持大多数类型，包括联合类型（例如，(Node or DOMString)），但有一些部分不同。请参阅类型的对应表。

mixed $value

传递要转换的值。

string $argNum = 0

传递要转换的值的偏移量参数。 参数从零开始计数。 此参数值用于异常消息。如果调用方法是 __set()，则忽略此参数。

(string|string[]|array)[] $pseudoType = []

传递包含回调接口类型、枚举类型、回调函数类型或字典类型标识符的关联数组（在 $type 中传递的字符串）作为键。相应的值具有以下结构。

[
    'A callback interface type name' => 'callback interface',
    'A single operation callback interface type name' => 'single operation callback interface',
    'A callback function type name' => 'callback function',
    'A enumeration type name' => ['An array', 'of strings'],
    'dictionary 型名' => [
        'A member key A' => [
            'type' => 'A type name',
            'default' => 'A default value',
        ],
        'A member key B' => [
            'type' => 'A type name',
            'required' => true,
        ],
    ],
]

esperecyan\webidl\TypeHinter::throwReadonlyException()

抛出一个表示只读属性的异常消息。必须从 __set() 方法调用。

esperecyan\webidl\TypeHinter::triggerVisibilityErrorOrDefineProperty()

如果用户尝试设置私有或受保护的属性，将触发致命错误。如果用户尝试设置不存在的属性，将创建一个新的公共属性。必须从 __set() 方法调用。

esperecyan\webidl\TypeHinter::triggerVisibilityErrorOrUndefinedNotice()

如果用户尝试设置私有或受保护的属性，将触发致命错误。如果用户尝试获取不存在的属性，将触发警告。必须从 __get() 方法调用。

类型 对应表

^*1 应使用 double 而不是 float。已弃用。
[*1]: #*1 "double 应使用 float。已弃用."

异常 对应表

^*2 “Error”简单异常类型在 W3C 编辑草稿中已弃用 (* 这不是 Error IDL 类型)。已弃用。 [*2]: #2 "“Error”简单异常类型在 W3C 编辑草稿中已弃用 ( 这不是 Error IDL 类型)。已弃用。

要求

• PHP 5.4 或更高版本 (PHP 5.4 – 7.1 已弃用)
  • SPL 类型 PECL 库不支持

贡献

1. 分叉它 ( https://github.com/esperecyan/webidl )
2. 创建你的功能分支 git checkout -b my-new-feature
3. 提交你的更改 git commit -am '添加一些功能'
4. 推送到分支 git push origin my-new-feature
5. 创建新的 Pull Request

或

创建新的 Issue

如果你在 README 或 Doc 注释中找到任何英语错误，或测试中的任何缺陷，请通过上述方式报告。我也欢迎对 README 进行翻译。

致谢

我在创建此库时将 Web IDL (第二版) — 日文翻译 作为参考。

HADAA 帮助我将 README 翻译成英文。

语义版本控制

此库使用 语义版本控制。未在 库的文档 中标记为“内部”的类（包括异常）、接口和方法是公共 API。

许可证

此库受 Mozilla 公共许可证版本 2.0 (MPL-2.0) 许可。