Modernize for PHP 8.x: attributes support, parser/CI/tooling updates, README fixes

.github/workflows/ci.yml

@@ -17,19 +17,19 @@ jobs:
       fail-fast: false
       matrix:
         php: [
-            7.4,
-            8.0,
             8.1,
-            8.2
+            8.2,
+            8.3,
+            8.4
         ]
         composer: [basic]
     timeout-minutes: 10
     steps:
       - name: Checkout code
-        uses: actions/checkout@3df4ab11eba7bda6032a0b82a6bb43b11571feac # v4
+        uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2
 
       - name: Setup PHP
-        uses: shivammathur/setup-php@2.25.5
+        uses: shivammathur/setup-php@accd6127cb78bee3e8082180cb391013d204ef9f # v2.37.0
         with:
           php-version: ${{ matrix.php }}
           coverage: xdebug
@@ -38,21 +38,17 @@ jobs:
 
       - name: Determine composer cache directory
         id: composer-cache
-        run: echo "::set-output name=directory::$(composer config cache-dir)"
+        run: echo "directory=$(composer config cache-dir)" >> "$GITHUB_OUTPUT"
 
       - name: Cache composer dependencies
-        uses: actions/cache@v3.3.1
+        uses: actions/cache@0057852bfaa89a56745cba8c7296529d2fc39830 # v4.3.0
         with:
           path: ${{ steps.composer-cache.outputs.directory }}
           key: ${{ matrix.php }}-composer-${{ hashFiles('**/composer.lock') }}
           restore-keys: ${{ matrix.php }}-composer-
 
       - name: Install dependencies
         run: |
-          if [[ "${{ matrix.php }}" == "8.0" ]]; then
-            composer require phpstan/phpstan --no-update
-          fi;
-
           if [[ "${{ matrix.composer }}" == "lowest" ]]; then
             composer update --prefer-dist --no-interaction --prefer-lowest --prefer-stable
           fi;
@@ -70,7 +66,7 @@ jobs:
 
       - name: Run phpstan
         continue-on-error: true
-        if: ${{ matrix.php == '7.4' }}
+        if: ${{ matrix.php == '8.3' }}
         run: |
           php vendor/bin/phpstan analyse
 
@@ -82,13 +78,13 @@ jobs:
           php-coveralls --coverage_clover=build/logs/clover.xml -v
 
       - name: Upload coverage results to Codecov
-        uses: codecov/codecov-action@v3
+        uses: codecov/codecov-action@e28ff129e5465c2c0dcc6f003fc735cb6ae0c673 # v4.5.0
         with:
           files: build/logs/clover.xml
 
       - name: Archive logs artifacts
         if: ${{ failure() }}
-        uses: actions/upload-artifact@v3
+        uses: actions/upload-artifact@b4b15b8c7c6ac21ea08fcf65892d2ee8f75cf882 # v4.4.3
         with:
           name: logs_composer-${{ matrix.composer }}_php-${{ matrix.php }}
           path: |

README.md

@@ -10,13 +10,15 @@
 
 You can simply scan a string, a file or a full directory and you can see a simple data structure from your php code.
 - Classes (**PHPClass**)
-- Properties (**PHPProperties**)
+- Properties (**PHPProperty**)
 - Constants (**PHPConst**)
 - Methods (**PHPMethod**)
 - Interfaces (**PHPInterface**)
 - Traits (**PHPTrait**)
+- Enums (**PHPEnum**)
 - Functions (**PHPFunction**)
 - Parameter (**PHPParameter**)
