Blade Components and Compilation

Purpose and Scope

This document explains the ComponentTagCompiler class and its role in processing Blade components for email templates. The compiler extends Hyperf's component compilation system to provide enhanced slot processing and special handling for email-specific components prefixed with mail::.

For information about how Markdown content is rendered using this compiler, see Markdown Rendering. For details about the email template structure that uses these components, see Email Template Structure.

Overview

The ComponentTagCompiler serves as a bridge between raw Blade template syntax and executable PHP code for email templates. It handles two primary responsibilities:

1. Slot Tag Compilation - Transforms <x-slot> and <x:slot> tags into Blade directives
2. Component Class Resolution - Locates the appropriate class or view for each component reference, with special handling for mail:: prefixed components

The compiler is located at src/Compiler/ComponentTagCompiler.php1-119 and extends Hyperf\ViewEngine\Compiler\ComponentTagCompiler.

Sources: src/Compiler/ComponentTagCompiler.php1-119

Architecture Position

The following diagram shows where the ComponentTagCompiler fits in the email rendering pipeline:

Sources: src/Compiler/ComponentTagCompiler.php1-119

Slot Compilation

Slot Syntax Recognition

The compileSlots() method transforms Blade component slot syntax into executable directives. It recognizes three slot naming patterns:

Pattern	Example	Compiled To
Inline name	<x-slot:footer>	@slot('footer')
Named attribute	<x-slot name="header">	@slot('header')
Bound name	<x-slot :name="$slotName">	@slot($slotName)

The compilation process uses a complex regular expression pattern defined at src/Compiler/ComponentTagCompiler.php20-62 that captures:

• Slot tag opening (<x-slot> or <x:slot>)
• Optional inline name using colon syntax (:footer)
• Optional name= attribute
• Optional :name= bound attribute
• Additional attributes including @class, @style, and {{ $attributes }}
• Proper handling of attribute values (quoted or unquoted)

Sources: src/Compiler/ComponentTagCompiler.php18-79

Slot Name Processing

The compiler applies transformation logic to slot names at src/Compiler/ComponentTagCompiler.php64-76:

Example transformations:

• <x-slot:action-button> → @slot('actionButton')
• <x-slot name="footer"> → @slot('footer')
• <x-slot :name="$variable"> → @slot($variable)

Closing tags </x-slot> and </x:slot> are replaced with @endslot at src/Compiler/ComponentTagCompiler.php78

Sources: src/Compiler/ComponentTagCompiler.php64-79

Component Class Resolution

Resolution Strategy

The componentClass() method at src/Compiler/ComponentTagCompiler.php84-117 implements a multi-stage lookup strategy to resolve component references:

Sources: src/Compiler/ComponentTagCompiler.php84-117

Lookup Stages

The resolution proceeds through the following stages in order:

Stage 1: Alias Lookup

At src/Compiler/ComponentTagCompiler.php88-100 the compiler checks if the component name exists in the $this->aliases array. If found:

• Checks if the alias maps to an existing class
• Checks if the alias maps to an existing view via $viewFactory->exists()
• Throws InvalidArgumentException if neither exists

Stage 2: Class Discovery

At src/Compiler/ComponentTagCompiler.php102-104 attempts to find a class by component name using $this->findClassByComponent() (inherited from parent).

Stage 3: Autoload Guessing

At src/Compiler/ComponentTagCompiler.php106-108 tries to guess a view path from autoload configuration using $this->guessComponentFromAutoload() (inherited from parent).

Stage 4: Mail Component Passthrough

At src/Compiler/ComponentTagCompiler.php110-112 the critical email-specific logic:

if (str_starts_with($component, 'mail::')) {
 return $component;
}

This allows mail::button, mail::panel, mail::message, and other email components to be resolved by the view system without requiring explicit class registration. The view factory will later locate these in the configured view paths.

Stage 5: Error Handling

If all stages fail, throws InvalidArgumentException at src/Compiler/ComponentTagCompiler.php114-116

Sources: src/Compiler/ComponentTagCompiler.php84-117

Mail Component Prefix Handling

Special Treatment for mail:: Components

The passthrough logic for mail:: prefixed components is the key differentiator from the base Hyperf component compiler. This enables email templates to reference standardized components without manual registration:

Component Reference	Resolves To
mail::message	View at mail::message path
mail::button	View at mail::button path
mail::panel	View at mail::panel path
mail::table	View at mail::table path
mail::promotion	View at mail::promotion path
mail::subcopy	View at mail::subcopy path

The actual view files for these components are registered through the Markdown class's view factory configuration, which manages separate component paths for HTML and text rendering modes.

Sources: src/Compiler/ComponentTagCompiler.php110-112

Integration with View Engine

Container Resolution

The compiler integrates with Hyperf's dependency injection container at src/Compiler/ComponentTagCompiler.php86:

$viewFactory = Blade::container()->get(FactoryInterface::class);

This retrieves the FactoryInterface instance, which provides:

• View existence checking via exists()
• View rendering capabilities
• Access to configured view paths

The Blade::container() call uses Hyperf's static facade to access the application container, ensuring proper resolution of the view factory configured for the mail system.

Sources: src/Compiler/ComponentTagCompiler.php84-117

Component Compilation Flow

The complete component compilation process:

Sources: src/Compiler/ComponentTagCompiler.php1-119

Extension Point

The ComponentTagCompiler extends Hyperf\ViewEngine\Compiler\ComponentTagCompiler at src/Compiler/ComponentTagCompiler.php13 inheriting:

• Base component compilation logic
• Component path registration
• Anonymous component support
• Attribute bag handling

The hypervel/mail implementation overrides only:

1. compileSlots() - Enhanced slot processing with attribute support
2. componentClass() - Added mail:: prefix passthrough

This minimal override approach ensures compatibility with Hyperf's view engine while adding email-specific functionality.

Sources: src/Compiler/ComponentTagCompiler.php13

Error Handling

The compiler throws InvalidArgumentException in two scenarios:

Scenario 1: Alias Resolution Failure

At src/Compiler/ComponentTagCompiler.php97-99:

throw new InvalidArgumentException(
 "Unable to locate class or view [{$alias}] for component [{$component}]."
);

Occurs when a registered alias doesn't map to an existing class or view.

Scenario 2: Component Not Found

At src/Compiler/ComponentTagCompiler.php114-116:

throw new InvalidArgumentException(
 "Unable to locate a class or view for component [{$component}]."
);

Occurs when all resolution strategies fail and the component doesn't have the mail:: prefix.

Both exceptions provide clear error messages that include the component name, facilitating debugging of template issues.

Sources: src/Compiler/ComponentTagCompiler.php97-116