feat: generate list of OCP events

.github/workflows/update-ocp-events.yml

@@ -0,0 +1,67 @@
+# SPDX-FileCopyrightText: 2026 Nextcloud GmbH and Nextcloud contributors
+# SPDX-License-Identifier: MIT
+
+name: Update OCP events
+
+on:
+  workflow_dispatch:
+  schedule:
+    - cron: '5 22 * * 6'
+
+permissions:
+  contents: read
+
+jobs:
+  update-ocp-events:
+    runs-on: ubuntu-latest
+
+    if: ${{ github.repository_owner == 'nextcloud' }}
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          persist-credentials: false
+
+      - name: Set up php
+        uses: shivammathur/setup-php@eb7c497e18156a6bbabfef1d3a82760b9eda3962 # v2.40.0
+        with:
+          php-version: '8.5'
+          coverage: none
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+
+      - name: Install composer dependencies
+        uses: ramsey/composer-install@65e4f84970763564f46a70b8a54b90d033b3bdda # 4.0.0
+        with:
+          working-directory: build/ocp-events
+
+      - name: Update events
+        run: php build/ocp-events/update_events.php
+
+      - uses: peter-evans/create-pull-request@5f6978faf089d4d20b00c7766989d076bb2fc7f1 # v8.1.1
+        id: cpr
+        with:
+          token: ${{ secrets.COMMAND_BOT_PAT }}
+          commit-message: 'chore: update list of OCP events'
+          committer: GitHub <noreply@github.com>
+          author: nextcloud-command <nextcloud-command@users.noreply.github.com>
+          signoff: true
+          branch: 'automated/noid/update-ocp-events'
+          title: 'Update list of OCP events'
+          add-paths: developer_manual/basics/_available_events_ocp.rst
+
+      - uses: hmarr/auto-approve-action@f0939ea97e9205ef24d872e76833fa908a770363 # v4.0.0
+        if: steps.cpr.outputs.pull-request-operation == 'created'
+        with:
+          github-token: "${{ secrets.GITHUB_TOKEN }}"
+          pull-request-number: ${{ steps.cpr.outputs.pull-request-number }}
+
+      - uses: pascalgn/automerge-action@7961b8b5eec56cc088c140b56d864285eabd3f67 # v0.16.4
+        if: steps.cpr.outputs.pull-request-operation == 'created'
+        env:
+          GITHUB_TOKEN: "${{ secrets.GITHUB_TOKEN }}"
+          MERGE_LABELS: ""
+          MERGE_RETRIES: 10
+          MERGE_RETRY_SLEEP: 60000
+          PULL_REQUEST: ${{ steps.cpr.outputs.pull-request-number }}

.gitignore

@@ -7,6 +7,9 @@ build/index.html
 build/vendor/
 build/server/
 build/composer.lock
+build/ocp-events/vendor/
+build/ocp-events/composer.lock
+build/ocp-events/.php-cs-fixer.cache
 developer_manual/api/
 server/
 _build

build/ocp-events/.php-cs-fixer.dist.php

@@ -0,0 +1,15 @@
+<?php
+
+declare(strict_types=1);
+
+require_once './vendor/autoload.php';
+
+use Nextcloud\CodingStandard\Config;
+
+$config = new Config();
+$config
+    ->getFinder()
+    ->ignoreVCSIgnored(true)
+    ->notPath('vendor')
+    ->in(__DIR__);
+return $config;

build/ocp-events/composer.json

@@ -0,0 +1,25 @@
+{
+    "require": {
+        "nette/robot-loader": "^4.0",
+        "nextcloud/ocp": "dev-master",
+        "phpdocumentor/reflection-docblock": "^6.0"
+    },
+    "require-dev": {
+        "ergebnis/composer-normalize": "^2.43",
+        "nextcloud/coding-standard": "^1.2"
+    },
+    "autoload": {
+        "psr-4": {
+            "": "lib"
+        }
+    },
+    "config": {
+        "allow-plugins": {
+            "ergebnis/composer-normalize": true
+        }
+    },
+    "scripts": {
+        "cs:check": "php-cs-fixer fix --dry-run --diff",
+        "cs:fix": "php-cs-fixer fix"
+    }
+}

build/ocp-events/lib/EventClass.php

@@ -0,0 +1,18 @@
+<?php
+
+declare(strict_types=1);
+
+/**
+ * SPDX-FileCopyrightText: 2024 Nextcloud GmbH and Nextcloud contributors
+ * SPDX-License-Identifier: AGPL-3.0-or-later
+ */
+
+class EventClass {
+	public function __construct(
+		public readonly string $className,
+		public readonly string $summary,
+		public readonly string $description,
+		public readonly array $sinceTags,
+	) {
+	}
+}

build/ocp-events/lib/EventFinder.php