+- Attributes (**PHPAttribute**)
 
 This code is forked from [JetBrains/phpstorm-stubs](https://github.com/JetBrains/phpstorm-stubs/tree/master/tests) but you can't use the classes from "phpstorm-stubs" directly, 
 because they are in a test namespace and the autoloader is "autoload-dev", so here is a extended version.
@@ -27,6 +29,31 @@ We will use:
 - [phpDocumentor](https://github.com/phpDocumentor/)
 - [PHPStan/phpdoc-parser](https://github.com/phpstan/phpdoc-parser)
 
+### Requirements
+
+- PHP >= 8.1
+
+### Supported PHP Features
+
+| Feature | PHP Version | Supported |
+|---|---|---|
+| Attributes (class, method, property, parameter, constant) | 8.0+ | ✅ |
+| Constructor property promotion | 8.0+ | ✅ |
+| Union types | 8.0+ | ✅ |
+| Named arguments | 8.0+ | ✅ |
+| Match expressions | 8.0+ | ✅ |
+| Nullsafe operator | 8.0+ | ✅ |
+| Enums (unit, string-backed, int-backed) | 8.1+ | ✅ |
+| Readonly properties | 8.1+ | ✅ |
+| Intersection types | 8.1+ | ✅ |
+| `never` return type | 8.1+ | ✅ |
+| First-class callable syntax | 8.1+ | ✅ |
+| Readonly classes | 8.2+ | ✅ |
+| DNF types | 8.2+ | ✅ |
+| Standalone `true`, `false`, `null` types | 8.2+ | ✅ |
+| Trait constants | 8.2+ | ✅ |
+| Typed class constants | 8.3+ | ✅ |
+| `#[\Override]` attribute detection | 8.3+ | ✅ |
 
 ### Install via "composer require"
 
@@ -96,19 +123,42 @@ $phpClasses = $phpCode->getClasses();
 var_dump($phpClasses[Dummy::class]); // "PHPClass"-object
 ````
 
+Access enums:
+```php
+$phpCode = \voku\SimplePhpParser\Parsers\PhpCodeParser::getPhpFiles(__DIR__ . '/src');
+$phpEnums = $phpCode->getEnums();
+// PHPEnum objects with scalarType, cases, methods, constants, attributes
+````
+
+Access attributes:
+```php
+$phpCode = \voku\SimplePhpParser\Parsers\PhpCodeParser::getPhpFiles(__DIR__ . '/src');
+$phpClasses = $phpCode->getClasses();
+$class = $phpClasses['MyClass'];
+
+// Class-level attributes
+foreach ($class->attributes as $attr) {
+    echo $attr->name;          // e.g. "MyAttribute"
+    print_r($attr->arguments); // constructor arguments (array)
+}
+
+// Method/property/parameter attributes work the same way
+foreach ($class->methods['myMethod']->attributes as $attr) { ... }
+foreach ($class->properties['myProp']->attributes as $attr) { ... }
+foreach ($class->methods['myMethod']->parameters['param']->attributes as $attr) { ... }
+````
+
 
 ### Support
 
-For support and donations please visit [Github](https://github.com/voku/simple_html_dom/) | [Issues](https://github.com/voku/simple_html_dom/issues) | [PayPal](https://paypal.me/moelleken) | [Patreon](https://www.patreon.com/voku).
+For support and donations please visit [GitHub](https://github.com/voku/Simple-PHP-Code-Parser/) | [Issues](https://github.com/voku/Simple-PHP-Code-Parser/issues) | [PayPal](https://paypal.me/moelleken) | [Patreon](https://www.patreon.com/voku).
 
-For status updates and release announcements please visit [Releases](https://github.com/voku/simple_html_dom/releases) | [Twitter](https://twitter.com/suckup_de) | [Patreon](https://www.patreon.com/voku/posts).
+For status updates and release announcements please visit [Releases](https://github.com/voku/Simple-PHP-Code-Parser/releases) | [Patreon](https://www.patreon.com/voku/posts).
 
 For professional support please contact [me](https://about.me/voku).
 
 ### Thanks
 
-- Thanks to [GitHub](https://github.com) (Microsoft) for hosting the code and a good infrastructure including Issues-Managment, etc.
+- Thanks to [GitHub](https://github.com) (Microsoft) for hosting the code and a good infrastructure including Issues-Management, etc.
 - Thanks to [IntelliJ](https://www.jetbrains.com) as they make the best IDEs for PHP and they gave me an open source license for PhpStorm!
-- Thanks to [Travis CI](https://travis-ci.com/) for being the most awesome, easiest continous integration tool out there!
-- Thanks to [StyleCI](https://styleci.io/) for the simple but powerfull code style check.
 - Thanks to [PHPStan](https://github.com/phpstan/phpstan) && [Psalm](https://github.com/vimeo/psalm) for really great Static analysis tools and for discover bugs in the code!

composer.json

@@ -16,18 +16,19 @@
         }
     ],
     "require": {
-        "php": ">=7.4",
+        "php": ">=8.1",
         "react/async": "~3.0.0 || ~4.1.0",
         "react/filesystem": "^0.2@dev",
         "phpdocumentor/type-resolver": "~1.7.2",
         "phpdocumentor/reflection-docblock": "~5.3",
         "phpdocumentor/reflection-common": "~2.2",
         "phpstan/phpdoc-parser": "~1.23",
         "voku/simple-cache": "~4.1",
-        "nikic/php-parser": "~4.16"
+        "nikic/php-parser": "~4.18"
     },
     "require-dev": {
-        "phpunit/phpunit": "~6.0 || ~7.0 || ~9.0"
+        "phpunit/phpunit": "~9.6",
+        "phpstan/phpstan": "^1.10"
     },
     "autoload": {
         "psr-4": {

src/voku/SimplePhpParser/Model/BasePHPClass.php

@@ -23,6 +23,13 @@ abstract class BasePHPClass extends BasePHPElement
      */
     public array $constants = [];
 
+    /**
+     * PHP 8.0+ attributes on this class/interface/trait/enum.
+     *
+     * @var PHPAttribute[]
+     */
+    public array $attributes = [];
+
     public ?bool $is_final = null;
 
     public ?bool $is_abstract = null;

src/voku/SimplePhpParser/Model/PHPAttribute.php

@@ -0,0 +1,29 @@
+<?php
+
+declare(strict_types=1);
+
+namespace voku\SimplePhpParser\Model;
+
+/**
+ * Represents a single PHP 8.0+ attribute instance.
+ */
+class PHPAttribute
+{
+    /**
+     * Fully qualified attribute class name.
+     */
+    public string $name;
+
+    /**
+     * Attribute constructor arguments.
+     *
+     * @var array<int|string, mixed>
+     */
+    public array $arguments = [];
+
+    public function __construct(string $name, array $arguments = [])
+    {
+        $this->name = $name;
+        $this->arguments = $arguments;
+    }
+}

src/voku/SimplePhpParser/Model/PHPClass.php

@@ -50,13 +50,26 @@
 
         $this->is_anonymous = $node->isAnonymous();
 
+        // Extract PHP 8.0+ attributes
+        if (!empty($node->attrGroups)) {
+            $this->attributes = Utils::extractAttributesFromAstNode($node->attrGroups);
+        }
+
+        // PHP < 8.2 raises an uncatchable E_COMPILE_ERROR for certain PHP 8.2+ syntax
+        // (standalone true/false/null types, DNF types, readonly class). Similarly,
+        // PHP < 8.3 raises an error for PHP 8.3+ syntax (typed class constants).
+        // Skip autoloading in those cases; AST data is still read from the node below.
+        $canAutoload = (\PHP_VERSION_ID >= 80200 || !self::nodeUsesPHP82PlusSyntax($node))
+            && (\PHP_VERSION_ID >= 80300 || !self::nodeUsesPHP83PlusSyntax($node));
         $classExists = false;
-        try {
-            if (\class_exists($this->name, true)) {
-                $classExists = true;
+        if ($canAutoload) {
+            try {
+                if (\class_exists($this->name, true)) {
+                    $classExists = true;
+                }
+            } catch (\Throwable $e) {
+                // nothing
             }
-        } catch (\Exception $e) {
-            // nothing
         }
         if ($classExists) {
             $reflectionClass = Utils::createClassReflectionInstance($this->name);
@@ -156,6 +169,9 @@
 
         $this->is_iterable = $clazz->isIterable();
 
+        // Extract PHP 8.0+ attributes
+        $this->attributes = Utils::extractAttributesFromReflection($clazz);
+
         $parent = $clazz->getParentClass();
         if ($parent) {
             $this->parentClass = $parent->getName();
@@ -169,7 +185,7 @@
                 ) {
                     $classExists = true;
                 }
-            } catch (\Exception $e) {
+            } catch (\Throwable $e) {
                 // nothing
             }
             if ($classExists) {
@@ -442,4 +458,102 @@
             $this->parseError[\md5($tmpErrorMessage)] = $tmpErrorMessage;
         }
     }
+
+    /**
+     * Returns true if the class node uses syntax that requires PHP 8.2+ and would
+     * cause an uncatchable E_COMPILE_ERROR when autoloaded on PHP < 8.2.
+     *
+     * @param Class_ $node
+     *
+     * @return bool
+     */
+    private static function nodeUsesPHP82PlusSyntax(Class_ $node): bool
+    {
+        // readonly class is PHP 8.2+
+        if (\method_exists($node, 'isReadOnly') && $node->isReadOnly()) {
+            return true;
+        }
+
+        foreach ($node->stmts as $stmt) {
+            if ($stmt instanceof \PhpParser\Node\Stmt\ClassMethod) {
+                if (self::containsPHP82PlusType($stmt->returnType)) {
+                    return true;
+                }
+                foreach ($stmt->params as $param) {
+                    if (self::containsPHP82PlusType($param->type)) {
+                        return true;
+                    }
+                }
+            } elseif ($stmt instanceof \PhpParser\Node\Stmt\Property) {
+                if (self::containsPHP82PlusType($stmt->type)) {
+                    return true;
+                }
+            }
+        }
+
+        return false;
+    }
+
+    /**
+     * Returns true if the class node uses syntax that requires PHP 8.3+ and would
+     * cause an uncatchable E_COMPILE_ERROR when autoloaded on PHP < 8.3.
+     *
+     * Covers: typed class constants (Stmt\ClassConst with a non-null type).
+     *
+     * @param Class_ $node
+     *
+     * @return bool
+     */
+    private static function nodeUsesPHP83PlusSyntax(Class_ $node): bool
+    {
+        foreach ($node->stmts as $stmt) {
+            // Typed class constants are PHP 8.3+
+            if ($stmt instanceof \PhpParser\Node\Stmt\ClassConst && $stmt->type !== null) {
+                return true;
+            }
+        }
+
+        return false;
+    }
+
+    /**
+     * Returns true if the given type node is a PHP 8.2+ type that causes an
+     * uncatchable E_COMPILE_ERROR when loaded on PHP < 8.2.
+     *
+     * Covers: standalone true/false/null types and DNF types (union of intersections).
+     *
+     * @param \PhpParser\Node|null $typeNode
+     *
+     * @return bool
+     */
+    private static function containsPHP82PlusType($typeNode): bool
+    {
+        if ($typeNode === null) {
+            return false;
+        }
+
+        // Standalone true, false, null as the *sole* type (not in a nullable like ?string)
+        // are PHP 8.2+ only. PHP-Parser represents these as Identifier nodes (not Name).
+        // Nullable null (?null) is syntactically invalid; NullableType wraps the inner type.
+        if ($typeNode instanceof \PhpParser\Node\Identifier) {
+            $name = \strtolower($typeNode->name);
+            return $name === 'true' || $name === 'false' || $name === 'null';
+        }
+
+        // DNF types: union type containing an intersection type (PHP 8.2+)
+        if ($typeNode instanceof \PhpParser\Node\UnionType) {
+            foreach ($typeNode->types as $t) {
+                if ($t instanceof \PhpParser\Node\IntersectionType || self::containsPHP82PlusType($t)) {
+                    return true;
+                }
+            }
+        }
+
+        // Recurse into nullable type
+        if ($typeNode instanceof \PhpParser\Node\NullableType) {
+            return self::containsPHP82PlusType($typeNode->type);
+        }
+
+        return false;
+    }
 }