Add Nexus API deployment

Author: paulbalandan

.github/workflows/deploy-nexus-api.yml

@@ -0,0 +1,83 @@
+name: Deploy Nexus API
+
+on:
+  push:
+    branches:
+      - '1.x'
+    paths:
+      - src
+  workflow_dispatch:
+
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+concurrency:
+  group: pages
+  cancel-in-progress: false
+
+jobs:
+  build:
+    runs-on: ubuntu-22.04
+    if: github.repository == 'NexusPHP/framework'
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Setup PHP
+        uses: shivammathur/setup-php@v2
+        with:
+          php-version: '8.3'
+          coverage: none
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+
+      - name: Setup global variables
+        id: globals
+        run: |
+          echo "COMPOSER_CACHE_DIR=$(composer config cache-dir)" >> $GITHUB_OUTPUT
+
+      - name: Cache Composer dependencies
+        uses: actions/cache@v4
+        with:
+          path: ${{ steps.globals.outputs.COMPOSER_CACHE_DIR }}
+          key: ${{ github.workflow }}-PHP_8.3-${{ hashFiles('**/composer.json') }}
+          restore-keys: |
+            ${{ github.workflow }}-PHP_8.3-
+
+      - name: Install dependencies
+        run: |
+          echo ::group::composer update --ansi
+          composer update --ansi
+          echo ::endgroup::
+
+          echo ::group::composer update --ansi --working-dir api
+          composer update --ansi --working-dir api
+          echo ::endgroup::
+
+      - name: Setup Pages
+        id: pages
+        uses: actions/configure-pages@v5
+
+      - name: Generate Nexus API
+        run: api/vendor/bin/apigen src --ansi --output api/docs --title Nexus --config api/apigen.neon
+
+      - name: Upload pages artifact
+        uses: actions/upload-pages-artifact@v3
+        with:
+          path: api/docs
+
+  deploy:
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+
+    runs-on: ubuntu-22.04
+    needs: build
+
+    steps:
+      - name: Deploy Nexus API
+        id: deployment
+        uses: actions/deploy-pages@v4

.php-cs-fixer.dist.php

@@ -29,6 +29,7 @@
     ->files()
     ->in([
         __DIR__.'/.github',
+        __DIR__.'/api',
         __DIR__.'/bin',
         __DIR__.'/src',
         __DIR__.'/tests',

api/.gitignore

@@ -0,0 +1,3 @@
+/docs
+/vendor
+/composer.lock

api/apigen.neon

@@ -0,0 +1,13 @@
+parameters:
+  title: Nexus
+
+services:
+  analyzer.filter:
+    factory: Nexus\Api\AnalyserFilter
+    arguments:
+      excludeProtected: %excludeProtected%
+      excludePrivate: %excludePrivate%
+      excludeTagged: %excludeTagged%
+
+  renderer.filter:
+    factory: Nexus\Api\RendererFilter

api/composer.json

@@ -0,0 +1,11 @@
+{
+    "require": {
+        "php": "^8.3",
+        "apigen/apigen": "dev-master"
+    },
+    "autoload": {
+        "psr-4": {
+            "Nexus\\Api\\": "src/"
+        }
+    }
+}

api/src/AnalyserFilter.php

@@ -0,0 +1,51 @@
+<?php
+
+declare(strict_types=1);
+
+/**
+ * This file is part of the Nexus framework.
+ *
+ * (c) John Paul E. Balandan, CPA <[email protected]>
+ *
+ * For the full copyright and license information, please view
+ * the LICENSE file that was distributed with this source code.
+ */
+
+namespace Nexus\Api;
+
+use ApiGen\Analyzer\Filter;
+use ApiGen\Info\ClassLikeInfo;
+use ApiGen\Info\MemberInfo;
+use PhpParser\Node;
+
+final class AnalyserFilter extends Filter
+{
+    public function filterClassLikeNode(Node\Stmt\ClassLike $node): bool
+    {
+        $name = $node->namespacedName?->toString();
+
+        if (null === $name) {
+            return false;
+        }
+
+        return str_starts_with($name, 'Nexus\\');
+    }
+
+    public function filterFunctionNode(Node\Stmt\Function_ $node): bool
+    {
+        $name = $node->namespacedName?->toString();
+
+        if (null === $name) {
+            return false;
+        }
+
+        return str_starts_with($name, 'Nexus\\');
+    }
+
+    public function filterMemberInfo(ClassLikeInfo $classLike, MemberInfo $member): bool
+    {
+        $name = $classLike->name->full;
+
+        return str_starts_with($name, 'Nexus\\');
+    }
+}

api/src/RendererFilter.php

@@ -0,0 +1,80 @@
+<?php
+
+declare(strict_types=1);
+
+/**
+ * This file is part of the Nexus framework.
+ *
+ * (c) John Paul E. Balandan, CPA <[email protected]>
+ *
+ * For the full copyright and license information, please view
+ * the LICENSE file that was distributed with this source code.
+ */
+
+namespace Nexus\Api;
+
+use ApiGen\Index\NamespaceIndex;
+use ApiGen\Info\ClassLikeInfo;
+use ApiGen\Renderer\Filter;
+
+final class RendererFilter extends Filter
+{
+    public function filterNamespacePage(NamespaceIndex $namespace): bool
+    {
+        foreach ($namespace->children as $child) {
+            if ($this->filterNamespacePage($child)) {
+                return true;
+            }
+        }
+
+        foreach ($namespace->class as $class) {
+            if ($this->filterClassLikePage($class)) {
+                return true;
+            }
+        }
+
+        foreach ($namespace->interface as $interface) {
+            if ($this->filterClassLikePage($interface)) {
+                return true;
+            }
+        }
+
+        foreach ($namespace->trait as $trait) {
+            if ($this->filterClassLikePage($trait)) {
+                return true;
+            }
+        }
+
+        foreach ($namespace->enum as $enum) {
+            if ($this->filterClassLikePage($enum)) {
+                return true;
+            }
+        }
+
+        foreach ($namespace->exception as $exception) {
+            if ($this->filterClassLikePage($exception)) {
+                return true;
+            }
+        }
+
+        foreach ($namespace->function as $function) {
+            if ($this->filterFunctionPage($function)) {
+                return true;
+            }
+        }
+
+        return false;
+    }
+
+    public function filterClassLikePage(ClassLikeInfo $classLike): bool
+    {
+        return $this->isClassRendered($classLike);
+    }
+
+    private function isClassRendered(ClassLikeInfo $classLike): bool
+    {
+        $name = $classLike->name->full;
+
+        return str_starts_with($name, 'Nexus\\');
+    }
+}

phpstan.dist.neon

@@ -9,6 +9,7 @@ parameters:
   tmpDir: build/phpstan
   paths:
     - .github
+    - api
     - bin
     - src
     - tests
@@ -18,6 +19,7 @@ parameters:
       - tests/**/data/**
       - tests/PHPStan/**/data/**
     analyse:
+      - api/vendor/**
       - tools/vendor/**
   bootstrapFiles:
     - vendor/autoload.php