diff --git a/docs/Application-flow.md b/docs/Application-flow.md index eadb6d7..ad19b0e 100644 --- a/docs/Application-flow.md +++ b/docs/Application-flow.md @@ -46,7 +46,7 @@ At any point of the flow, by holding an instance of the `Package`, it is possibl 1. Upon instantiation, the `Package` status is at **`Package::STATUS_IDLE`** 2. Modules can be added by directly calling **`Package::addModule()`** on the instance, and other packages can be added by calling **`Package::connect()`**. 3. **`Package::build()`** is called. -4. The `Package` status moves to **`Package::STATUS_INIT`**. +4. The `Package` status moves to **`Package::STATUS_INITIALIZING`**. 5. The **`Package::ACTION_INIT`** action hook is fired, passing the package instance as an argument. That allows external code to add modules and connect other packages. 6. The `Package` status moves to **`Package::STATUS_INITIALIZED`**. No more modules can be added. 7. The **`Package::ACTION_INITIALIZED`** action hook is fired, passing the package instance as an argument. That allows external code to get services from the container. @@ -58,8 +58,8 @@ At any point of the flow, by holding an instance of the `Package`, it is possibl 1. **`Package::boot()`** is called. 2. `Package` status moves to **`Package::STATUS_BOOTING`**. 3. **All executables modules run**. That is when all the application behavior happens. -4. The `Package` status moves to **`Package::STATUS_READY`**. -5. The **`Package::ACTION_READY`** action hook is fired, passing the package instance as an argument. +4. The `Package` status moves to **`Package::STATUS_BOOTED`**. +5. The **`Package::ACTION_BOOTED`** action hook is fired, passing the package instance as an argument. 6. The `Package` status moves to **`Package::STATUS_DONE`**. The booting stage is completed. `Package::boot()` returns true. diff --git a/docs/Package.md b/docs/Package.md index 6b93afc..15e6e4b 100644 --- a/docs/Package.md +++ b/docs/Package.md @@ -24,9 +24,9 @@ It has been mentioned how during both the "build" and "boot" phases the `Package There are three package-specific hooks: -- `Package::ACTION_INIT`, fired at the beginning of the "build" phase, enables adding modules or connecting packages to the passed `Package` instance. +- `Package::ACTION_INITIALIZING`, fired at the beginning of the "build" phase, enables adding modules or connecting packages to the passed `Package` instance. - `Package::ACTION_INITIALIZED`, fired at the end of the "build" phase, enables external code to access `Package`'s container, resolving services. No modification to the `Package`'s services are possible at this time or later. -- `Package::ACTION_READY`, fired at the end of the "boot" phase, enables external code to access `Package`'s instance at a stage where it did all its job by registering services and adding hook to WordPress. +- `Package::ACTION_BOOTED`, fired at the end of the "boot" phase, enables external code to access `Package`'s instance at a stage where it did all its job by registering services and adding hook to WordPress. All the hooks above enable access to `Package` properties and to retrieve information about specific modules. @@ -327,12 +327,12 @@ Access to the wrapped [properties instance](./Properties.md). Retrieve the current status of the application. The following statuses are available: -| Status | Description | -|-------------------------------|-----------------------------------------------------------------------------------| -| `Package::STATUS_IDLE` | Before application is built or booted (`Package` instance just instantiated). | -| `Package::STATUS_INIT` | Before `Package::build()` started processing modules. | -| `Package::STATUS_INITIALIZED` | After `Package::build()` end processing modules. | -| `Package::STATUS_BOOTING` | Before `Package::boot()` started processing executable modules' "run procedures". | -| `Package::STATUS_READY` | After `Package::boot()` ended processing executable modules' "run procedures". | -| `Package::STATUS_DONE` | The application has successfully booted. | -| `Package::STATUS_FAILED` | The application did not build/boot properly. | \ No newline at end of file +| Status | Description | +|--------------------------------|-----------------------------------------------------------------------------------| +| `Package::STATUS_IDLE` | Before application is built or booted (`Package` instance just instantiated). | +| `Package::STATUS_INITIALIZING` | Before `Package::build()` started processing modules. | +| `Package::STATUS_INITIALIZED` | After `Package::build()` end processing modules. | +| `Package::STATUS_BOOTING` | Before `Package::boot()` started processing executable modules' "run procedures". | +| `Package::STATUS_BOOTED` | After `Package::boot()` ended processing executable modules' "run procedures". | +| `Package::STATUS_DONE` | The application has successfully completed both processes. | +| `Package::STATUS_FAILED` | The application did not build/boot properly. | \ No newline at end of file diff --git a/src/Package.php b/src/Package.php index 11de8a5..11d5975 100644 --- a/src/Package.php +++ b/src/Package.php @@ -83,7 +83,7 @@ class Package * Action fired when plugin finished its bootstrapping process, all its hooks are added. * Add more modules is not anymore possible at this stage. */ - public const ACTION_READY = 'ready'; + public const ACTION_BOOTED = 'ready'; /** * Action fired when anything went wrong during the "build" procedure. @@ -139,32 +139,32 @@ class Package * */ public const STATUS_IDLE = 2; - public const STATUS_INIT = 3; + public const STATUS_INITIALIZING = 3; public const STATUS_INITIALIZED = 4; public const STATUS_BOOTING = 5; - public const STATUS_READY = 7; + public const STATUS_BOOTED = 7; public const STATUS_DONE = 8; public const STATUS_FAILED = -8; - // Deprecated statuses + // Deprecated flags /** @deprecated */ public const STATUS_MODULES_ADDED = self::STATUS_BOOTING; /** @deprecated */ - public const STATUS_BOOTED = self::STATUS_DONE; + public const ACTION_READY = self::ACTION_BOOTED; // Map of status to package-specific and global hook, both optional (i..e, null). private const STATUSES_ACTIONS_MAP = [ - self::STATUS_INIT => [self::ACTION_INIT, self::ACTION_MODULARITY_INIT], + self::STATUS_INITIALIZING => [self::ACTION_INIT, self::ACTION_MODULARITY_INIT], self::STATUS_INITIALIZED => [self::ACTION_INITIALIZED, null], - self::STATUS_READY => [self::ACTION_READY, null], + self::STATUS_BOOTED => [self::ACTION_BOOTED, null], ]; private const SUCCESS_STATUSES = [ self::STATUS_IDLE => self::STATUS_IDLE, - self::STATUS_INIT => self::STATUS_INIT, + self::STATUS_INITIALIZING => self::STATUS_INITIALIZING, self::STATUS_INITIALIZED => self::STATUS_INITIALIZED, self::STATUS_BOOTING => self::STATUS_BOOTING, - self::STATUS_READY => self::STATUS_READY, + self::STATUS_BOOTED => self::STATUS_BOOTED, self::STATUS_DONE => self::STATUS_DONE, ]; @@ -227,7 +227,7 @@ public function addModule(Module $module): Package try { $reason = sprintf('add module %s', $module->id()); $this->assertStatus(self::STATUS_FAILED, $reason, '!='); - $this->assertStatus(self::STATUS_INIT, $reason, '<='); + $this->assertStatus(self::STATUS_INITIALIZING, $reason, '<='); $registeredServices = $this->addModuleServices( $module, @@ -349,9 +349,9 @@ public function build(): Package // hooking ACTION_INIT OR ACTION_INITIALIZED. $this->assertStatus(self::STATUS_IDLE, 'build package'); - // This will change the status to "INIT" then fire the action that allow external + // This will change the status to "INITIALIZING" then fire the action that allow other // packages to add modules or connect packages. - $this->progress(self::STATUS_INIT); + $this->progress(self::STATUS_INITIALIZING); // This will change the status to "INITIALIZED" then fire an action when it is safe to // access the container, because from this moment on, container is locked from change. @@ -374,7 +374,7 @@ public function boot(Module ...$defaultModules): bool try { // When package is done, nothing should happen to it calling boot again, but we call // false to signal something is off. - if ($this->hasReachedStatus(self::STATUS_DONE)) { + if ($this->statusIs(self::STATUS_DONE)) { return false; } @@ -388,15 +388,15 @@ public function boot(Module ...$defaultModules): bool // This will change status to STATUS_BOOTING "locking" subsequent call to `boot()`, but // no hook is fired here, because at this point we can not do anything more or less than - // what can be done on the ACTION_BUILD hook, so that hook is sufficient. + // what can be done on the ACTION_INITIALIZED hook, so that hook is sufficient. $this->progress(self::STATUS_BOOTING); $this->doExecute(); - // This will change status to STATUS_READY and then fire an action that make it possible - // to hook on a package that has finished its bootstrapping process, so all its + // This will change status to STATUS_BOOTED and then fire an action that make it + // possible to hook on a package that has finished its bootstrapping process, so all its // "executable" modules have been executed. - $this->progress(self::STATUS_READY); + $this->progress(self::STATUS_BOOTED); } catch (\Throwable $throwable) { $this->handleFailure($throwable, self::ACTION_FAILED_BOOT); @@ -473,7 +473,7 @@ private function doBuild(Module ...$defaultModules): void // until the next major is released. To do that, we simulate IDLE status to prevent // `addModule()` from throwing when adding default modules. // But we can do that only if we don't have a compiled container yet. - // If anything hooking ACTION_INITIALIZED called `container()` we have a compiled container + // If anything hooking ACTION_INIT called `container()` we have a compiled container // already, and we can't add modules, so we not going to simulate INIT status, which mean // the `$this->addModule()` call below will throw. $backup = $this->status; diff --git a/tests/unit/PackageTest.php b/tests/unit/PackageTest.php index 68f864f..0d72bd0 100644 --- a/tests/unit/PackageTest.php +++ b/tests/unit/PackageTest.php @@ -30,7 +30,7 @@ public function testBasic(): void static::assertTrue($package->hasReachedStatus(Package::STATUS_IDLE)); static::assertFalse($package->hasReachedStatus(Package::STATUS_INITIALIZED)); static::assertFalse($package->hasReachedStatus(Package::STATUS_BOOTING)); - static::assertFalse($package->hasReachedStatus(Package::STATUS_READY)); + static::assertFalse($package->hasReachedStatus(Package::STATUS_BOOTED)); static::assertFalse($package->hasReachedStatus(Package::STATUS_DONE)); $package->build(); @@ -39,13 +39,13 @@ public function testBasic(): void static::assertTrue($package->hasReachedStatus(Package::STATUS_IDLE)); static::assertTrue($package->hasReachedStatus(Package::STATUS_INITIALIZED)); static::assertFalse($package->hasReachedStatus(Package::STATUS_BOOTING)); - static::assertFalse($package->hasReachedStatus(Package::STATUS_READY)); + static::assertFalse($package->hasReachedStatus(Package::STATUS_BOOTED)); static::assertFalse($package->hasReachedStatus(Package::STATUS_DONE)); - Monkey\Actions\expectDone($package->hookName(Package::ACTION_READY)) + Monkey\Actions\expectDone($package->hookName(Package::ACTION_BOOTED)) ->once() ->whenHappen(static function (Package $package): void { - static::assertTrue($package->statusIs(Package::STATUS_READY)); + static::assertTrue($package->statusIs(Package::STATUS_BOOTED)); }); static::assertTrue($package->boot()); @@ -53,11 +53,11 @@ public function testBasic(): void static::assertTrue($package->hasReachedStatus(Package::STATUS_IDLE)); static::assertTrue($package->hasReachedStatus(Package::STATUS_INITIALIZED)); static::assertTrue($package->hasReachedStatus(Package::STATUS_BOOTING)); + static::assertTrue($package->hasReachedStatus(Package::STATUS_BOOTED)); static::assertTrue($package->hasReachedStatus(Package::STATUS_DONE)); + static::assertFalse($package->hasReachedStatus(6)); // check back compat - static::assertTrue($package->hasReachedStatus(Package::STATUS_BOOTED)); static::assertTrue($package->hasReachedStatus(Package::STATUS_MODULES_ADDED)); - static::assertFalse($package->hasReachedStatus(6)); static::assertSame($expectedName, $package->name()); static::assertInstanceOf(Properties::class, $package->properties()); @@ -105,10 +105,10 @@ public static function provideHookNameSuffix(): \Generator $baseHookName . '.' . Package::ACTION_INIT, ]; - yield 'ready' => [ - Package::ACTION_READY, + yield 'booted' => [ + Package::ACTION_BOOTED, $expectedName, - $baseHookName . '.' . Package::ACTION_READY, + $baseHookName . '.' . Package::ACTION_BOOTED, ]; } @@ -583,7 +583,7 @@ static function (string $packageName, int $status) use (&$log): void { ->once() ->whenHappen( static function (Package $package) use (&$log): void { - static::assertTrue($package->statusIs(Package::STATUS_INIT)); + static::assertTrue($package->statusIs(Package::STATUS_INITIALIZING)); $log[] = 1; } ); @@ -593,7 +593,7 @@ static function (Package $package) use (&$log): void { ->whenHappen( static function (string $packageName, Package $package) use (&$log): void { static::assertSame('package_1', $packageName); - static::assertTrue($package->statusIs(Package::STATUS_INIT)); + static::assertTrue($package->statusIs(Package::STATUS_INITIALIZING)); $log[] = 2; } ); @@ -607,11 +607,11 @@ static function (Package $package) use (&$log): void { } ); - Monkey\Actions\expectDone($package->hookName(Package::ACTION_READY)) + Monkey\Actions\expectDone($package->hookName(Package::ACTION_BOOTED)) ->once() ->whenHappen( static function (Package $package) use (&$log): void { - static::assertTrue($package->statusIs(Package::STATUS_READY)); + static::assertTrue($package->statusIs(Package::STATUS_BOOTED)); $log[] = 4; } ); @@ -647,7 +647,7 @@ static function (string $packageName, int $status) use (&$log): void { ->once() ->whenHappen( static function (Package $package) use (&$log): void { - static::assertTrue($package->statusIs(Package::STATUS_INIT)); + static::assertTrue($package->statusIs(Package::STATUS_INITIALIZING)); $log[] = 1; } ); @@ -657,7 +657,7 @@ static function (Package $package) use (&$log): void { ->whenHappen( static function (string $packageName, Package $package) use (&$log): void { static::assertSame('package_1', $packageName); - static::assertTrue($package->statusIs(Package::STATUS_INIT)); + static::assertTrue($package->statusIs(Package::STATUS_INITIALIZING)); $log[] = 2; } ); @@ -671,11 +671,11 @@ static function (Package $package) use (&$log): void { } ); - Monkey\Actions\expectDone($package->hookName(Package::ACTION_READY)) + Monkey\Actions\expectDone($package->hookName(Package::ACTION_BOOTED)) ->once() ->whenHappen( static function (Package $package) use (&$log): void { - static::assertTrue($package->statusIs(Package::STATUS_READY)); + static::assertTrue($package->statusIs(Package::STATUS_BOOTED)); $log[] = 4; } ); @@ -711,7 +711,7 @@ static function (string $packageName, int $status) use (&$log): void { ->once() ->whenHappen( static function (Package $package) use (&$log): void { - static::assertTrue($package->statusIs(Package::STATUS_INIT)); + static::assertTrue($package->statusIs(Package::STATUS_INITIALIZING)); $log[] = 1; } ); @@ -721,7 +721,7 @@ static function (Package $package) use (&$log): void { ->whenHappen( static function (string $packageName, Package $package) use (&$log): void { static::assertSame('package_1', $packageName); - static::assertTrue($package->statusIs(Package::STATUS_INIT)); + static::assertTrue($package->statusIs(Package::STATUS_INITIALIZING)); $log[] = 2; } ); @@ -735,7 +735,7 @@ static function (Package $package) use (&$log): void { } ); - Monkey\Actions\expectDone($package->hookName(Package::ACTION_READY)) + Monkey\Actions\expectDone($package->hookName(Package::ACTION_BOOTED)) ->never(); $package->connect(Package::new($this->stubProperties('connected', true))); @@ -757,7 +757,7 @@ public function testItFailsWhenCallingBootFromInitHookDebugOff(): void Monkey\Actions\expectDone(Package::ACTION_MODULARITY_INIT)->never(); Monkey\Actions\expectDone($package->hookName(Package::ACTION_INITIALIZED))->never(); - Monkey\Actions\expectDone($package->hookName(Package::ACTION_READY))->never(); + Monkey\Actions\expectDone($package->hookName(Package::ACTION_BOOTED))->never(); Monkey\Actions\expectDone($package->hookName(Package::ACTION_FAILED_BUILD))->once(); Monkey\Actions\expectDone($package->hookName(Package::ACTION_FAILED_BOOT))->never(); @@ -777,7 +777,7 @@ public function testItFailsWhenCallingBootFromInitHookDebugOn(): void Monkey\Actions\expectDone(Package::ACTION_MODULARITY_INIT)->never(); Monkey\Actions\expectDone($package->hookName(Package::ACTION_INITIALIZED))->never(); - Monkey\Actions\expectDone($package->hookName(Package::ACTION_READY))->never(); + Monkey\Actions\expectDone($package->hookName(Package::ACTION_BOOTED))->never(); Monkey\Actions\expectDone($package->hookName(Package::ACTION_FAILED_BUILD))->once(); Monkey\Actions\expectDone($package->hookName(Package::ACTION_FAILED_BOOT))->never(); @@ -798,7 +798,7 @@ public function testItFailsWhenCallingBootFromInitializedHook(): void Monkey\Actions\expectDone($package->hookName(Package::ACTION_INIT))->once(); Monkey\Actions\expectDone(Package::ACTION_MODULARITY_INIT)->once(); - Monkey\Actions\expectDone($package->hookName(Package::ACTION_READY))->never(); + Monkey\Actions\expectDone($package->hookName(Package::ACTION_BOOTED))->never(); Monkey\Actions\expectDone($package->hookName(Package::ACTION_FAILED_BUILD))->once(); Monkey\Actions\expectDone($package->hookName(Package::ACTION_FAILED_BOOT))->never(); @@ -813,7 +813,7 @@ public function testItFailsWhenCallingBootFromReadyHook(): void { $package = Package::new($this->stubProperties('test', true)); - Monkey\Actions\expectDone($package->hookName(Package::ACTION_READY)) + Monkey\Actions\expectDone($package->hookName(Package::ACTION_BOOTED)) ->once() ->whenHappen([$package, 'boot']); @@ -840,7 +840,7 @@ public function testItFailsWhenCallingBuildFromInitHook(): void Monkey\Actions\expectDone(Package::ACTION_MODULARITY_INIT)->never(); Monkey\Actions\expectDone($package->hookName(Package::ACTION_INITIALIZED))->never(); - Monkey\Actions\expectDone($package->hookName(Package::ACTION_READY))->never(); + Monkey\Actions\expectDone($package->hookName(Package::ACTION_BOOTED))->never(); Monkey\Actions\expectDone($package->hookName(Package::ACTION_FAILED_BUILD))->once(); Monkey\Actions\expectDone($package->hookName(Package::ACTION_FAILED_BOOT))->never(); @@ -861,7 +861,7 @@ public function testItFailsWhenCallingBuildFromInitializedHook(): void Monkey\Actions\expectDone($package->hookName(Package::ACTION_INIT))->once(); Monkey\Actions\expectDone(Package::ACTION_MODULARITY_INIT)->once(); - Monkey\Actions\expectDone($package->hookName(Package::ACTION_READY))->never(); + Monkey\Actions\expectDone($package->hookName(Package::ACTION_BOOTED))->never(); Monkey\Actions\expectDone($package->hookName(Package::ACTION_FAILED_BUILD))->once(); Monkey\Actions\expectDone($package->hookName(Package::ACTION_FAILED_BOOT))->never(); @@ -876,7 +876,7 @@ public function testItFailsWhenCallingBuildFromReadyHook(): void { $package = Package::new($this->stubProperties('test', true)); - Monkey\Actions\expectDone($package->hookName(Package::ACTION_READY)) + Monkey\Actions\expectDone($package->hookName(Package::ACTION_BOOTED)) ->once() ->whenHappen([$package, 'build']);