Progress events and progress bar support

[adamziel]

Description

Exposes details about the progress of the Blueprint execution:

CleanShot.2024-03-01.at.14.14.57.mp4

Implementation

The Engine class no longer exposes a single run() method. Instead, the flow is split into two stages: 1. Parsing&compiling, 2. Running:

$compiledBlueprint = $engine->parseAndCompile( $json );
// Now we can register any progress listeners and subscribers
$compiledBlueprint->progressTracker->events->addSubscriber( $progressSubscriber );
$result = $engine->run( $compiledBlueprint );

The CompiledBlueprint object exposes two progress trackers:

1. progressTracker with the joint progress information about steps and resources
2. stepsProgressStage with information only about the Blueprint steps – Playground will use that one as it will start pre-fetching any URL-based resources before PHP is even loaded.

The progressTracker->event->addSubscriber method accepts an EventSubscriberInterface $progressSubscriber argument that can subscribe to "progress" and "done" events. This enables implementing custom progress reporters, like the one showcased in the video above:

class CLIProgressBarProgressReporter {
	public static function getSubscribedEvents() {
		return [
			ProgressEvent::class => 'onProgress',
			DoneEvent::class     => 'onDone',
		];
	}

	// ...initialize $this->progress_bar in the constructor...

	public function onProgress( ProgressEvent $event ) {
		$this->progress_bar->setMessage( $event->caption );
		$this->progress_bar->setProgress( (int) $event->progress );
	}

	public function onDone( DoneEvent $event ) {
		$this->progress_bar->finish();
	}
}

Related resources

• Related Playground PR: PHP Blueprints: Display progress wordpress-playground#1077

Follow-up work

• Define the home for generic progress reporters. My current thinking is that the Blueprint package will not actually ship any environment-specific progress reporters, as they would get bundled with blueprints.phar and bring CLI-specific libraries into the library that's supposed to be lightweight and environment-agnostic. Instead, exploring environment-specific packages like Blueprints/CLI or Blueprints/Playground might make more sense. Or perhaps Playground OR each runtime should even ship its own PHP bindings in its own repo? That's TBD.

Testing instructions

Run rm -rf new-wp/*; php blueprint_compiling.php and confirm the entire Blueprint gets executed.