Refactor: Component based PHP rendering

inc/Framework/ComponentLoader.php

@@ -0,0 +1,189 @@
+<?php
+/**
+ * Component loader for resolving and rendering PHP component partials.
+ *
+ * Resolves components from theme or plugin paths with configurable priority.
+ * Components are render-only PHP files that receive data as arguments and output HTML.
+ *
+ * @package rtCamp\Theme\Elementary
+ */
+
+declare( strict_types = 1 );
+
+namespace rtCamp\Theme\Elementary\Framework;
+
+/**
+ * Class ComponentLoader
+ *
+ * @since 1.0.0
+ */
+class ComponentLoader {
+
+	/**
+	 * Render a component by name.
+	 *
+	 * Resolves the component file based on registered paths and priority,
+	 * then includes it with the provided arguments available in scope.
+	 *
+	 * @param string $name    Component name (e.g. 'Button', 'Card').
+	 * @param array  $args    Arguments to pass to the component.
+	 * @param array  $options {
+	 *     Optional. Resolution options.
+	 *
+	 *     @type string $priority Resolution priority: 'theme' or 'plugin'. Default determined by filter.
+	 * }
+	 *
+	 * @return void
+	 */
+	public static function render( string $name, array $args = [], array $options = [] ): void {
+
+		$file = self::get_component_file( $name, $options );
+
+		if ( false === $file ) {
+			return;
+		}
+
+		require $file;
+	}
+
+	/**
+	 * Get the rendered HTML of a component as a string.
+	 *
+	 * Uses output buffering to capture the component output instead of
+	 * sending it directly to the browser.
+	 *
+	 * @param string $name    Component name (e.g. 'Button', 'Card').
+	 * @param array  $args    Arguments to pass to the component.
+	 * @param array  $options {
+	 *     Optional. Resolution options.
+	 *
+	 *     @type string $priority Resolution priority: 'theme' or 'plugin'. Default determined by filter.
+	 * }
+	 *
+	 * @return string Rendered component HTML, or empty string if not found.
+	 */
+	public static function get( string $name, array $args = [], array $options = [] ): string {
+
+		ob_start();
+		self::render( $name, $args, $options );
+
+		return (string) ob_get_clean();
+	}
+
+	/**
+	 * Resolve the component file path.
+	 *
+	 * Checks registered paths in priority order and returns the first match.
+	 * Path format: {source_path}/{Name}/{Name}.php
+	 *
+	 * @param string $name    Component name.
+	 * @param array  $options Resolution options.
+	 *
+	 * @return string|false Full file path on success, false if not found.
+	 */
+	private static function get_component_file( string $name, array $options = [] ): string|false {
+
+		$priority = self::get_priority( $options );
+
+		/**
+		 * Filters the registered component paths.
+		 *
+		 * Each entry is keyed by source type ('theme', 'plugin') and maps
+		 * to a directory path where components are stored.
+		 *
+		 * @since 1.0.0
+		 *
+		 * @param array  $paths    Associative array of source => directory path.
+		 * @param string $name     Component name being resolved.
+		 * @param array  $options  Options passed to render().
+		 */
+		$paths = apply_filters(
+			'elementary_theme_component_paths',
+			[
+				'theme' => ELEMENTARY_THEME_TEMP_DIR . '/src/Components',
+			],
+			$name,
+			$options
+		);
+
+		// Order sources based on priority.
+		$order = self::get_source_order( $priority, $paths );
+
+		foreach ( $order as $source ) {
+
+			if ( empty( $paths[ $source ] ) ) {
+				continue;
+			}
+
+			$file = trailingslashit( $paths[ $source ] ) . $name . '/' . $name . '.php';
+
+			if ( file_exists( $file ) && is_readable( $file ) ) {
+				return $file;
+			}
+		}
+
+		return false;
+	}
+
+	/**
+	 * Get the resolution priority.
+	 *
+	 * @param array $options Options array potentially containing 'priority'.
+	 *
+	 * @return string 'theme' or 'plugin'.
+	 */
+	private static function get_priority( array $options ): string {
+
+		if ( ! empty( $options['priority'] ) && in_array( $options['priority'], [ 'theme', 'plugin' ], true ) ) {
+			return $options['priority'];
+		}
+
+		/**
+		 * Filters the default component resolution priority.
+		 *
+		 * @since 1.0.0
+		 *
+		 * @param string $priority Default priority. Accepts 'theme' or 'plugin'.
+		 */
+		$default = apply_filters( 'elementary_theme_component_default_priority', 'theme' );
+
+		if ( in_array( $default, [ 'theme', 'plugin' ], true ) ) {
+			return $default;
+		}
+
+		return 'theme';
+	}
+
+	/**
+	 * Get the source resolution order based on priority.
+	 *
+	 * @param string $priority 'theme' or 'plugin'.
+	 * @param array  $paths    Registered paths keyed by source.
+	 *
+	 * @return array Ordered list of source keys to check.
+	 */
+	private static function get_source_order( string $priority, array $paths ): array {
+
+		$sources = array_keys( $paths );
+
+		if ( 'plugin' === $priority ) {
+			// Move 'plugin' to front if it exists.
+			$key = array_search( 'plugin', $sources, true );
+
+			if ( false !== $key ) {
+				unset( $sources[ $key ] );
+				array_unshift( $sources, 'plugin' );
+			}
+		} else {
+			// Move 'theme' to front if it exists.
+			$key = array_search( 'theme', $sources, true );
+
+			if ( false !== $key ) {
+				unset( $sources[ $key ] );
+				array_unshift( $sources, 'theme' );
+			}
+		}
+
+		return array_values( $sources );
+	}
+}

