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>

Author: printminion-co

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;
+	}
+}

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());
+	}
+}