Includelibrary Bundle Laravel Package

Getting Started

Minimal Setup

1. Install via Composer (if not archived, verify compatibility with your Laravel version):

   composer require c975l/includelibrary-bundle
   

   Note: Since the bundle is archived, ensure no breaking changes exist in your Laravel version (e.g., Symfony 4+ compatibility).

2. Register the Bundle (Laravel 5.x/6.x): Add to config/app.php under providers:

   C975L\IncludeLibraryBundle\IncludeLibraryBundle::class,
   

3. Publish Config (if needed):

   php artisan vendor:publish --provider="C975L\IncludeLibraryBundle\IncludeLibraryBundle" --tag=config
   

   Check config/include_library.php for default settings (e.g., CDN paths, fallbacks).

4. First Use Case: Replace hardcoded CDN links in a Blade template (e.g., resources/views/layouts/app.blade.php):

   {{ inc_lib('bootstrap', 'css', '4.6.0') }}
   {{ inc_lib('bootstrap', 'js', '4.6.0') }}
   {{ inc_lib('google-font', 'family', 'Roboto:400,700') }}
   

Implementation Patterns

Core Workflows

1. Library Inclusion:

   • Syntax: {{ inc_lib('library', 'type', 'version') }}
     • library: bootstrap, jquery, font-awesome, etc. (see supported libraries).
     • type: css, js, or family (for Google Fonts).
     • version: Specific version (e.g., 3.3.7) or wildcard * (uses latest).
   • Example:

     <!-- jQuery + Popper.js (Bootstrap 4 dependency) -->
     {{ inc_lib('jquery', 'js', '3.5.1') }}
     {{ inc_lib('popper', 'js', '1.16.1') }}
     {{ inc_lib('bootstrap', 'css', '4.6.0') }}
     

2. Google Fonts:

   • Use family type with comma-separated font strings:

     {{ inc_lib('google-font', 'family', 'Open+Sans:400,700|Roboto:italic,500') }}
     

3. Local Fallbacks:

   • Configure config/include_library.php to use local copies if CDN fails:

     'fallback_paths' => [
         'bootstrap' => 'vendor/bootstrap/dist/',
     ],
     

4. Dynamic Versioning:

   • Fetch latest version via API (if supported) or hardcode in config:

     'versions' => [
         'bootstrap' => '4.6.0', // Override default
     ],
     

Integration Tips

• Asset Optimization: Combine with Laravel Mix/Webpack to bundle JS/CSS locally for production. Example: Exclude inc_lib outputs from Mix processing by using unique class names:

  {{ inc_lib('bootstrap', 'css', '4.6.0', ['class' => 'no-mix-process']) }}
  

• Twig Compatibility: If using Twig, register the helper in app/Twig/Extensions/IncludeLibraryExtension.php:

  public function getFunctions()
  {
      return [
          new \Twig\TwigFunction('inc_lib', [$this, 'includeLibrary']),
      ];
  }
  

• Environment-Specific Libraries: Use Blade directives to conditionally load libraries:

  @if(config('app.env') === 'production')
      {{ inc_lib('bootstrap', 'css', '4.6.0') }}
  @else
      {{ inc_lib('bootstrap', 'css', '*') }} <!-- Latest for dev -->
  @endif
  

Gotchas and Tips

Pitfalls

1. Archived Status:

   • No active maintenance; test thoroughly with your Laravel/Symfony version.
   • Mitigation: Fork the repo or create a wrapper package for updates.

2. SRI (Subresource Integrity) Issues:

   • Some libraries lack SRI hashes in the bundle’s database. If a hash fails, the asset may block rendering.
   • Debugging: Check browser console for Failed to find a valid digest errors. Override hashes in config:

     'sri_overrides' => [
         'bootstrap' => [
             'css' => 'sha384-...', // Manually add correct hash
         ],
     ],
     

3. Version Wildcards (*):

   • May pull unstable versions. Avoid in production unless explicitly tested.
   • Tip: Pin versions in config/include_library.php for critical projects.

4. Google Fonts Caching:

   • Google Fonts may not load if the family string exceeds URL length limits (~2000 chars).
   • Workaround: Split into multiple inc_lib calls or use a subset of weights/styles.

5. Laravel Mix Conflicts:

   • If using Mix, ensure inc_lib outputs don’t interfere with asset hashing. Use unique filenames:

     // config/include_library.php
     'asset_options' => [
         'bootstrap_css' => ['attributes' => ['id' => 'bootstrap-css']],
     ],
     

Debugging

• Check Loaded Libraries: Enable debug mode in config/include_library.php:

  'debug' => true,
  

  Outputs a list of included libraries to the footer.

• Verify CDN Availability: Test CDN URLs manually (e.g., https://maxcdn.bootstrapcdn.com/bootstrap/4.6.0/css/bootstrap.min.css) before blaming the bundle.

• Clear Config Cache: After modifying config/include_library.php, run:

  php artisan config:clear
  

Extension Points

1. Add Custom Libraries: Extend the bundle by creating a service provider to register new libraries:

   // app/Providers/IncludeLibraryServiceProvider.php
   use C975L\IncludeLibraryBundle\Manager\LibraryManager;
   
   public function register()
   {
       $this->app->make(LibraryManager::class)->addLibrary([
           'name' => 'custom-lib',
           'css' => 'https://cdn.example.com/{version}/custom.css',
           'js' => 'https://cdn.example.com/{version}/custom.js',
       ]);
   }
   

2. Override Default Templates: Publish and modify the Blade template:

   php artisan vendor:publish --provider="C975L\IncludeLibraryBundle\IncludeLibraryBundle" --tag=views
   

   Edit resources/views/vendor/includelibrary/default.blade.php to customize output (e.g., add defer to scripts).

3. Custom Attributes: Pass additional HTML attributes via the 4th parameter:

   {{ inc_lib('bootstrap', 'js', '4.6.0', ['defer' => 'defer', 'data-turbolinks-eval' => 'false']) }}
   

4. Local Development Proxy: Use Laravel Valet/Vagrant to mirror CDN files locally for offline testing:

   // config/include_library.php
   'cdn_proxies' => [
       'bootstrap' => 'http://localhost:8000/vendor/bootstrap/',
   ],