Add "@license" tag support

Author: Kirill Nesmeyanov

README.md

@@ -49,7 +49,7 @@ composer require type-lang/phpdoc
 - [ ] `@inheritdoc` - TODO
 - [x] `@inherits` - An alias of `@extends` tag
 - [ ] `@internal` - TODO
-- [ ] `@license` - TODO
+- [x] `@license` - Used to indicate which license is applicable
 - [x] `@link` - Indicates a custom relation between the associated _Symbol_ 
       and a website, which is identified by an absolute URI
 - [x] `@method` - Allows a class to know which "_magic_" methods are callable

composer.json

@@ -26,6 +26,7 @@
         ]
     },
     "require-dev": {
+        "composer/spdx-licenses": "^1.5",
         "friendsofphp/php-cs-fixer": "^3.70",
         "jetbrains/phpstorm-attributes": "^1.0",
         "phpstan/phpstan": "^2.1",
@@ -39,6 +40,9 @@
             "TypeLang\\PHPDoc\\Tests\\": "tests"
         }
     },
+    "suggest": {
+        "composer/spdx-licenses": "Provides additional licenses (@license tag) support"
+    },
     "extra": {
         "branch-alias": {
             "dev-master": "2.x-dev",

src/DocBlock/Tag/LicenseTag/LicenseTag.php

@@ -0,0 +1,36 @@
+<?php
+
+declare(strict_types=1);
+
+namespace TypeLang\PHPDoc\DocBlock\Tag\LicenseTag;
+
+use TypeLang\PHPDoc\DocBlock\Tag\Shared\Reference\UriReference;
+use TypeLang\PHPDoc\DocBlock\Tag\Tag;
+
+/**
+ * Used to indicate which license is applicable for the associated _Symbol_.
+ *
+ * The `"@license"` tag provides the user with the name and URL of the license
+ * that is applicable to a _Symbol_ and any of its child elements.
+ *
+ * Whenever multiple licenses apply, there MUST be one "`@license"` tag per
+ * applicable license.
+ *
+ * ```
+ * "@license" [<url>] [name]
+ * ```
+ */
+final class LicenseTag extends Tag
+{
+    public function __construct(
+        string $name,
+        public readonly ?UriReference $uri = null,
+        /**
+         * @var non-empty-string|null
+         */
+        public readonly ?string $license = null,
+        \Stringable|string|null $description = null,
+    ) {
+        parent::__construct($name, $description);
+    }
+}

src/DocBlock/Tag/LicenseTag/LicenseTagFactory.php

@@ -0,0 +1,67 @@
+<?php
+
+declare(strict_types=1);
+
+namespace TypeLang\PHPDoc\DocBlock\Tag\LicenseTag;
+
+use Composer\Spdx\SpdxLicenses;
+use League\Uri\Uri;
+use TypeLang\PHPDoc\DocBlock\Tag\Factory\TagFactoryInterface;
+use TypeLang\PHPDoc\DocBlock\Tag\Shared\Reference\UriReference;
+use TypeLang\PHPDoc\Parser\Content\Stream;
+use TypeLang\PHPDoc\Parser\Content\UriReferenceReader;
+use TypeLang\PHPDoc\Parser\Description\DescriptionParserInterface;
+
+/**
+ * This class is responsible for creating "`@license`" tags.
+ *
+ * See {@see LicenseTag} for details about this tag.
+ */
+final class LicenseTagFactory implements TagFactoryInterface
+{
+    private readonly ?SpdxLicenses $licenses;
+
+    public function __construct()
+    {
+        $this->licenses = $this->createSpdxLicenses();
+    }
+
+    private function createSpdxLicenses(): ?SpdxLicenses
+    {
+        if (\class_exists(SpdxLicenses::class)) {
+            return new SpdxLicenses();
+        }
+
+        return null;
+    }
+
+    public function create(string $tag, string $content, DescriptionParserInterface $descriptions): LicenseTag
+    {
+        $stream = new Stream($tag, $content);
+
+        try {
+            $uri = $stream->apply(new UriReferenceReader());
+        } catch (\Throwable) {
+            $uri = null;
+        }
+
+        $description = $identifier = ($suffix = \trim($stream->value)) === '' ? null : $suffix;
+
+        if ($this->licenses !== null && $identifier !== null) {
+            /** @var array{0:non-empty-string, 1:bool, 2:non-empty-string, 3:bool}|null $info */
+            $info = $this->licenses->getLicenseByIdentifier($identifier);
+
+            if ($info !== null) {
+                $uri ??= new UriReference(Uri::new($info[2]));
+                $description = $info[0];
+            }
+        }
+
+        return new LicenseTag(
+            name: $tag,
+            uri: $uri,
+            license: $identifier,
+            description: $description,
+        );
+    }
+}

src/Platform/StandardPlatform.php

@@ -10,6 +10,7 @@
 use TypeLang\PHPDoc\DocBlock\Tag\FinalTag\FinalTagFactory;
 use TypeLang\PHPDoc\DocBlock\Tag\IgnoreTag\IgnoreTagFactory;
 use TypeLang\PHPDoc\DocBlock\Tag\InheritDocTag\InheritDocTagFactory;
+use TypeLang\PHPDoc\DocBlock\Tag\LicenseTag\LicenseTagFactory;
 use TypeLang\PHPDoc\DocBlock\Tag\LinkTag\LinkTagFactory;
 use TypeLang\PHPDoc\DocBlock\Tag\MethodTag\MethodTagFactory;
 use TypeLang\PHPDoc\DocBlock\Tag\NoNamedArgumentsTag\NoNamedArgumentsTagFactory;
@@ -42,6 +43,7 @@ protected function load(TypesParserInterface $types): iterable
         yield 'implements' => new TemplateImplementsTagFactory($types);
         yield 'inheritdoc' => new InheritDocTagFactory();
         yield 'ignore' => new IgnoreTagFactory();
+        yield 'license' => new LicenseTagFactory();
         yield 'link' => new LinkTagFactory();
         yield 'method' => new MethodTagFactory($types);
         yield 'no-named-arguments' => new NoNamedArgumentsTagFactory();