Add param defaults to reflection (of php-ast's functions) in php 8 (nikic#152)

Add param defaults to reflection in php 8

Support generated arginfo macros in older php versions

Throw in `new ast\Node` for invalid parameter types in php 7. (already the default for php 8)

Author: TysonAndre

ast.c

@@ -14,6 +14,29 @@
 #include "zend_exceptions.h"
 #include "zend_smart_str.h"
 
+#ifndef ZEND_ARG_INFO_WITH_DEFAULT_VALUE
+#define ZEND_ARG_INFO_WITH_DEFAULT_VALUE(pass_by_ref, name, default_value) \
+	ZEND_ARG_INFO(pass_by_ref, name)
+#endif
+#if PHP_VERSION_ID < 70200
+#undef ZEND_BEGIN_ARG_WITH_RETURN_TYPE_INFO_EX
+#define ZEND_BEGIN_ARG_WITH_RETURN_TYPE_INFO_EX(name, return_reference, required_num_args, class_name, allow_null) \
+	static const zend_internal_arg_info name[] = { \
+	   	{ (const char*)(zend_uintptr_t)(required_num_args), ( #class_name ), 0, return_reference, allow_null, 0 },
+#endif
+
+#ifndef ZEND_BEGIN_ARG_WITH_RETURN_OBJ_INFO_EX
+#define ZEND_BEGIN_ARG_WITH_RETURN_OBJ_INFO_EX(name, return_reference, required_num_args, class_name, allow_null) \
+	ZEND_BEGIN_ARG_WITH_RETURN_TYPE_INFO_EX(name, return_reference, required_num_args, class_name, allow_null)
+#endif
+
+#ifndef ZEND_ARG_TYPE_INFO_WITH_DEFAULT_VALUE
+#define ZEND_ARG_TYPE_INFO_WITH_DEFAULT_VALUE(pass_by_ref, name, type_hint, allow_null, default_value) \
+	ZEND_ARG_TYPE_INFO(pass_by_ref, name, type_hint, allow_null)
+#endif
+
+#include "ast_arginfo.h"
+
 #define ast_throw_exception(exception_ce, ...) \
 	zend_throw_exception_ex(exception_ce, 0, __VA_ARGS__)
 
@@ -1242,7 +1265,7 @@ PHP_METHOD(ast_Node, __construct) {
 	zend_long lineno;
 	zend_bool kindNull, flagsNull, linenoNull;
 
-	ZEND_PARSE_PARAMETERS_START(0, 4)
+	ZEND_PARSE_PARAMETERS_START_EX(ZEND_PARSE_PARAMS_THROW, 0, 4)
 		Z_PARAM_OPTIONAL
 		Z_PARAM_LONG_EX(kind, kindNull, 1, 0)
 		Z_PARAM_LONG_EX(flags, flagsNull, 1, 0)
@@ -1278,39 +1301,6 @@ PHP_METHOD(ast_Node, __construct) {
 	}
 }
 
-ZEND_BEGIN_ARG_INFO_EX(arginfo_parse_file, 0, 0, 2)
-	ZEND_ARG_INFO(0, filename)
-	ZEND_ARG_INFO(0, version)
-ZEND_END_ARG_INFO()
-
-ZEND_BEGIN_ARG_INFO_EX(arginfo_parse_code, 0, 0, 2)
-	ZEND_ARG_INFO(0, code)
-	ZEND_ARG_INFO(0, version)
-	ZEND_ARG_INFO(0, filename)
-ZEND_END_ARG_INFO()
-
-ZEND_BEGIN_ARG_INFO_EX(arginfo_get_kind_name, 0, 0, 1)
-	ZEND_ARG_INFO(0, kind)
-ZEND_END_ARG_INFO()
-
-ZEND_BEGIN_ARG_INFO_EX(arginfo_kind_uses_flags, 0, 0, 1)
-	ZEND_ARG_INFO(0, kind)
-ZEND_END_ARG_INFO()
-
-ZEND_BEGIN_ARG_INFO_EX(arginfo_get_metadata, 0, 0, 0)
-ZEND_END_ARG_INFO()
-
-ZEND_BEGIN_ARG_INFO_EX(arginfo_get_supported_versions, 0, 0, 0)
-	ZEND_ARG_INFO(0, exclude_deprecated)
-ZEND_END_ARG_INFO()
-
-ZEND_BEGIN_ARG_INFO_EX(arginfo_node_construct, 0, 0, 0)
-	ZEND_ARG_INFO(0, kind)
-	ZEND_ARG_INFO(0, flags)
-	ZEND_ARG_ARRAY_INFO(0, children, 1)
-	ZEND_ARG_INFO(0, lineno)
-ZEND_END_ARG_INFO()
-
 const zend_function_entry ast_functions[] = {
 	ZEND_NS_FE("ast", parse_file, arginfo_parse_file)
 	ZEND_NS_FE("ast", parse_code, arginfo_parse_code)
@@ -1322,7 +1312,7 @@ const zend_function_entry ast_functions[] = {
 };
 
 const zend_function_entry ast_node_functions[] = {
-	PHP_ME(ast_Node, __construct, arginfo_node_construct, ZEND_ACC_PUBLIC)
+	PHP_ME(ast_Node, __construct, arginfo_class_Node___construct, ZEND_ACC_PUBLIC)
 	PHP_FE_END
 };
 

ast.stub.php

@@ -0,0 +1,74 @@
+<?php
+
+/**
+ * USE ast_stub.php INSTEAD IF YOU ARE LOOKING FOR DOCUMENTATION OR STUBS FOR YOUR IDE.
+ *
+ * This is a stub file meant only for use with https://github.com/php/php-src/blob/master/build/gen_stub.php
+ * to generate Reflection information (ReflectionParameter, ReflectionFunction, ReflectionMethod, etc.)
+ */
+
+// XXX: build/gen_stub.php does not support namespace nodes at the time of writing.
+// The namespace is thus deliberately omitted so that ast_arginfo.h can be successfully built.
+// namespace ast;
+
+
+/**
+ * Parses code file and returns AST root node.
+ *
+ * @param string $filename Code file to parse
+ * @param int    $version  AST version
+ * @return Node Root node of AST
+ *
+ * @see https://github.com/nikic/php-ast for version information
+ */
+function parse_code(string $code, int $version, string $filename = 'string code'): \ast\Node {}
+
+function parse_file(string $filename, int $version): \ast\Node {}
+
+/**
+ * @param int $kind AST_* constant value defining the kind of an AST node
+ * @return string String representation of AST kind value
+ */
+function get_kind_name(int $kind): string {}
+
+/**
+ * @param int $kind AST_* constant value defining the kind of an AST node
+ * @return bool Returns true if AST kind uses flags
+ */
+function kind_uses_flags(int $kind): bool {}
+
+/**
+ * Provides metadata for the AST kinds.
+ *
+ * The returned array is a map from AST kind to a Metadata object.
+ *
+ * @return Metadata[] Metadata about AST kinds
+ */
+function get_metadata(): array {}
+
+/**
+ * Returns currently supported AST versions.
+ *
+ * @param bool $exclude_deprecated Whether to exclude deprecated versions
+ * @return int[] Array of supported AST versions
+ */
+function get_supported_versions(bool $exclude_deprecated = false): array {}
+
+/**
+ * This class describes a single node in a PHP AST.
+ */
+class Node
+{
+    /**
+     * A constructor which accepts any types for the properties.
+     * For backwards compatibility reasons, all values are optional and can be any type, and properties default to null
+     *
+     * @param int|null $kind
+     * @param int|null $flags
+     * @param array|null $children
+     * @param int|null $lineno
+     */
+    public function __construct(?int $kind = null, ?int $flags = null, ?array $children = null, ?int $lineno = null) {
+    }
+}
+

ast_arginfo.h

@@ -0,0 +1,35 @@
+/* This is a generated file, edit the .stub.php file instead.
+ * Stub hash: 6c168364b94be45e237e47fd5709046457c6cb6b */
+
+ZEND_BEGIN_ARG_WITH_RETURN_OBJ_INFO_EX(arginfo_parse_code, 0, 2, ast\\Node, 0)
+	ZEND_ARG_TYPE_INFO(0, code, IS_STRING, 0)
+	ZEND_ARG_TYPE_INFO(0, version, IS_LONG, 0)
+	ZEND_ARG_TYPE_INFO_WITH_DEFAULT_VALUE(0, filename, IS_STRING, 0, "\'string code\'")
+ZEND_END_ARG_INFO()
+
+ZEND_BEGIN_ARG_WITH_RETURN_OBJ_INFO_EX(arginfo_parse_file, 0, 2, ast\\Node, 0)
+	ZEND_ARG_TYPE_INFO(0, filename, IS_STRING, 0)
+	ZEND_ARG_TYPE_INFO(0, version, IS_LONG, 0)
+ZEND_END_ARG_INFO()
+
+ZEND_BEGIN_ARG_WITH_RETURN_TYPE_INFO_EX(arginfo_get_kind_name, 0, 1, IS_STRING, 0)
+	ZEND_ARG_TYPE_INFO(0, kind, IS_LONG, 0)
+ZEND_END_ARG_INFO()
+
+ZEND_BEGIN_ARG_WITH_RETURN_TYPE_INFO_EX(arginfo_kind_uses_flags, 0, 1, _IS_BOOL, 0)
+	ZEND_ARG_TYPE_INFO(0, kind, IS_LONG, 0)
+ZEND_END_ARG_INFO()
+
+ZEND_BEGIN_ARG_WITH_RETURN_TYPE_INFO_EX(arginfo_get_metadata, 0, 0, IS_ARRAY, 0)
+ZEND_END_ARG_INFO()
+
+ZEND_BEGIN_ARG_WITH_RETURN_TYPE_INFO_EX(arginfo_get_supported_versions, 0, 0, IS_ARRAY, 0)
+	ZEND_ARG_TYPE_INFO_WITH_DEFAULT_VALUE(0, exclude_deprecated, _IS_BOOL, 0, "false")
+ZEND_END_ARG_INFO()
+
+ZEND_BEGIN_ARG_INFO_EX(arginfo_class_Node___construct, 0, 0, 0)
+	ZEND_ARG_TYPE_INFO_WITH_DEFAULT_VALUE(0, kind, IS_LONG, 1, "null")
+	ZEND_ARG_TYPE_INFO_WITH_DEFAULT_VALUE(0, flags, IS_LONG, 1, "null")
+	ZEND_ARG_TYPE_INFO_WITH_DEFAULT_VALUE(0, children, IS_ARRAY, 1, "null")
+	ZEND_ARG_TYPE_INFO_WITH_DEFAULT_VALUE(0, lineno, IS_LONG, 1, "null")
+ZEND_END_ARG_INFO()

ast_stub.php

@@ -217,7 +217,7 @@
  *
  * @see https://github.com/nikic/php-ast for version information
  */
-function parse_file($filename, $version)
+function parse_file(string $filename, int $version)
 {
 }
 
@@ -231,23 +231,23 @@ function parse_file($filename, $version)
  *
  * @see https://github.com/nikic/php-ast for version information
  */
-function parse_code($code, $version, $filename = "string code")
+function parse_code(string $code, int $version, string $filename = "string code")
 {
 }
 
 /**
  * @param int $kind AST_* constant value defining the kind of an AST node
  * @return string String representation of AST kind value
  */
-function get_kind_name($kind)
+function get_kind_name(int $kind): string
 {
 }
 
 /**
  * @param int $kind AST_* constant value defining the kind of an AST node
  * @return bool Returns true if AST kind uses flags
  */
-function kind_uses_flags($kind)
+function kind_uses_flags(int $kind): bool
 {
 }
 
@@ -258,7 +258,7 @@ function kind_uses_flags($kind)
  *
  * @return Metadata[] Metadata about AST kinds
  */
-function get_metadata()
+function get_metadata(): array
 {
 }
 
@@ -268,7 +268,7 @@ function get_metadata()
  * @param bool $exclude_deprecated Whether to exclude deprecated versions
  * @return int[] Array of supported AST versions
  */
-function get_supported_versions($exclude_deprecated = false)
+function get_supported_versions($exclude_deprecated = false): array
 {
 }
 

package.xml

@@ -31,6 +31,10 @@
  <notes>
 - Support attributes syntax change (`#[...]`) in php 8.0.0RC1.
 - Change the current AST version from 70 to 80. AST version 80 is no longer experimental.
+- Add `ReflectionParameter` defaults for `ast\parse_code` and `ast\get_supported_versions` in php 8.
+- Add parameter types and return types to reflection for various global functions.
+  php-ast was already throwing a `TypeError` when invalid parameter types were received.
+- Always throw instead of warning when invalid parameters are passed to the ast\Node constructor.
  </notes>
  <contents>
   <dir name="/">
@@ -39,6 +43,7 @@
     <file name="util.php" role="doc" />
     <file name="ast.c" role="src" />
     <file name="ast_data.c" role="src" />
+    <file name="ast_arginfo.h" role="src" />
     <file name="ast_str_defs.h" role="src" />
     <file name="ast_stub.php" role="doc" />
     <file name="LICENSE" role="doc" />
@@ -85,6 +90,7 @@
       <file name="named_children.phpt" role="test" />
       <file name="name_node.phpt" role="test" />
       <file name="nested_stmt_lists.phpt" role="test" />
+      <file name="node_constructor_throw.phpt" role="test" />
       <file name="nop_statements.phpt" role="test" />
       <file name="nullable_types.phpt" role="test" />
       <file name="object_type.phpt" role="test" />

tests/node_constructor_throw.phpt

@@ -0,0 +1,14 @@
+--TEST--
+new ast\Node() throwing
+--SKIPIF--
+<?php if (!extension_loaded("ast")) print "skip"; ?>
+--FILE--
+<?php
+
+try {
+    new ast\Node('invalid');
+} catch (TypeError $e) {
+    echo "Caught {$e->getMessage()}\n";
+}
+--EXPECTF--
+Caught %s, string given