Html Builders Laravel Package

Getting Started

Minimal Setup

1. Installation:

   composer require apie/html-builders
   

   Ensure your composer.json meets the PHP 8.3+ requirement and includes apie/common and apie/core (auto-resolved via self.version).

2. First Use Case: Generate a simple HTML element (e.g., a button) in a Laravel Blade template or PHP file:

   use Apie\HtmlBuilders\HtmlBuilder;
   
   $button = HtmlBuilder::button()
       ->withText('Click Me')
       ->withClass('btn-primary')
       ->build();
   
   echo $button; // Outputs: <button class="btn-primary">Click Me</button>
   

3. Key Entry Points:

   • HtmlBuilder facade/class: Central class for constructing HTML elements.
   • Method chaining: Use fluent methods like withClass(), withId(), or withAttributes().
   • Build methods: Call build() to render the final HTML string.

Implementation Patterns

Core Workflows

1. Blade Integration: Register the facade in config/app.php under aliases:

   'HtmlBuilders' => Apie\HtmlBuilders\Facades\HtmlBuilder::class,
   

   Use in Blade templates:

   @HtmlBuilders::div()
       ->withClass('container')
       ->withChildren(
           HtmlBuilders::h1()->withText('Welcome')
       )
       ->build()
   

2. Dynamic Element Generation: Loop through data to generate repeated HTML structures:

   $items = ['Item 1', 'Item 2'];
   $list = HtmlBuilder::ul()
       ->withChildren(
           collect($items)->map(fn($item) =>
               HtmlBuilder::li()->withText($item)
           )
       )
       ->build();
   

3. Form Handling: Build forms with validation-aware attributes:

   $form = HtmlBuilder::form()
       ->withAction('/submit')
       ->withMethod('POST')
       ->withChildren(
           HtmlBuilder::input()
               ->withName('email')
               ->withType('email')
               ->withClass('form-control')
       )
       ->build();
   

4. Component-Based Patterns: Create reusable HTML components as classes:

   class CardBuilder {
       public static function build(array $data) {
           return HtmlBuilder::div()
               ->withClass('card')
               ->withChildren(
                   HtmlBuilder::h3()->withText($data['title']),
                   HtmlBuilder::p()->withText($data['content'])
               );
       }
   }
   

5. Integration with Laravel Collectives: Combine with HTML facade for hybrid approaches:

   use Collective\Html\Html as CollectiveHtml;
   
   $element = HtmlBuilder::div()
       ->withChildren(
           CollectiveHtml::link('Home', '/')
       )
       ->build();
   

Gotchas and Tips

Pitfalls

1. Monorepo Dependency:

   • The package is part of a monorepo (apie-lib-monorepo). Ensure all apie/* packages are updated in sync to avoid version mismatches.
   • Fix: Use self.version in composer.json or pin versions explicitly.

2. Lack of Official Docs:

   • No public API documentation exists. Rely on method introspection (e.g., php artisan tinker):

     \Apie\HtmlBuilders\HtmlBuilder::class->getMethods();
     

   • Workaround: Study the source code or use IDE autocompletion.

3. PHP 8.3+ Requirement:

   • Features like named arguments or attributes may not work in older PHP versions.
   • Tip: Use php -v to verify compatibility before upgrading.

4. Attribute Handling:

   • Custom attributes (e.g., data-*) require explicit chaining:

     HtmlBuilder::div()->withAttribute('data-custom', 'value');
     

   • Gotcha: No shortcut for bulk attributes (e.g., withAttributes(['data-*' => [...]]) is unsupported).

5. Child Elements:

   • Use withChildren() for nested elements, but ensure proper closure syntax:

     // Correct:
     HtmlBuilder::div()->withChildren(fn($div) =>
         $div->withText('Nested')
     );
     

   • Error: Passing raw strings instead of closures or HtmlBuilder instances may break rendering.

6. UUID Integration:

   • The package requires ramsey/uuid. If generating UUIDs for IDs:

     use Ramsey\Uuid\Uuid;
     
     HtmlBuilder::div()->withId(Uuid::uuid4()->toString());
     

Debugging Tips

1. Inspect Built HTML: Use dd() or dump() to debug intermediate states:

   $element = HtmlBuilder::div()->withClass('debug');
   dd($element->build()); // Inspect raw HTML
   

2. Check for Deprecated Methods: The package may evolve rapidly. Monitor the monorepo issues for breaking changes.

3. Fallback to Raw HTML: For unsupported elements, fall back to Laravel’s e() or Html::entityEncode():

   {!! Html::entityEncode('<div>Raw HTML</div>') !!}
   

Extension Points

1. Custom Builders: Extend HtmlBuilder for domain-specific elements:

   class ApiButtonBuilder extends HtmlBuilder {
       public function withApiEndpoint(string $endpoint) {
           return $this->withAttribute('data-endpoint', $endpoint);
       }
   }
   

2. Service Provider: Bind custom builders in a service provider:

   $this->app->bind('apie.button', function() {
       return new ApiButtonBuilder();
   });
   

3. Testing: Use phpunit to test builders in isolation:

   public function testButtonBuilder() {
       $button = HtmlBuilder::button()->withText('Test')->build();
       $this->assertStringContainsString('button', $button);
   }
   

4. Laravel Mix/Webpack: Process HTML strings with PostCSS or other tools if needed:

   // webpack.mix.js
   mix.postCss('resources/css/app.css', 'public/css', [
       require('postcss-html')()
   ]);