esperecyan/webidl

Provides the utility class for casting a given value in accordance with WebIDL (Web IDL) type to help with PHP type declarations. / WebIDL (Web IDL) の型に沿うように、与えられた値をキャストするユーティリティクラスを提供し、PHP の型宣言を補助します。

Maintainers

Details

github.com/esperecyan/webidl

Homepage

Source

Issues

Fund package maintenance!
esperecyan

Installs: 6 540

Dependents: 2

Suggesters: 0

Security: 0

Stars: 0

Watchers: 3

Forks: 1

Open Issues: 0

v2.3.0 2023-02-15 04:19 UTC

Requires

Requires (Dev)

MPL-2.0 d92157f19c2e60f9fe886bf986f6516824a4a0cb

W3CEvalErrorRangeErrorReferenceErrorTypeErrorURIError

This package is auto-updated.

Last update: 2024-04-15 06:50:16 UTC

README

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).