Html Laravel Package

Getting Started

Minimal Setup

1. Installation:

   composer require aura/html
   

   No additional configuration is required—just autoload via Composer.

2. First Use Case: Escape dynamic content to prevent XSS:

   use Aura\Html\HtmlHelper;
   
   $helper = new HtmlHelper();
   $safeHtml = $helper->escapeHtml('<script>alert("XSS")</script>');
   // Output: &lt;script&gt;alert(&quot;XSS&quot;)&lt;/script&gt;
   

3. Where to Look First:

   • Core Classes: Aura\Html\HtmlHelper (escaping), Aura\Html\FormHelper (form inputs).
   • Documentation: Package README and API docs.
   • Tests: tests/ directory for usage examples.

Implementation Patterns

1. Escaping User Input

• Pattern: Escape all dynamic content (user input, DB values, API responses) before rendering.
• Example:

  $helper = new HtmlHelper();
  $userComment = $request->input('comment');
  echo $helper->escapeHtml($userComment); // Safe for HTML context
  

• Laravel Integration: Bind HtmlHelper to a service container:

  $this->app->singleton(HtmlHelper::class, fn() => new HtmlHelper());
  

2. Form Input Helpers

• Pattern: Generate secure form inputs with built-in escaping.
• Example:

  $formHelper = new FormHelper();
  echo $formHelper->text('username', $user->username, ['class' => 'form-control']);
  // Output: <input type="text" name="username" value="john_doe" class="form-control">
  

• Common Methods:
  • text(), password(), email(), textarea(), select(), etc.
  • hidden(), checkbox(), radio() for hidden/boolean fields.

3. Template Integration

• Pattern: Use as a service in Blade templates or view composers.
• Blade Example:

  // app/Providers/AppServiceProvider.php
  public function boot()
  {
      view()->share('html', new HtmlHelper());
  }
  

  {{ $html->escapeHtml($dynamicData) }}
  

4. Custom Escaping Rules

• Pattern: Extend HtmlHelper for context-specific escaping (e.g., HTML vs. JS vs. URL).
• Example:

  $helper = new HtmlHelper();
  $jsSafe = $helper->escapeJs('alert("Hello")'); // Escapes for JS context
  

5. Batch Processing

• Pattern: Escape arrays/lists of data (e.g., from DB queries).
• Example:

  $comments = Comment::all()->pluck('body');
  $safeComments = array_map([$helper, 'escapeHtml'], $comments);
  

Gotchas and Tips

Pitfalls

1. Double Escaping:

   • If you escape content again after Laravel’s built-in escaping (e.g., in Blade {{ }}), you’ll break HTML.
   • Fix: Use HtmlHelper only for raw dynamic data, not Blade’s auto-escaped output.

2. Context Mismatches:

   • escapeHtml() is for HTML contexts only. Use escapeJs(), escapeUrl(), or escapeAttr() for other contexts.
   • Example:

     // ❌ Wrong (breaks JS)
     $helper->escapeHtml('<script>var x = "test"</script>');
     
     // ✅ Correct
     $helper->escapeJs('<script>var x = "test"</script>');
     

3. Form Helper Quirks:

   • FormHelper escapes values by default. To disable (e.g., for rich text):

     $formHelper->text('content', $post->content, [], false);
     

Debugging Tips

1. Verify Escaping:

   • Use htmlspecialchars() as a sanity check:

     assert($helper->escapeHtml('<b>test</b>') === htmlspecialchars('<b>test</b>'));
     

2. Check for False Positives:

   • If legitimate HTML (e.g., <div>) is escaped, ensure you’re using the correct context method.

3. Performance:

   • HtmlHelper is lightweight, but batch operations (e.g., array_map) on large datasets may benefit from caching escaped values.

Extension Points

1. Custom Escapers:

   • Implement Aura\Html\EscaperInterface for domain-specific escaping (e.g., Markdown to HTML).

2. Form Helper Extensions:

   • Extend Aura\Html\FormHelper to add custom input types (e.g., date(), color()).

3. Integration with Laravel Validators:

   • Combine with Illuminate\Validation to escape sanitized input:

     $validated = $request->validate(['comment' => 'required|string']);
     echo $helper->escapeHtml($validated['comment']);
     

Configuration Quirks

• No Config File: aura/html is zero-config. All behavior is controlled via method calls.
• PHP 8.4+ Requirement: Ensure your Laravel app meets this (use php:8.4 in Dockerfile or .php-version if needed).

Pro Tips

1. Compose Helpers:

   • Combine with other Aura packages (e.g., Aura\Sql for DB-driven forms):

     $formHelper->select('user_id', $user->id, $users->pluck('id', 'name'));
     

2. Laravel Service Provider:

   • Register helpers globally for convenience:

     $this->app->bind(HtmlHelper::class, fn() => new HtmlHelper());
     $this->app->bind(FormHelper::class, fn() => new FormHelper());
     

3. Testing:

   • Mock HtmlHelper in unit tests to verify escaping:

     $helper = $this->createMock(HtmlHelper::class);
     $helper->method('escapeHtml')->willReturn('<b>safe</b>');