English / 日本語

Web IDL

Provides the utility class for casting a given value in accordance with WebIDL (Web IDL) type to help with PHP type declarations.

Description

This library makes type declarations help API and the exceptions defined by Web IDL available in PHP. This library is for Web standards API implementors and is not intended to be used directly by a PHP project.

If you want your users to install this library simultaneously with your library, append "esperecyan/webidl": "^2.1.0" to require property in composer.json of your library, such as the following.

{
	"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/"
		}
	},
}

For details of Composer, see Composer documentation.

Example

<?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');

The above example will throw the chained exceptions:

• InvalidArgumentException: Expected a single operation callback interface (a object, array or callable), got 'invalid argument' in esperecyan/webidl/src/lib/ObjectType.php on line 66
• InvalidArgumentException: Expected EventListener? (EventListener or null) in esperecyan/webidl/src/lib/NullableType.php on line 29
• InvalidArgumentException: Argument 2 passed to EventTarget::addEventListener() is not of the expected type in esperecyan/webidl/src/TypeHinter.php on line 45

For actual examples, see the source code of esperecyan/url.

Type declarations help API

All of the methods are static, and must be called from a class method.

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

Converts a given value in accordance with a given IDL type. If the value is not castable, it will throw a DomainException or InvalidArgumentException including a message with method name etc.

string $type

Pass the IDL type (for example, USVString).

• If it is an interface type (excluding callback interface), pass the fully qualified class name or interface name (for example, esperecyan\webidl\TypeError). Additionally, the leading backslash is unnecessary.
• If it is an integer type, can use [EnforceRange] extended attribute or [Clamp] extended attribute (for example, [Clamp] octet).
• Supports most types also including such as union types (for example, (Node or DOMString)), but there are some parts are different. See The correspondence table of the types.

mixed $value

Pass the value being converted.

string $argNum = 0

Pass the argument offset that received the value being converted. Arguments are counted starting from zero. This argument value is used by a exception message. If the caller method is __set(), this argument is ignored.

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

Pass the associative array with the identifiers of callback interface types, enumeration types, callback function types or dictionary types (the strings passed in $type) as key. The corresponding values have the following structure.

[
    '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()

Throws an exception with a message that represents a read-only property. Must call from __set() method.

esperecyan\webidl\TypeHinter::triggerVisibilityErrorOrDefineProperty()

If a user tries setting to a private or protected property, it will trigger a fatal error. If a user tries setting to a non-existing property, it will create a new public property. Must call from __set() method.

esperecyan\webidl\TypeHinter::triggerVisibilityErrorOrUndefinedNotice()

If a user tries setting to a private or protected property, it will trigger a fatal error. If a user tries getting to a non-existing property, it will trigger a notice. Must call from __get() method.

The correspondence table of the types

Web IDL	PHP	Additional notes
boolean	Booleans
byte octet short unsigned short long	Integers
unsigned long	Integers|Floating point numbers	On 32bit PHP or PHP 5.6 or earlier for Windows, a number less than -2147483648 or greater than 2147483647 is the floating point number.
long long	Integers|Floating point numbers	-9223372036854775808 to 9223372036854775807. However, on 32bit PHP or PHP 5.6 or earlier for Windows, -9007199254740991 to 9007199254740991, and the number less than -2147483648 or greater than 2147483647 is the floating point number.
unsigned long long	Integers|Floating point numbers	0 to 9223372036854775807. However, on 32bit PHP or PHP 5.6 or earlier for Windows, 0 to 9007199254740991, and the number greater than 2147483647 is the floating point number.
float [*1] unrestricted float [*1] double unrestricted double	Floating point numbers	float and unrestricted float is aliases of double and unrestricted double.
DOMString USVString	Strings	A valid UTF-8 string.
ByteString	Strings
object	Objects
Interface types	Objects|Callables	If an interface is single operation callback interface, there are cases where the PHP type is Callable.
Dictionary types	Arrays	An array conforming the structure passed in $pseudoType.
Enumeration types	Strings	A element of the array passed in $pseudoType, or a constant value of the class passed in.
Callback function types	Callables
Sequences Frozen arrays	Arrays	New array.
record<K, V>	esperecyan\webidl\Record
Promise types		Not supported. Instead, pass a fully qualified class name or interface name (for example, React\Promise\PromiseInterface).
Union types	mixed	A return value of UnionType::toUnion().
Error	esperecyan\webidl\Error|DOMException
DOMException	DOMException
Buffer source types		Not supported. Instead, pass a fully qualified class name or interface name.

^*1 double should be used rather than float. Deprecated.
[*1]: #*1 "double should be used rather than float. Deprecated."

The correspondence table of the exceptions

Web IDL	PHP
Error [*2]	esperecyan\webidl\Error interface (If you need to construct an exception having this error name, write new esperecyan\webidl\ErrorClass('error message'))
EvalError	esperecyan\webidl\EvalError class
RangeError	esperecyan\webidl\RangeError class
ReferenceError	esperecyan\webidl\ReferenceError class
TypeError	esperecyan\webidl\TypeError class
URIError	esperecyan\webidl\URIError class
DOMException	DOMException class

^*2 “Error” simple exception type is obsoleted in W3C Editor’s draft (* this is not Error IDL type). Deprecated. [*2]: #2 "“Error” simple exception type is obsoleted in W3C Editor’s draft ( this is not Error IDL type). Deprecated."

Requirement

• PHP 5.4 or later (PHP 5.4 – 7.1 are deprecated)
  • SPL Types PECL library is not supported

Contribution

1. Fork it ( https://github.com/esperecyan/webidl )
2. Create your feature branch git checkout -b my-new-feature
3. Commit your changes git commit -am 'Add some feature'
4. Push to the branch git push origin my-new-feature
5. Create new Pull Request

Or

Create new Issue

If you find any mistakes of English in the README or Doc comments or any flaws in tests, please report by such as above means. I also welcome translations of README too.

Acknowledgement

I use Web IDL (Second Edition) — Japanese translation as reference in creating this library.

HADAA helped me translate README to English.

Semantic Versioning

This library uses Semantic Versioning. The classes (including exceptions), interfaces, and methods not indicated “Internal” in the documentation of the library are the public API.

Licence

This library is licensed under the Mozilla Public License Version 2.0 (MPL-2.0).