From 46e0f25dcdb6d70dcbb432e8528665ea0fd651ca Mon Sep 17 00:00:00 2001 From: George Peter Banyard Date: Thu, 12 Nov 2020 19:45:06 +0000 Subject: [PATCH] Actually add type declaration page... git-svn-id: https://svn.php.net/repository/phpdoc/en/trunk@351366 c90b9560-bf6c-de11-be94-00142212c4b1 --- language/types/declarations.xml | 812 ++++++++++++++++++++++++++++++++ 1 file changed, 812 insertions(+) create mode 100755 language/types/declarations.xml diff --git a/language/types/declarations.xml b/language/types/declarations.xml new file mode 100755 index 0000000000..c99dc02b08 --- /dev/null +++ b/language/types/declarations.xml @@ -0,0 +1,812 @@ + + + + Type declarations + + + Type declarations can be added to function arguments, return values, + and, as of PHP 7.4.0, class properties. They ensure that the value + is of the specified type at call time, otherwise a + TypeError is thrown. + + + + + + + When overriding a parent method, the child's method must match any return + type declaration on the parent. If the parent doesn't define a return + type, then the child method may do so. + + + + + Single types + + + + + &Type; + &Description; + &Version; + + + + + Class/interface name + + The value must be an &instanceof; the given class or interface. + + + + + self + + The value must be an &instanceof; the same class as the one the + method is defined on. + Can only be used in classes. + + + + + array + + The value must be an array. + + + + + callable + + The value must be a valid callable. + Cannot be used as a class property type declaration. + + + + + bool + + The value must be a boolean value. + + + + + float + + The value must be a floating point number. + + + + + int + + The value must be an integer. + + + + + string + + The value must be a string. + + + + + iterable + + The value must be either an array or an &instanceof; Traversable. + + PHP 7.1.0 + + + object + + The value must be an object. + + PHP 7.2.0 + + + mixed + + The value can be any value. + + PHP 8.0.0 + + + + + + + + Aliases for the above scalar types are not supported. + Instead, they are treated as class or interface names. + For example, using boolean as a type declaration + it will require the value to be an &instanceof; the class or + interface boolean, rather than of type + bool: + + + + + +]]> + + &example.outputs.8; + + + + + + + + + &reftitle.examples; + + Basic class type declaration + + +]]> + + &example.outputs.8; + + + + + + + Basic interface type declaration + + +]]> + + &example.outputs.8; + + + + + + + Basic return type declaration + + +]]> + + &example.outputs; + + + + + + + Returning an object + + +]]> + + &example.outputs; + + + + + + + + + Nullable type + + + As of PHP 7.1.0, type declarations can be marked nullable by prefixing the + type name with a question mark (?). + This signifies that the value can be of the specified type or &null;. + + + + + Nullable argument type declaration + + +]]> + + &example.outputs; + + + + + + + Nullable return type declaration + + +]]> + + + + + + + Prior to PHP 7.1.0, it was possible to achieve nullable arguments by making + null the default value. + This is not recommended as this breaks during inheritance. + + + Old way to make arguments nullable + + +]]> + + &example.outputs; + + + + + + + + + Union types + + A union type declaration accepts values of multiple different types, + rather than a single one. + Union types are specified using the syntax T1|T2|.... + Union types are available as of PHP 8.0.0. + + + + Nullable union types + + The null type is supported as part of unions, + such that T1|T2|null can be used to create a nullable union. + The existing ?T notation is considered a shorthand + for the common case of T|null. + + + + + null cannot be used as a standalone type. + + + + + + false pseudo-type + + The false literal type is supported as part of unions, + and is included as for historical reasons many internal functions return + false instead of null for failures. + A classic example of such a function is strpos. + + + + + false cannot be used as a standalone type (including + nullable standalone type). + As such, all of false, false|null + and ?false are not permitted. + + + + + The true literal type does not + exist. + + + + + + Duplicate and redundant types + + To catch simple bugs in union type declarations, redundant types that + can be detected without performing class loading will result in a + compile-time error. This includes: + + + + + Each name-resolved type may only occur once. Types such as + int|string|INT result in an error. + + + + + If bool is used, false cannot be used additionally. + + + + + If object is used, class types cannot be used additionally. + + + + + If iterable is used, array + and Traversable cannot be used additionally. + + + + + + + + This does not guarantee that the type is “minimal”, because doing so would + require loading all used class types. + + + + + For example, if A and B are class + aliases, then A|B remains a legal union type, even + though it could be reduced to either A or + B. + Similarly, if class B extends A {}, then A|B + is also a legal union type, even though it could be reduced to just + A. + + + + +]]> + + + + + + + + + Return only types + + + void + + void is a return type indicating the function does not + return a value. + Therefore it cannot be part of a union type declaration. + Available as of PHP 7.1.0. + + + + + static + + The value must be an &instanceof; the same class as the one the + method is called in. + Available as of PHP 8.0.0. + + + + + + Strict typing + + + By default, PHP will coerce values of the wrong type into the expected + scalar type declaration if possible. For example, a function that is given + an int for a parameter that expects a string + will get a variable of type string. + + + + It is possible to enable strict mode on a per-file basis. In strict + mode, only a value corresponding exactly to the type declaration will be + accepted, otherwise a TypeError will be thrown. + The only exception to this rule is that an int value will + pass a float type declaration. + + + + + Function calls from within internal functions will not be affected by + the strict_types declaration. + + + + + To enable strict mode, the &declare; statement is used with the + strict_types declaration: + + + + + Strict typing applies to function calls made from + within the file with strict typing enabled, not to + the functions declared within that file. If a file without strict + typing enabled makes a call to a function that was defined in a file + with strict typing, the caller's preference (coercive typing) will be + respected, and the value will be coerced. + + + + + + Strict typing is only defined for scalar type declarations. + + + + + Strict typing for arguments values + + +]]> + + &example.outputs.8; + + + + + + + Coercive typing for argument values + + +]]> + + &example.outputs; + + + + + + + Strict typing for return values + + +]]> + + &example.outputs; + + + + + + + + Coercive typing with union types + + When strict_types is not enabled, scalar type declarations + are subject to limited implicit type coercions. + If the exact type of the value is not part of the union, then the target type + is chosen in the following order of preference: + + + + + int + + + + + float + + + + + string + + + + + bool + + + + + If the type both exists in the union, and the value can be coerced to the + type under PHPs existing type checking semantics, then the type is chosen. + Otherwise the next type is tried. + + + + + As an exception, if the value is a string and both int and float are part + of the union, the preferred type is determined by the existing + “numeric string” semantics. + For example, for "42" int is chosen, + while for "42.0" float is chosen. + + + + + + Types that are not part of the above preference list are not eligible + targets for implicit coercion. In particular no implicit coercions to + the null and false types occur. + + + + + Example of types being coerced into a type part of the union + + 42 // exact type +"42" --> "42" // exact type +new ObjectWithToString --> "Result of __toString()" + // object never compatible with int, fall back to string +42.0 --> 42 // float compatible with int +42.1 --> 42 // float compatible with int +1e100 --> "1.0E+100" // float too large for int type, fall back to string +INF --> "INF" // float too large for int type, fall back to string +true --> 1 // bool compatible with int +[] --> TypeError // array not compatible with int or string + +// int|float|bool +"45" --> 45 // int numeric string +"45.0" --> 45.0 // float numeric string + +"45X" --> true // not numeric string, fall back to bool +"" --> false // not numeric string, fall back to bool +"X" --> true // not numeric string, fall back to bool +[] --> TypeError // array not compatible with int, float or bool +?> +]]> + + + + + + + Misc + + Typed pass-by-reference Parameters + + Declared types of reference parameters are checked on function entry, but + not when the function returns, so after the function had returned, the + argument's type may have changed. + + + +]]> + + &example.outputs.8; + + + + + + + Catching <classname>TypeError</classname> + +getMessage(); +} +?> +]]> + + &example.outputs.8; + + + + + + + + +