Bootswatch Bundle Laravel Package

Getting Started

Minimal Setup

1. Installation:

   composer require akuma/bootswatch-bundle:dev-master
   

   Add the bundle to AppKernel.php:

   new Akuma\Bundle\BootswatchBundle\AkumaBootswatchBundle(),
   

2. Configure (config.yml):

   akuma_bootswatch:
       theme: "cosmo"  # Default theme (e.g., "cerulean", "flatly")
       font_awesome: true
   

3. Install Assets:

   php bin/console akuma:bootswatch:install
   

   This copies Bootswatch assets to web/ and sets up Font Awesome.

4. First Use Case: Include the theme in your base template (base.html.twig):

   <link rel="stylesheet" href="{{ asset('css/bootstrap.min.css') }}">
   <link rel="stylesheet" href="{{ asset('css/bootswatch/{{ app.config.akuma_bootswatch.theme }}.min.css') }}">
   

Implementation Patterns

1. Theme Switching

• Dynamic Theme Selection: Override the theme per environment or route:

  # config_dev.yml
  akuma_bootswatch:
      theme: "cerulean"
  

  Or dynamically in a controller:

  $this->get('akuma_bootswatch.twig.extension')->setTheme('flatly');
  

• Twig Extension: Use the akuma_bootswatch Twig extension to generate theme-specific assets:

  {{ akuma_bootswatch.css('bootswatch/{{ theme }}.min.css') }}
  

2. Asset Management

• Assetic Integration: Enable Assetic in config (auto_configure.assetic: true) and bundle assets:

  // app/config/config.yml
  assetic:
      bundles: [AcmeDemoBundle]
  

  Use in Twig:

  {% stylesheets
      'bundles/acmedemobundle/css/bootstrap.min.css'
      'bundles/acmedemobundle/css/bootswatch/{{ theme }}.min.css'
      filter='cssrewrite'
  %}
      <link rel="stylesheet" href="{{ asset_url }}">
  {% endstylesheets %}
  

• Custom Output Paths: Redirect assets to a CDN or subdirectory:

  akuma_bootswatch:
      output_dir: "%kernel.root_dir%/../web/custom-assets"
  

3. Sass/Less Processing

• Compile on Demand: Configure a processor (e.g., scssphp):

  akuma_bootswatch:
      less_filter: "scssphp"
  

  Recompile assets:

  php bin/console assetic:dump --watch
  

• Custom Sass Variables: Override Bootswatch variables by extending its Sass files in your project’s scss/ directory.

4. Font Awesome

• Auto-Installation: The install command copies Font Awesome to web/fonts. Use it in Twig:

  <link rel="stylesheet" href="{{ asset('css/font-awesome.min.css') }}">
  

Gotchas and Tips

Pitfalls

1. Asset Paths:

   • After running akuma:bootswatch:install, verify assets are in web/css/bootswatch/ and web/fonts/.
   • If paths are wrong, clear cache:

     php bin/console cache:clear
     

2. Theme Not Loading:

   • Ensure the theme name matches Bootswatch’s (e.g., "cosmo", not "Cosmo").
   • Check config.yml for typos in bootswatch.theme.

3. Assetic Conflicts:

   • If using Assetic, ensure auto_configure.assetic: true and bundles are properly configured.
   • Debug with:

     php bin/console assetic:dump --debug
     

4. Sass/Less Dependencies:

   • Missing scssphp or less.php will break compilation. Install dev dependencies:

     composer require --dev leafo/scssphp oyejorge/less.php
     

Debugging

• Check Config: Dump the bundle’s configuration to verify settings:

  $this->get('akuma_bootswatch.config')->getConfig();
  

• Log Asset Installation: Run akuma:bootswatch:install with -v for verbose output:

  php bin/console akuma:bootswatch:install -v
  

Extension Points

1. Custom Themes:

   • Add themes by copying from vendor/thomaspark/bootswatch to web/css/bootswatch/ and update config.yml:

     akuma_bootswatch:
         bootswatch:
             path: "%kernel.root_dir%/../web/css/bootswatch"
     

2. Override Twig Extensions:

   • Extend the Twig extension to add custom filters:

     // src/Acme/DemoBundle/Twig/BootswatchExtension.php
     class BootswatchExtension extends \Akuma\Bundle\BootswatchBundle\Twig\BootswatchExtension
     {
         public function getThemeClass($theme) { ... }
     }
     

   • Register it as a compiler pass or service override.

3. Post-Install Hooks:

   • Use Symfony’s event system to run tasks after akuma:bootswatch:install:

     # config.yml
     akuma_bootswatch:
         post_install_command: "app/console my:custom-task"
     

Performance Tips

• Enable HTTP Cache: Configure Assetic to use http_cache for Bootswatch assets:

  assetic:
      use_controller: true
      filters:
          http_cache:
              assets_path: /assets
  

• Minify Assets: Use Assetic’s yui_css or yui_js2 filters for production:

  {% stylesheets '...' filter='yui_css2' %}