Html Common2 Laravel Package

Getting Started

Minimal Steps

1. Installation:

   composer require pear/html_common2
   

   Note: Requires PHP 5.3+ (conflicts with Laravel 8+). Use only in legacy projects or PHP 5.6+ environments.

2. Basic Usage:

   require_once 'HTML/Common2.php';
   $html = new HTML_Common2();
   $html->setAttribute('class', 'btn btn-primary');
   $html->setAttribute('data-toggle', 'modal');
   echo $html->parseAttributes(); // Output: class="btn btn-primary" data-toggle="modal"
   

3. First Use Case:

   • Dynamic HTML Generation: Use in a Blade template or service to generate consistent HTML attributes for forms, buttons, or dynamic elements.
   • Example:

     // In a Laravel service
     public function generateButtonAttributes($isPrimary = true) {
         $html = new HTML_Common2();
         $html->setAttribute('class', 'btn' . ($isPrimary ? ' btn-primary' : ''));
         $html->setAttribute('role', 'button');
         return $html->parseAttributes();
     }
     

4. Where to Look First:

   • PEAR Documentation for method references.
   • tests/ directory in the package for usage examples.
   • Focus on setAttribute(), parseAttributes(), and mergeAttributes() for core functionality.

Implementation Patterns

Usage Patterns

1. Attribute Management:

   • Setting Attributes:

     $html = new HTML_Common2();
     $html->setAttribute('id', 'user-profile');
     $html->setAttribute('class', 'profile-card');
     

   • Merging Attributes:

     $html->mergeAttributes(['data-user-id' => 123, 'aria-hidden' => 'true']);
     

   • Removing Attributes:

     $html->removeAttribute('aria-hidden');
     

2. CSS Class Handling:

   • Add/Remove Classes:

     $html->addClass('active');
     $html->removeClass('disabled');
     

   • Toggle Classes:

     if ($isActive) {
         $html->addClass('active');
     }
     

3. Document-Wide Options:

   • Set Charset/Indentation:

     $html->setDocumentOption('charset', 'UTF-8');
     $html->setDocumentOption('indent', '    ');
     $html->setDocumentOption('linebreak', "\n");
     

   • Generate Indented HTML:

     $html->setDocumentOption('indent', '  ');
     $html->setDocumentOption('linebreak', "\n");
     echo $html->parseAttributes(); // Output with indentation
     

4. HTML Comments:

   • Add Comments:

     $html->addComment('This is a button');
     echo $html->parseAttributes(); // Output: <!-- This is a button -->
     

Workflows

1. Form Builder Integration:

   • Use HTML_Common2 as a base for custom form field generators.
   • Example:

     class FormField {
         protected $html;
     
         public function __construct() {
             $this->html = new HTML_Common2();
         }
     
         public function setType($type) {
             $this->html->setAttribute('type', $type);
         }
     
         public function getAttributes() {
             return $this->html->parseAttributes();
         }
     }
     

2. Dynamic Template Rendering:

   • Integrate with Blade templates via a custom directive or helper.
   • Example Blade Helper:

     // app/Helpers/html_helper.php
     if (!function_exists('html_attributes')) {
         function html_attributes(array $attributes) {
             $html = new HTML_Common2();
             $html->mergeAttributes($attributes);
             return $html->parseAttributes();
         }
     }
     

   • Usage in Blade:

     <button {{ html_attributes(['class' => 'btn btn-success', 'data-id' => $user->id]) }}>
         Save
     </button>
     

3. Legacy PEAR Migration:

   • Replace direct PEAR calls (e.g., HTML_QuickForm2) with HTML_Common2 for attribute handling.
   • Example:

     // Old PEAR way
     $form->addElement('text', 'username', ['class' => 'form-control']);
     
     // New way with HTML_Common2
     $html = new HTML_Common2();
     $html->setAttribute('class', 'form-control');
     $form->addElement('text', 'username', $html->parseAttributes());
     

Integration Tips

1. Laravel Service Provider:

   • Bind HTML_Common2 to the Laravel container for dependency injection.
   • Example:

     // app/Providers/AppServiceProvider.php
     public function register() {
         $this->app->singleton('html.common', function () {
             return new \HTML_Common2();
         });
     }
     

   • Usage in Controllers:

     public function __construct(\HTML_Common2 $htmlCommon) {
         $this->htmlCommon = $htmlCommon;
     }
     

2. Caching Attributes:

   • Cache parsed attributes in a service to avoid reprocessing.
   • Example:

     public function getCachedAttributes($key, $attributes) {
         return Cache::remember("html.{$key}", 60, function () use ($attributes) {
             $html = new HTML_Common2();
             $html->mergeAttributes($attributes);
             return $html->parseAttributes();
         });
     }
     

3. Testing:

   • Mock HTML_Common2 in PHPUnit tests.
   • Example:

     $mockHtml = $this->createMock(\HTML_Common2::class);
     $mockHtml->method('parseAttributes')->willReturn('class="test"');
     $this->app->instance(\HTML_Common2::class, $mockHtml);
     

Gotchas and Tips

Pitfalls

1. PHP Version Conflict:

   • Issue: Requires PHP 5.3+, but Laravel 8+ requires PHP 8.0+.
   • Fix: Use only in legacy projects or PHP 5.6+ environments. For Laravel 8+, consider alternatives like illuminate/html.

2. PEAR Autoloading:

   • Issue: PEAR’s autoloader conflicts with Composer’s. require_once 'HTML/Common2.php' may fail.
   • Fix: Use Composer’s autoloading:

     $loader = require __DIR__.'/vendor/autoload.php';
     $html = new \HTML_Common2();
     

3. No PSR Compliance:

   • Issue: No PSR-4 autoloading or PSR-12 coding standards.
   • Fix: Manually wrap the class in a PSR-compliant facade or service.

4. Deprecated Methods:

   • Issue: Some methods may be deprecated or undocumented.
   • Fix: Check the PEAR documentation for method signatures and deprecations.

5. No Modern PHP Features:

   • Issue: Lacks typed properties, attributes, or PHP 8+ features.
   • Fix: Use only for legacy codebases. For new projects, prefer modern alternatives.

6. Global State:

   • Issue: Document-wide options (e.g., charset) are global and may affect unintended parts of the application.
   • Fix: Create a new instance of HTML_Common2 for each independent HTML generation task.

Debugging

1. Attribute Parsing Issues:

   • Symptom: parseAttributes() outputs unexpected results.
   • Debug:

     $html = new HTML_Common2();
     $html->setAttribute('class', 'btn btn-primary');
     $html->setAttribute('data-toggle', 'modal');
     var_dump($html->getAttributes()); // Inspect raw attributes
     echo $html->parseAttributes();    // Inspect parsed output
     

2. Class Merging Problems:

   • Symptom: Classes are not merging correctly (e.g., class="btn btn-primary" becomes class="btn-primary").
   • Debug:

     $html = new HTML_Common2();
     $html->setAttribute('class', 'btn');
     $html->addClass('btn-primary');
     var_dump($html->getAttribute('class')); // Should output: 'btn btn-primary'
     

3. Indentation Issues:

   • Symptom: Generated HTML is not indented as expected.
   • Debug:

     $html = new HTML_Common2();
     $html->setDocumentOption('indent', '  ');
     $html->setDocumentOption('linebreak', "\n");
     $html->setAttribute('div', ['class' => 'container']);
     echo