inc/Framework/Traits/AssetLoaderTrait.php

@@ -84,9 +84,10 @@
 	 */
 	private function get_asset_meta( string $file, array $deps = [], string|bool|null $ver = false ): array {
 		$normalized_file   = ltrim( str_replace( '\\', '/', $file ), '/' );
-		$asset_meta_target = preg_replace( '/\.[^\/.]+$/', '', $normalized_file ) ?: $normalized_file;
+		$asset_meta_target = preg_replace( '/\.[^\/.]+$/', '', $normalized_file );
+		$asset_meta_target = $asset_meta_target ? $asset_meta_target : $normalized_file;
 		$asset_meta_file   = sprintf( '%s/%s.asset.php', untrailingslashit( ELEMENTARY_THEME_BUILD_DIR ), $asset_meta_target );
 		$asset_meta      = is_readable( $asset_meta_file )
 			? require $asset_meta_file
 			: [
 				'dependencies' => [],

inc/helpers/custom-functions.php

@@ -7,4 +7,44 @@
 
 declare( strict_types = 1 );
 
-// Define custom functions here.
+use rtCamp\Theme\Elementary\Framework\ComponentLoader;
+
+if ( ! function_exists( 'elementary_theme_component' ) ) {
+
+	/**
+	 * Render a component by name.
+	 *
+	 * Global convenience wrapper for ComponentLoader::render().
+	 *
+	 * @since 1.0.0
+	 *
+	 * @param string $name    Component name (e.g. 'Button', 'Card').
+	 * @param array  $args    Arguments to pass to the component.
+	 * @param array  $options Optional. Resolution options. See ComponentLoader::render().
+	 *
+	 * @return void
+	 */
+	function elementary_theme_component( string $name, array $args = [], array $options = [] ): void {
+		ComponentLoader::render( $name, $args, $options );
+	}
+}
+
+if ( ! function_exists( 'elementary_theme_get_component' ) ) {
+
+	/**
+	 * Get the rendered HTML of a component as a string.
+	 *
+	 * Global convenience wrapper for ComponentLoader::get().
+	 *
+	 * @since 1.0.0
+	 *
+	 * @param string $name    Component name (e.g. 'Button', 'Card').
+	 * @param array  $args    Arguments to pass to the component.
+	 * @param array  $options Optional. Resolution options. See ComponentLoader::get().
+	 *
+	 * @return string Rendered component HTML.
+	 */
+	function elementary_theme_get_component( string $name, array $args = [], array $options = [] ): string {
+		return ComponentLoader::get( $name, $args, $options );
+	}
+}

phpcs.xml.dist

@@ -100,6 +100,8 @@
 			</property>
 		</properties>
 		<exclude-pattern>tests/bootstrap.php</exclude-pattern>
+		<!-- Component partials are always require'd inside ComponentLoader::render(), so variables are method-scoped at runtime. -->
+		<exclude-pattern>src/Components/*</exclude-pattern>
 	</rule>
 
 	<rule ref="WordPress-Docs">
@@ -112,6 +114,8 @@
 
 	<rule ref="WordPress.WP.GlobalVariablesOverride.Prohibited">
 		<exclude-pattern>tests/*</exclude-pattern>
+		<!-- Component partials are always require'd inside ComponentLoader::render(), so variables are method-scoped at runtime. -->
+		<exclude-pattern>src/Components/*</exclude-pattern>
 	</rule>
 
 	<!--

src/Components/Button/Button.php

@@ -0,0 +1,43 @@
+<?php
+/**
+ * Button component.
+ *
+ * A render-only component that outputs a button or link element.
+ *
+ * @package rtCamp\Theme\Elementary
+ *
+ * @param array $args {
+ *     Component arguments.
+ *
+ *     @type string $label Button label text. Required.
+ *     @type string $url   URL for link buttons. Optional.
+ *     @type string $class Additional CSS classes. Optional.
+ *     @type string $tag   HTML tag: 'a' or 'button'. Optional. Defaults to 'a' when $url is set, 'button' otherwise.
+ * }
+ */
+
+$label = $args['label'] ?? '';
+$url   = $args['url'] ?? '';
+$class = $args['class'] ?? '';
+$tag   = $args['tag'] ?? ( ! empty( $url ) ? 'a' : 'button' );
+
+if ( empty( $label ) ) {
+	return;
+}
+
+$css_class = trim( 'elementary-button ' . $class );
+
+if ( 'a' === $tag && ! empty( $url ) ) {
+	printf(
+		'<a href="%s" class="%s">%s</a>',
+		esc_url( $url ),
+		esc_attr( $css_class ),
+		esc_html( $label )
+	);
+} else {
+	printf(
+		'<button type="button" class="%s">%s</button>',
+		esc_attr( $css_class ),
+		esc_html( $label )
+	);
+}

src/Components/Card/Card.php

@@ -0,0 +1,63 @@
+<?php
+/**
+ * Card component.
+ *
+ * A render-only component that outputs a card with optional image, title,
+ * description, and action button. Demonstrates component composability
+ * by rendering the Button component internally.
+ *
+ * @package rtCamp\Theme\Elementary
+ *
+ * @param array $args {
+ *     Component arguments.
+ *
+ *     @type string $title       Card title. Required.
+ *     @type string $description Card description text. Optional.
+ *     @type string $image_url   Card image URL. Optional.
+ *     @type string $url         Card link URL. Optional.
+ * }
+ */
+
+use rtCamp\Theme\Elementary\Framework\ComponentLoader;
+
+$title       = $args['title'] ?? '';
+$description = $args['description'] ?? '';
+$image_url   = $args['image_url'] ?? '';
+$url         = $args['url'] ?? '';
+
+if ( empty( $title ) ) {
+	return;
+}
+
+?>
+<div class="elementary-card">
+	<?php if ( ! empty( $image_url ) ) : ?>
+		<div class="elementary-card__image">
+			<img src="<?php echo esc_url( $image_url ); ?>" alt="<?php echo esc_attr( $title ); ?>" />
+		</div>
+	<?php endif; ?>
+
+	<div class="elementary-card__content">
+		<h3 class="elementary-card__title"><?php echo esc_html( $title ); ?></h3>
+
+		<?php if ( ! empty( $description ) ) : ?>
+			<p class="elementary-card__description"><?php echo esc_html( $description ); ?></p>
+		<?php endif; ?>
+
+		<?php if ( ! empty( $url ) ) : ?>
+			<div class="elementary-card__action">
+				<?php
+				ComponentLoader::render(
+					'Button',
+					[
+						'label' => $title,
+						'url'   => $url,
+						'class' => 'elementary-card__button',
+					]
+				);
+				?>
+			</div>
+		<?php endif; ?>
+	</div>
+</div>
+<?php