From 977592313709173196d73b893706d97c3876dad7 Mon Sep 17 00:00:00 2001
From: "Misha M.-Kupriyanov" <kupriyanov@strato.de>
Date: Thu, 22 Jan 2026 15:37:41 +0100
Subject: [PATCH] feat(install): add InstallationCompletedEvent for
 post-installation hooks

Add InstallationCompletedEvent class in public API (OCP namespace) that
provides installation details: data directory, admin username, and admin
email. Event will be dispatched after successful installation.

Include comprehensive unit tests covering all event scenarios.

Signed-off-by: Misha M.-Kupriyanov <kupriyanov@strato.de>
---
 .../Events/InstallationCompletedEvent.php     | 79 ++++++++++++++++
 .../Events/InstallationCompletedEventTest.php | 89 +++++++++++++++++++
 2 files changed, 168 insertions(+)
 create mode 100644 lib/public/Install/Events/InstallationCompletedEvent.php
 create mode 100644 tests/lib/Install/Events/InstallationCompletedEventTest.php

diff --git a/lib/public/Install/Events/InstallationCompletedEvent.php b/lib/public/Install/Events/InstallationCompletedEvent.php
new file mode 100644
index 00000000000..7cf75d76d6f
--- /dev/null
+++ b/lib/public/Install/Events/InstallationCompletedEvent.php
@@ -0,0 +1,79 @@
+<?php
+
+declare(strict_types=1);
+
+/**
+ * SPDX-FileCopyrightText: 2026 Nextcloud GmbH and Nextcloud contributors
+ * SPDX-License-Identifier: AGPL-3.0-or-later
+ */
+namespace OCP\Install\Events;
+
+use OCP\EventDispatcher\Event;
+
+/**
+ * Emitted when the Nextcloud installation has been completed successfully.
+ *
+ * This event is dispatched after:
+ * - The database has been configured and migrations have run
+ * - The admin user has been created (if applicable)
+ * - Default apps have been installed
+ * - Background jobs have been configured
+ * - The system has been marked as installed
+ *
+ * Apps can listen to this event to perform additional actions after installation,
+ * such as:
+ * - Sending notification emails
+ * - Triggering external APIs
+ * - Initializing app-specific data
+ * - Setting up integrations
+ *
+ * @since 33.0.0
+ */
+class InstallationCompletedEvent extends Event {
+	/**
+	 * @since 33.0.0
+	 */
+	public function __construct(
+		private string $dataDirectory,
+		private ?string $adminUsername = null,
+		private ?string $adminEmail = null,
+	) {
+		parent::__construct();
+	}
+
+	/**
+	 * Get the configured data directory path
+	 *
+	 * @since 33.0.0
+	 */
+	public function getDataDirectory(): string {
+		return $this->dataDirectory;
+	}
+
+	/**
+	 * Get the admin username if an admin user was created
+	 *
+	 * @since 33.0.0
+	 */
+	public function getAdminUsername(): ?string {
+		return $this->adminUsername;
+	}
+
+	/**
+	 * Get the admin email if configured
+	 *
+	 * @since 33.0.0
+	 */
+	public function getAdminEmail(): ?string {
+		return $this->adminEmail;
+	}
+
+	/**
+	 * Check if an admin user was created during installation
+	 *
+	 * @since 33.0.0
+	 */
+	public function hasAdminUser(): bool {
+		return $this->adminUsername !== null;
+	}
+}
diff --git a/tests/lib/Install/Events/InstallationCompletedEventTest.php b/tests/lib/Install/Events/InstallationCompletedEventTest.php
new file mode 100644
index 00000000000..3a973e008b9
--- /dev/null
+++ b/tests/lib/Install/Events/InstallationCompletedEventTest.php
@@ -0,0 +1,89 @@
+<?php
+
+declare(strict_types=1);
+
+/**
+ * SPDX-FileCopyrightText: 2026 Nextcloud GmbH and Nextcloud contributors
+ * SPDX-License-Identifier: AGPL-3.0-or-later
+ */
+
+namespace Test\Install\Events;
+
+use OCP\Install\Events\InstallationCompletedEvent;
+
+class InstallationCompletedEventTest extends \Test\TestCase {
+	public function testConstructorWithAllParameters(): void {
+		$dataDir = '/path/to/data';
+		$adminUsername = 'admin';
+		$adminEmail = 'admin@example.com';
+
+		$event = new InstallationCompletedEvent($dataDir, $adminUsername, $adminEmail);
+
+		$this->assertEquals($dataDir, $event->getDataDirectory());
+		$this->assertEquals($adminUsername, $event->getAdminUsername());
+		$this->assertEquals($adminEmail, $event->getAdminEmail());
+		$this->assertTrue($event->hasAdminUser());
+	}
+
+	public function testConstructorWithMinimalParameters(): void {
+		$dataDir = '/path/to/data';
+
+		$event = new InstallationCompletedEvent($dataDir);
+
+		$this->assertEquals($dataDir, $event->getDataDirectory());
+		$this->assertNull($event->getAdminUsername());
+		$this->assertNull($event->getAdminEmail());
+		$this->assertFalse($event->hasAdminUser());
+	}
+
+	public function testConstructorWithUsernameOnly(): void {
+		$dataDir = '/path/to/data';
+		$adminUsername = 'admin';
+
+		$event = new InstallationCompletedEvent($dataDir, $adminUsername);
+
+		$this->assertEquals($dataDir, $event->getDataDirectory());
+		$this->assertEquals($adminUsername, $event->getAdminUsername());
+		$this->assertNull($event->getAdminEmail());
+		$this->assertTrue($event->hasAdminUser());
+	}
+
+	public function testConstructorWithUsernameAndEmail(): void {
+		$dataDir = '/path/to/data';
+		$adminUsername = 'admin';
+		$adminEmail = 'admin@example.com';
+
+		$event = new InstallationCompletedEvent($dataDir, $adminUsername, $adminEmail);
+
+		$this->assertEquals($dataDir, $event->getDataDirectory());
+		$this->assertEquals($adminUsername, $event->getAdminUsername());
+		$this->assertEquals($adminEmail, $event->getAdminEmail());
+		$this->assertTrue($event->hasAdminUser());
+	}
+
+	public function testHasAdminUserReturnsFalseWhenUsernameIsNull(): void {
+		$event = new InstallationCompletedEvent('/path/to/data', null, 'admin@example.com');
+
+		$this->assertFalse($event->hasAdminUser());
+		$this->assertNull($event->getAdminUsername());
+		$this->assertEquals('admin@example.com', $event->getAdminEmail());
+	}
+
+	public function testDataDirectoryCanBeAnyString(): void {
+		$customPath = '/custom/data/directory';
+		$event = new InstallationCompletedEvent($customPath);
+
+		$this->assertEquals($customPath, $event->getDataDirectory());
+	}
+
+	public function testEmailCanBeSetWithoutUsername(): void {
+		$dataDir = '/path/to/data';
+		$email = 'admin@example.com';
+
+		$event = new InstallationCompletedEvent($dataDir, null, $email);
+
+		$this->assertNull($event->getAdminUsername());
+		$this->assertEquals($email, $event->getAdminEmail());
+		$this->assertFalse($event->hasAdminUser());
+	}
+}