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

^*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

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