Allow extending the Node class

[matt-allan]

This PR adds the ability to extend the Node class and parse code into your own classes. The idea is to offer a similar API to the tokenizer extension:

<?php

class MyNode extends \ast\Node
{
    public bool $myFlag = false;
}

$ast = MyNode::parseCode('<?php echo "hello, world!";', 90);

$ast->myFlag = true;

var_dump($ast);

Example output

object(MyNode)#1 (5) {
  ["kind"]=>
  int(132)
  ["flags"]=>
  int(0)
  ["lineno"]=>
  int(1)
  ["children"]=>
  array(1) {
    [0]=>
    object(MyNode)#2 (5) {
      ["kind"]=>
      int(283)
      ["flags"]=>
      int(0)
      ["lineno"]=>
      int(1)
      ["children"]=>
      array(1) {
        ["expr"]=>
        string(13) "hello, world!"
      }
      ["myFlag"]=>
      bool(false)
    }
  }
  ["myFlag"]=>
  bool(true)
}

This solves a similar problem as #217 but in a different way. Compared to dynamic properties this approach lets you add methods, constants, interfaces, etc. as well and everything can be statically analyzed properly.

This is my first major contribution to a PHP extension so please let me know if anything looks off! I based the changes on the tokenizer extension's source code.

[matt-allan]

This is copied nearly verbatim from https://github.com/php/php-src/blob/59d257d1aea70e370da5937cc019ca5bdcbb8d46/ext/tokenizer/tokenizer.c#L103

[matt-allan]

I tried using legacy arginfo to prevent the static return type from causing an error but that appears to be breaking a 'constructor throws' test. Not sure what the correct solution is here. I will try building on PHP 7.0 locally so I can see what the issue is. Seems to work fine on PHP 7.4 for me locally.

[nikic]

@TysonAndre Thoughts on this functionality? The idea looks reasonable to me.

[TysonAndre]

I tried using legacy arginfo to prevent the static return type from causing an error but that appears to be breaking a 'constructor throws' test. Not sure what the correct solution is here. I will try building on PHP 7.0 locally so I can see what the issue is. Seems to work fine on PHP 7.4 for me locally.

The ast_legacy_arginfo.h is using ZEND_ARG_INFO with no types, so the result is a warning, and stops being the expected TypeError.

[TysonAndre]

1. it'd be more useful to test properties are correctly set, e.g. with the node dumper
2. could check that additional properties on the MyNode can be declared and that when read, they have the expected value. Same for properties inherited from traits (to have the unit test in case the property slot order ever changes and affects ast_node_set_prop_kind)

[TysonAndre]

I think one possible solution is to redefine IS_STATIC to ast\NODE in ast.c above the include - I forget if that would actually work

And continue using ast_arginfo.h instead of ast_legacy_arginfo.h

#ifndef IS_STATIC
// Workaround for `parse*` methods on Node with static return types in php < 8.0
#define IS_STATIC ast\\Node
#endif

[TysonAndre]

Thoughts on this functionality? The idea looks reasonable to me.

The change itself seems reasonable once tests pass as long as the impact on the overall performance of parsing is small.

---

Aside: also see #180 regarding build issues if 7.1 is an obstacle with this PR using the regular arg info
EDIT: If you rebase, builds will stop being tested with 7.1 and below

[matt-allan]

Thanks for the detailed review! I will follow up soon, I've been a bit busy starting a new job.