Skip to content

Commit

Permalink
Rename actions and statuses for consistency
Browse files Browse the repository at this point in the history
  • Loading branch information
gmazzap committed Aug 29, 2024
1 parent f53c2cd commit 4f4eeba
Show file tree
Hide file tree
Showing 4 changed files with 59 additions and 59 deletions.
6 changes: 3 additions & 3 deletions docs/Application-flow.md
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand All @@ -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.


Expand Down
22 changes: 11 additions & 11 deletions docs/Package.md
Original file line number Diff line number Diff line change
Expand Up @@ -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.

Expand Down Expand Up @@ -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. |
| 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. |
36 changes: 18 additions & 18 deletions src/Package.php
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand Down Expand Up @@ -139,32 +139,32 @@ class Package
* </code>
*/
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,
];

Expand Down Expand Up @@ -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,
Expand Down Expand Up @@ -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.
Expand All @@ -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;
}

Expand All @@ -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);

Expand Down Expand Up @@ -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;
Expand Down
Loading

0 comments on commit 4f4eeba

Please sign in to comment.