Html5Shiv Laravel Package

Getting Started

Minimal Steps

1. Installation:

   composer require afarkas/html5shiv
   

   Add the script to your resources/views/layouts/app.blade.php (or equivalent) via:

   <script src="{{ asset('vendor/afarkas/html5shiv/dist/html5shiv.min.js') }}"></script>
   

2. Basic Usage: Place the script before your closing </body> tag. No additional configuration is needed for basic HTML5 shiv functionality.

3. First Use Case: Test with legacy IE (8-9) by using HTML5 semantic elements (<header>, <section>, <footer>, etc.) in your Blade templates. Verify rendering via browser dev tools or tools like BrowserStack.

Implementation Patterns

Workflows

1. Conditional Loading: Use Laravel's @stack directives to load the script only for legacy browsers:

   @if (Request::isMobile() || Request::userAgent() === 'MSIE')
       <script src="{{ asset('vendor/afarkas/html5shiv/dist/html5shiv.min.js') }}"></script>
   @endif
   

   Tip: Use a package like jenssegers/agent for robust user-agent detection.

2. Asset Optimization: Include the script in your Laravel Mix/Webpack build for minification/bundling:

   // webpack.mix.js
   mix.js('resources/js/app.js', 'public/js')
      .copy('node_modules/afarkas/html5shiv/dist/html5shiv.min.js', 'public/vendor/html5shiv/');
   

3. Blade Directives: Create a custom Blade directive for reusable script injection:

   // AppServiceProvider.php
   Blade::directive('html5shiv', function () {
       return '<script src="{{ asset("vendor/html5shiv/html5shiv.min.js") }}"></script>';
   });
   

   Usage:

   @html5shiv
   

Integration Tips

• Polyfills: Combine with other polyfills (e.g., classList.js) for broader IE support.
• Modernizr: If using Modernizr, ensure html5shiv is loaded before Modernizr’s script.
• Laravel Mix: Exclude the script from versioning if using cache-busting (e.g., mix.copy() without hashing).

Gotchas and Tips

Pitfalls

1. IE-Specific Quirks:

   • IE8: May require additional CSS resets (e.g., display: block for <header>).
   • IE9: Works but may need shiv for older document modes (force IE9 mode via <meta http-equiv="X-UA-Compatible" content="IE=9">).

2. Asset Paths:

   • Hardcoding paths (e.g., /vendor/...) breaks when deploying to subdirectories. Use Laravel’s asset() helper or environment-aware paths.

3. Deprecation:

   • The package is unmaintained (last release: 2015). Avoid in new projects; use autoprefixer + normalized CSS for modern builds. For legacy projects, pair with a CDN fallback:

     <script src="//cdn.jsdelivr.net/html5shiv/3.7.3/html5shiv.min.js"></script>
     

Debugging

• Console Errors: Check for SCRIPT1028 (cross-domain issues) if loading via CDN. Use absolute URLs or local paths.
• Rendering Issues: Test with IE’s F12 Developer Tools to inspect element styles.

Extension Points

1. Custom Builds: Modify the source (e.g., html5shiv.js) to include/exclude specific elements or add debug logs.

2. Server-Side Detection: Use Laravel middleware to inject the script dynamically:

   // app/Http/Middleware/InjectHtml5Shiv.php
   public function handle($request, Closure $next) {
       if ($request->isLegacyBrowser()) {
           $response = $next($request);
           $response->getContent();
           $response->setContent(
               str_replace('</body>', '<script src="/vendor/html5shiv/html5shiv.min.js"></script></body>', $response->getContent())
           );
           return $response;
       }
       return $next($request);
   }
   

3. Fallback for Critical Path: Inline the script in Blade for above-the-fold content:

   @if (Request::isLegacyBrowser())
       <script>
           document.createElement('section');
           // ... (full html5shiv code)
       </script>
   @endif