@@ -0,0 +1,122 @@
+<?php
+
+declare(strict_types=1);
+
+/**
+ * SPDX-FileCopyrightText: 2024 Nextcloud GmbH and Nextcloud contributors
+ * SPDX-License-Identifier: AGPL-3.0-or-later
+ */
+
+class EventFinder {
+
+	/**
+	 * Parent class for events.
+	 */
+	private const string EVENT_CLASS = \OCP\EventDispatcher\Event::class;
+
+	/**
+	 * The classes below are skipped because they depend on "private" dependencies
+	 * and will trigger a fatal error when loading with reflection class.
+	 */
+	private const array SKIP_CLASSES = [
+		\OCP\Diagnostics\IQueryLogger::class,
+		\OCP\Files\IRootFolder::class,
+		\OCP\Files_FullTextSearch\Model\AFilesDocument::class,
+		\OCP\Image::class,
+		\OCP\SabrePluginException::class,
+		\OCP\Share::class,
+		\OCP\Template::class,
+	];
+
+	public function __construct(
+		private array $classes,
+	) {
+
+	}
+
+	/**
+	 * @return EventClass[]
+	 */
+	public function find(): array {
+		$docBlockFactory = \phpDocumentor\Reflection\DocBlockFactory::createInstance();
+
+		$result = [];
+
+		foreach ($this->classes as $className => $classPath) {
+			if (in_array($className, self::SKIP_CLASSES)) {
+				continue;
+			}
+
+			try {
+				$reflection = new ReflectionClass($className);
+			} catch (ReflectionException $e) {
+				continue;
+			}
+
+			if ($reflection->isAbstract()) {
+				continue;
+			}
+
+			$isEventClass = false;
+			$parentClass = $reflection->getParentClass();
+
+			while ($isEventClass === false && $parentClass !== false) {
+				$isEventClass = $parentClass->getName() === self::EVENT_CLASS;
+				$parentClass = $parentClass->getParentClass();
+			}
+
+			if ($isEventClass === false) {
+				continue;
+			}
+
+			$docBlock = $docBlockFactory->create($reflection->getDocComment() ?: '/** */');
+
+			$sinceTags = array_map(function (\phpDocumentor\Reflection\DocBlock\Tags\Since $tag) {
+				$data = [
+					'version' => $tag->getVersion(),
+					'description' => '',
+				];
+
+				$description = $tag->getDescription();
+				if ($description instanceof \phpDocumentor\Reflection\DocBlock\Description) {
+					$data['description'] = $description->render();
+				}
+
+				return $data;
+			}, $docBlock->getTagsByName('since'));
+
+			if ($sinceTags === []) {
+				$sinceTags = $this->sinceFromAttributes($reflection);
+			}
+
+			$result[] = new EventClass(
+				$reflection->getName(),
+				$docBlock->getSummary(),
+				$docBlock->getDescription()->render(),
+				$sinceTags
+			);
+		}
+
+		usort($result, static function (EventClass $a, EventClass $b) {
+			return strcasecmp($a->className, $b->className);
+		});
+
+		return $result;
+	}
+
+	private function sinceFromAttributes(ReflectionClass $reflection): array {
+		$versions = [];
+		foreach ([\OCP\AppFramework\Attribute\Listenable::class, \OCP\AppFramework\Attribute\Dispatchable::class] as $attributeClass) {
+			foreach ($reflection->getAttributes($attributeClass) as $attribute) {
+				$versions[] = $attribute->newInstance()->getSince();
+			}
+		}
+
+		if ($versions === []) {
+			return [];
+		}
+
+		usort($versions, 'version_compare');
+		return [['version' => $versions[0], 'description' => '']];
+	}
+}

build/ocp-events/lib/ReStructuredTextFormatter.php

@@ -0,0 +1,56 @@
+<?php
+
+declare(strict_types=1);
+
+/**
+ * SPDX-FileCopyrightText: 2024 Nextcloud GmbH and Nextcloud contributors
+ * SPDX-License-Identifier: AGPL-3.0-or-later
+ */
+class ReStructuredTextFormatter {
+	/**
+	 * @param EventClass[] $events
+	 */
+	public function format(array $events): string {
+		$output = '.. This file is generated by nextcloud-ocp-events.' . PHP_EOL;
+		$output .= '.. Always change the source file.' . PHP_EOL;
+		$output .= PHP_EOL;
+
+		foreach ($events as $event) {
+			$output .= '``' . $event->className . '``' . PHP_EOL;
+			$output .= str_repeat('*', strlen($event->className) + 4) . PHP_EOL;
+			$output .= PHP_EOL;
+
+			foreach ($event->sinceTags as $i => $sinceTag) {
+				if ($i === 0) {
+					$output .= '.. versionadded:: ' . $this->adjustVersion($sinceTag['version']) . PHP_EOL;
+					if (strlen($sinceTag['description']) > 0) {
+						$output .= '   ' . $sinceTag['description'] . PHP_EOL;
+					}
+				} else {
+					$output .= '.. versionchanged:: ' . $sinceTag['version'] . PHP_EOL;
+					if (strlen($sinceTag['description']) > 0) {
+						$output .= '   ' . $sinceTag['description'] . PHP_EOL;
+					}
+				}
+				$output .= PHP_EOL;
+			}
+
+			if (strlen($event->summary) > 0) {
+				$output .= $event->summary . PHP_EOL;
+			}
+
+			if (strlen($event->description) > 0) {
+				$output .= $event->description . PHP_EOL;
+			}
+
+			$output .= PHP_EOL;
+
+		}
+
+		return $output;
+	}
+
+	private function adjustVersion(string $version): string {
+		return preg_replace("/(\.0\.0|\.0)$/", '', $version);
+	}
+}

build/ocp-events/update_events.php

@@ -0,0 +1,29 @@
+<?php
+
+declare(strict_types=1);
+
+/**
+ * SPDX-FileCopyrightText: 2024 Nextcloud GmbH and Nextcloud contributors
+ * SPDX-License-Identifier: AGPL-3.0-or-later
+ */
+
+require __DIR__ . '/vendor/autoload.php';
+
+$loader = new Nette\Loaders\RobotLoader;
+$loader->addDirectory(__DIR__ . '/vendor/nextcloud/ocp/OCP');
+$loader->setTempDirectory(sys_get_temp_dir());
+$loader->register();
+
+$loader->rebuild();
+$classes = $loader->getIndexedClasses();
+
+$eventFinder = new EventFinder($classes);
+$events = $eventFinder->find();
+
+$formatter = new ReStructuredTextFormatter();
+$rest = $formatter->format($events);
+
+file_put_contents(
+	__DIR__ . '/../../developer_manual/basics/_available_events_ocp.rst',
+	$rest
+);