Description:
This task aims to explore and investigate the implementation of the fluent builder pattern in Codex PHP, focusing on balancing flexibility, clarity, and best practices for generating markup.

Background

As discussed in T373708, there are several considerations when implementing the fluent builder pattern in Codex PHP. These considerations include:

• Separating object construction (via build()) from rendering (via getHtml() or render()).
• Combining these steps into a simpler method chain for convenience, potentially merging build() and render().
• Evaluating the use of implicit __toString() methods for output versus explicit method calls for clarity and maintainability.

The focus of this SPIKE is to determine the most efficient and developer-friendly way to implement the builder pattern, ensuring that the final API is clean, maintainable, and easy for PHP developers to use.

Goal

The goal of this SPIKE task is to evaluate different approaches to the builder pattern in Codex PHP. This will inform a final decision on the best approach to take for a clean and maintainable API that is user-friendly for PHP developers.

Investigation Areas

1. Builder Approaches to Evaluate:

• Approach 1: Keep build() and getHtml() separate, where build() constructs the immutable object and getHtml() returns its rendered output.

$infoChip = $codex->InfoChip()->setText( 'Info Chip' )->build()->getHtml(); // `getHtml()` can be renamed to any other descriptive method name.

• Approach 2: Introduce a combined render() method that both constructs the immutable object and returns its rendered output.

$infoChip = $codex->InfoChip()->setText( 'Info Chip' )->render();

• Approach 3: Introduce a combined build() method that both constructs the immutable object and returns its rendered output.

$infoChip = $codex->InfoChip()->setText( 'Info Chip' )->build();

• Approach 4: Introduce a combined getHtml() method that both constructs the immutable object and returns its rendered output.

$infoChip = $codex->InfoChip()->setText( 'Info Chip' )->getHtml();

• Approach 5: Use __toString() to implicitly return the HTML when constructing simpler objects like InfoChip.

$infoChip = $codex->InfoChip()->setText( 'Info Chip' );  // `__toString()` will implicitly return the HTML.

2. Usability and Flexibility:
   • Compare the flexibility of separating object construction and rendering versus streamlining the process into a single method call.

Deliverables

• An analysis of the different approaches based on ease of use for PHP developers.
• Create an ADR to document the decision and reasoning behind the chosen approach.

Acceptance criteria

• A clear recommendation on the best approach for implementing the fluent builder pattern in Codex PHP.
• Documentation of the reasons for the chosen approach, with a focus on PHP developer experience and code maintainability.

Deadline:

This task must be completed within one week, if acceptable.