DevEx API

src/plugin/class-engine.php

@@ -8,15 +8,21 @@ class Engine {
 
 	public function __construct() {
 		require 'enum-subject-type.php';
+		require 'class-subject.php';
+		require 'class-schema.php';
+
+		require 'class-handlers-registry.php';
+		require 'class-observers-registry.php';
 
-		require 'class-transformersregistry.php';
-		require 'class-post-type-ui.php';
-		require 'class-transformer.php';
 		require 'class-subjects-controller.php';
+
 		require 'class-storage.php';
-		require 'class-schema.php';
+
+		require 'class-post-type-ui.php';
+		require 'class-transformer.php';
+		require 'class-ops.php';
+
 		require 'utils.php';
-		require 'class-subject.php';
 
 		( function () {
 			new Transformer();
@@ -26,6 +32,8 @@ public function __construct() {
 			new Subjects_Controller( self::STORAGE_POST_TYPE );
 
 			new Storage( self::STORAGE_POST_TYPE );
+
+			Ops::init( self::STORAGE_POST_TYPE );
 		} )();
 	}
 }

src/plugin/class-transformersregistry.php → src/plugin/class-handlers-registry.php

@@ -5,7 +5,7 @@
 use Exception;
 use InvalidArgumentException;
 
-class TransformersRegistry {
+class Handlers_Registry {
 	private static string $user_choice_meta_key_prefix = '_data_liberation_chosen_handler_';
 	private static array $handlers                     = array();
 
@@ -90,18 +90,6 @@ public static function handle( SubjectType $type, Subject $subject ): void {
 		}
 	}
 
-	/**
-	 * Remove all handlers for a type
-	 *
-	 * @param SubjectType $type The type to clear handlers for.
-	 * @return void
-	 */
-	public static function clear( SubjectType $type ): void {
-		if ( isset( self::$handlers[ $type->value ] ) ) {
-			unset( self::$handlers[ $type->value ] );
-		}
-	}
-
 	/**
 	 * Set user choice for what transformer to run for a subject type when multiples are registered
 	 *

src/plugin/class-observers-registry.php

@@ -0,0 +1,65 @@
+<?php
+
+namespace DotOrg\TryWordPress;
+
+use Exception;
+use InvalidArgumentException;
+
+class Observers_Registry {
+	private static array $observers = array();
+
+	/**
+	 * Add a observer for a specific subject type
+	 *
+	 * @param SubjectType $type The subject type for which observer should be registered.
+	 * @param array       $identifier Array containing unique slug and description.
+	 * @param callable    $observer The observer function.
+	 * @return void
+	 * @throws InvalidArgumentException If observer is not callable.
+	 */
+	public static function add( SubjectType $type, array $identifier, callable $observer ): void {
+		if ( ! is_callable( $observer ) ) {
+			throw new InvalidArgumentException( 'observer must be callable' );
+		}
+
+		if ( ! isset( $identifier['slug'] ) ) {
+			throw new InvalidArgumentException( 'Identifier slug must be defined' );
+		}
+
+		if ( ! isset( self::$observers[ $type->value ] ) ) {
+			self::$observers[ $type->value ] = array();
+		}
+
+		self::$observers[ $type->value ][ $identifier['slug'] ] = array(
+			'slug'        => $identifier['slug'],
+			'description' => $identifier['description'],
+			'observer'    => $observer,
+		);
+	}
+
+	/**
+	 * Check if observers exist for a type
+	 *
+	 * @param SubjectType $type The subject type to check for.
+	 * @return bool True if observers exist
+	 */
+	public static function has( SubjectType $type ): bool {
+		return isset( self::$observers[ $type->value ] ) && ! empty( self::$observers[ $type->value ] );
+	}
+
+	/**
+	 * Execute all observers for a type
+	 *
+	 * @param SubjectType $type The subject type to handle.
+	 * @param Subject     $subject Data to pass to observers.
+	 * @return void
+	 */
+	public static function observe( SubjectType $type, Subject $subject ): void {
+		if ( ! self::has( $type ) ) {
+			return;
+		}
+		foreach ( self::$observers[ $type->value ] as $registered_observer ) {
+			$registered_observer['observer']( $subject );
+		}
+	}
+}

src/plugin/class-ops.php

@@ -0,0 +1,65 @@
+<?php
+
+namespace DotOrg\TryWordPress;
+
+use WP_Post;
+
+class Ops {
+	private static string $post_type;
+
+	public static function init( string $post_type ): void {
+		static::$post_type = $post_type;
+	}
+
+	/**
+	 * Register your handler for the specified subject type
+	 *
+	 * @param SubjectType $subject_type Type of subject.
+	 * @param array       $identifier Array containing unique slug and description.
+	 * @param callable    $handler Function that would handle the transformation of subject for the specific subject type.
+	 * @return void
+	 */
+	public static function handle( SubjectType $subject_type, array $identifier, callable $handler ): void {
+		Handlers_Registry::add( $subject_type, $identifier, $handler );
+	}
+
+	/**
+	 * Register your handler for the specified subject type to just observe (read-only) data
+	 *
+	 * @param SubjectType $subject_type Type of subject.
+	 * @param array       $identifier Array containing unique slug and description.
+	 * @param callable    $handler Function that would handle the transformation of subject for the specific subject type.
+	 * @return void
+	 */
+	public static function observe( SubjectType $subject_type, array $identifier, callable $handler ): void {
+		Observers_Registry::add( $subject_type, $identifier, $handler );
+	}
+
+	/**
+	 * Loops over all liberated_post posts for the specified subject_type
+	 *
+	 * @TODO: pagination support
+	 *
+	 * @param SubjectType $subject_type Type of subject.
+	 * @return Subject[]
+	 */
+	public static function loop( SubjectType $subject_type ): array {
+		$args  = array(
+			'post_type'      => static::$post_type,
+			'post_status'    => 'publish',
+			'posts_per_page' => -1,
+			// @phpcs:ignore
+			'meta_query'     => array(
+				'key'     => 'subject_type',
+				'value'   => $subject_type->value,
+				'compare' => '=',
+			),
+		);
+		$posts = get_posts( $args );
+
+		return array_map(
+			fn( WP_Post $post ) => Subject::from_post( $post->ID ),
+			$posts
+		);
+	}
+}

src/plugin/class-subjects-controller.php

@@ -292,7 +292,7 @@ public function create_item( $request ): WP_REST_Response|WP_Error {
 		update_post_meta( $item['ID'], 'subject_type', $subject_type->value );
 
 		try {
-			TransformersRegistry::handle( $subject_type, Subject::from_post( $item['ID'] ) );
+			$this->announce_subject( $subject_type, Subject::from_post( $item['ID'] ) );
 		} catch ( Exception $e ) {
 			return new WP_Error( $e->getCode(), $e->getMessage() );
 		}
@@ -322,7 +322,7 @@ public function update_item( $request ): WP_REST_Response|WP_Error {
 		$subject_type = $this->get_subject_type( $request );
 
 		try {
-			TransformersRegistry::handle( $subject_type, Subject::from_post( $item['ID'] ) );
+			$this->announce_subject( $subject_type, Subject::from_post( $item['ID'] ) );
 		} catch ( Exception $e ) {
 			return new WP_Error( $e->getCode(), $e->getMessage() );
 		}
@@ -465,4 +465,16 @@ private function get_subject_type( $request ): SubjectType {
 		preg_match( '/\/subjects\/([^\/]+)/', $request->get_route(), $matches );
 		return SubjectType::tryFrom( $matches[1] );
 	}
+
+	/**
+	 * Announce subject to Observers_Registry & Handlers_Registry
+	 *
+	 * @param SubjectType $subject_type Type of subject to announce.
+	 * @param Subject     $subject Subject instance to announce.
+	 * @throws Exception Handlers_Registry::handle can throw an exception.
+	 */
+	private function announce_subject( SubjectType $subject_type, Subject $subject ): void {
+		Observers_Registry::observe( $subject_type, $subject );
+		Handlers_Registry::handle( $subject_type, $subject );
+	}
 }

src/plugin/class-transformer.php

@@ -7,7 +7,7 @@ class Transformer {
 	public const string META_KEY_LIBERATED_OUTPUT = '_data_liberation_output';
 
 	public function __construct() {
-		TransformersRegistry::add(
+		Ops::handle(
 			SubjectType::BLOGPOST,
 			array(
 				'slug'        => 'try_wordpress',
@@ -19,7 +19,7 @@ public function __construct() {
 			)
 		);
 
-		TransformersRegistry::add(
+		Ops::handle(
 			SubjectType::PAGE,
 			array(
 				'slug'        => 'try_wordpress',