Add InstallationCompletedEvent for post-installation actions

lib/private/Setup.php

@@ -23,12 +23,14 @@
 use OCP\AppFramework\Utility\ITimeFactory;
 use OCP\BackgroundJob\IJobList;
 use OCP\Defaults;
+use OCP\EventDispatcher\IEventDispatcher;
 use OCP\Http\Client\IClientService;
 use OCP\IAppConfig;
 use OCP\IConfig;
 use OCP\IGroup;
 use OCP\IGroupManager;
 use OCP\IL10N;
+use OCP\Install\Events\InstallationCompletedEvent;
 use OCP\IRequest;
 use OCP\IURLGenerator;
 use OCP\IUserManager;
@@ -51,6 +53,7 @@ public function __construct(
 		protected LoggerInterface $logger,
 		protected ISecureRandom $random,
 		protected Installer $installer,
+		protected IEventDispatcher $eventDispatcher,
 	) {
 		$this->l10n = $l10nFactory->get('lib');
 	}
@@ -495,6 +498,13 @@ public function install(array $options, ?IOutput $output = null): array {
 			}
 		}
 
+		// Dispatch installation completed event
+		$adminUsername = !$disableAdminUser ? ($options['adminlogin'] ?? null) : null;
+		$adminEmail = !empty($options['adminemail']) ? $options['adminemail'] : null;
+		$this->eventDispatcher->dispatchTyped(
+			new InstallationCompletedEvent($dataDir, $adminUsername, $adminEmail)
+		);
+
 		return $error;
 	}
 

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 31.0.0
+ */
+class InstallationCompletedEvent extends Event {
+	/**
+	 * @since 31.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 31.0.0
+	 */
+	public function getDataDirectory(): string {
+		return $this->dataDirectory;
+	}
+
+	/**
+	 * Get the admin username if an admin user was created
+	 *
+	 * @since 31.0.0
+	 */
+	public function getAdminUsername(): ?string {
+		return $this->adminUsername;
+	}
+
+	/**
+	 * Get the admin email if configured
+	 *
+	 * @since 31.0.0
+	 */
+	public function getAdminEmail(): ?string {
+		return $this->adminEmail;
+	}
+
+	/**
+	 * Check if an admin user was created during installation
+	 *
+	 * @since 31.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 = '[email protected]';
+
+		$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 = '[email protected]';
+
+		$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, '[email protected]');
+
+		$this->assertFalse($event->hasAdminUser());
+		$this->assertNull($event->getAdminUsername());
+		$this->assertEquals('[email protected]', $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 = '[email protected]';
+
+		$event = new InstallationCompletedEvent($dataDir, null, $email);
+
+		$this->assertNull($event->getAdminUsername());
+		$this->assertEquals($email, $event->getAdminEmail());
+		$this->assertFalse($event->hasAdminUser());
+	}
+}

tests/lib/SetupTest.php

@@ -13,7 +13,9 @@
 use OC\Setup;
 use OC\SystemConfig;
 use OCP\Defaults;
+use OCP\EventDispatcher\IEventDispatcher;
 use OCP\IL10N;
+use OCP\Install\Events\InstallationCompletedEvent;
 use OCP\L10N\IFactory as IL10NFactory;
 use OCP\Security\ISecureRandom;
 use Psr\Log\LoggerInterface;
@@ -28,6 +30,7 @@ class SetupTest extends \Test\TestCase {
 	protected LoggerInterface $logger;
 	protected ISecureRandom $random;
 	protected Installer $installer;
+	protected IEventDispatcher $eventDispatcher;
 
 	protected function setUp(): void {
 		parent::setUp();
@@ -42,9 +45,10 @@ protected function setUp(): void {
 		$this->logger = $this->createMock(LoggerInterface::class);
 		$this->random = $this->createMock(ISecureRandom::class);
 		$this->installer = $this->createMock(Installer::class);
+		$this->eventDispatcher = $this->createMock(IEventDispatcher::class);
 		$this->setupClass = $this->getMockBuilder(Setup::class)
 			->onlyMethods(['class_exists', 'is_callable', 'getAvailableDbDriversForPdo'])
-			->setConstructorArgs([$this->config, $this->iniWrapper, $this->l10nFactory, $this->defaults, $this->logger, $this->random, $this->installer])
+			->setConstructorArgs([$this->config, $this->iniWrapper, $this->l10nFactory, $this->defaults, $this->logger, $this->random, $this->installer, $this->eventDispatcher])
 			->getMock();
 	}
 
@@ -170,4 +174,87 @@ public static function findWebRootProvider(): array {
 			'empty' => ['', false],
 		];
 	}
+
+	/**
+	 * Test that Setup class has eventDispatcher injected
+	 */
+	public function testSetupHasEventDispatcher(): void {
+		$reflectionClass = new \ReflectionClass($this->setupClass);
+		$property = $reflectionClass->getProperty('eventDispatcher');
+		$property->setAccessible(true);
+
+		$eventDispatcher = $property->getValue($this->setupClass);
+
+		$this->assertInstanceOf(IEventDispatcher::class, $eventDispatcher);
+	}
+
+	/**
+	 * Helper method to extract event parameters from install options
+	 * This mirrors the logic in Setup::install() for extracting dataDir and admin parameters
+	 * 
+	 * Note: This assumes 'directory' key is present in options. Setup::install() has a fallback
+	 * that sets a default directory if empty, but our tests always provide this key.
+	 */
+	private function extractInstallationEventParameters(array $options): array {
+		$dataDir = htmlspecialchars_decode($options['directory']);
+		$disableAdminUser = (bool)($options['admindisable'] ?? false);
+		$adminUsername = !$disableAdminUser ? ($options['adminlogin'] ?? null) : null;
+		$adminEmail = !empty($options['adminemail']) ? $options['adminemail'] : null;
+
+		return [$dataDir, $adminUsername, $adminEmail];
+	}
+
+	/**
+	 * Test that InstallationCompletedEvent can be created with parameters from install options
+	 *
+	 * This test verifies that the InstallationCompletedEvent can be properly constructed with
+	 * the parameters that Setup::install() extracts from the options array for dataDir and admin parameters.
+	 *
+	 * Note: Testing that Setup::install() actually dispatches this event requires a full integration
+	 * test with database setup, file system operations, and app installation, which is beyond the
+	 * scope of a unit test. The event class itself is thoroughly tested in InstallationCompletedEventTest.php.
+	 */
+	public function testInstallationCompletedEventParametersFromInstallOptions(): void {
+		// Simulate the options array as passed to Setup::install()
+		$options = [
+			'directory' => '/path/to/data',
+			'adminlogin' => 'admin',
+			'adminemail' => '[email protected]',
+		];
+
+		// Extract parameters the same way Setup::install() does
+		[$dataDir, $adminUsername, $adminEmail] = $this->extractInstallationEventParameters($options);
+
+		// Create the event as Setup::install() does after successful installation
+		$event = new InstallationCompletedEvent($dataDir, $adminUsername, $adminEmail);
+
+		// Verify the event contains the expected values
+		$this->assertEquals($dataDir, $event->getDataDirectory());
+		$this->assertEquals($adminUsername, $event->getAdminUsername());
+		$this->assertEquals($adminEmail, $event->getAdminEmail());
+		$this->assertTrue($event->hasAdminUser());
+	}
+
+	/**
+	 * Test that event parameters handle disabled admin user correctly
+	 *
+	 * This tests the scenario where Setup::install() is called with admindisable=true,
+	 * resulting in a null adminUsername in the event.
+	 */
+	public function testInstallationCompletedEventWithDisabledAdminUser(): void {
+		$options = [
+			'directory' => '/path/to/data',
+			'admindisable' => true,
+		];
+
+		// Extract parameters as Setup::install() does
+		[$dataDir, $adminUsername, $adminEmail] = $this->extractInstallationEventParameters($options);
+
+		$event = new InstallationCompletedEvent($dataDir, $adminUsername, $adminEmail);
+
+		$this->assertEquals($dataDir, $event->getDataDirectory());
+		$this->assertNull($event->getAdminUsername());
+		$this->assertNull($event->getAdminEmail());
+		$this->assertFalse($event->hasAdminUser());
+	}
 }