Html Builder Laravel Package

Getting Started

Minimal Setup

1. Installation:

   composer require becklyn/html-builder
   

   No configuration required—just autoload via Composer.

2. First Use Case: Generate a basic HTML string:

   use Becklyn\HtmlBuilder\Html;
   
   $html = Html::tag('div', 'Hello, World!');
   echo $html; // Outputs: <div>Hello, World!</div>
   

3. Key Entry Points:

   • Html::tag() – Core method for creating HTML elements.
   • Html::attr() – Helper for attributes (e.g., Html::attr('class', 'btn')).
   • Html::raw() – Escape HTML safely (e.g., Html::raw('<b>bold</b>')).

Implementation Patterns

Common Workflows

1. Dynamic Element Creation:

   $user = User::find(1);
   $avatar = Html::tag('img', '', [
       'src' => $user->avatar_url,
       'alt' => $user->name,
       'class' => 'avatar',
   ]);
   

2. Nested Structures:

   $card = Html::tag('div', [
       Html::tag('h3', 'Title'),
       Html::tag('p', 'Content'),
   ], ['class' => 'card']);
   

3. Reusable Components:

   function button(string $text, array $attrs = []): string {
       return Html::tag('button', $text, $attrs);
   }
   // Usage: button('Submit', ['class' => 'btn-primary'])
   

4. Integration with Blade:

   @php
       $alert = Html::tag('div', 'Warning!', ['class' => 'alert']);
   @endphp
   {!! $alert !!}
   

Performance Tips

• Cache Complex HTML: Store generated HTML in a variable or view data to avoid reprocessing.
• Batch Attributes: Use Html::attr() for dynamic attributes (e.g., in loops):

  $items = collect([1, 2, 3]);
  $list = $items->map(fn($id) => Html::tag('li', '', [
      'data-id' => $id,
  ]))->implode('');
  

Gotchas and Tips

Pitfalls

1. XSS Risks:

   • Issue: Html::tag() escapes content by default. Use Html::raw() only for trusted HTML.
   • Fix: Sanitize user input before passing to Html::raw() (e.g., with Str::of()->markdown()).

2. Attribute Quoting:

   • Issue: Attributes with special characters (e.g., class="btn btn--primary") may break.
   • Fix: Use Html::attr() for dynamic attributes or manually escape:

     Html::tag('div', '', ['class' => 'btn btn--"primary"']);
     

3. Self-Closing Tags:

   • Issue: <img /> vs <img> syntax may cause rendering issues.
   • Fix: Explicitly close tags or use Html::tag('img', '', [], true) (if supported).

Debugging

• Inspect Output: Use dd($html) to verify generated markup.
• Check for Whitespace: Html::tag() trims content by default. Use Html::raw() for pre-formatted strings.

Extension Points

1. Custom Tag Helpers:

   Html::macro('link', function(string $text, string $url, array $attrs = []) {
       return Html::tag('a', $text, array_merge($attrs, ['href' => $url]));
   });
   // Usage: Html::link('Click', '/home')
   

2. Override Default Behavior: Modify the Html facade binding in AppServiceProvider:

   Html::macro('customTag', function() { ... });
   

3. Integration with Laravel Collectives: Combine with HTML facade for Blade compatibility:

   use Collective\Html\Html as CollectiveHtml;
   CollectiveHtml::macro('becklynTag', function($tag, $content = null) {
       return app(\Becklyn\HtmlBuilder\Html::class)->tag($tag, $content);
   });