Site Bundle Laravel Package

Getting Started

Minimal Setup

1. Installation Run composer require c975l/site-bundle in your Laravel project (note: this is a Symfony bundle, but can be adapted via Laravel's Symfony integration or a bridge like spatie/laravel-symfony-support).

2. Enable Routes Add to routes/web.php:

   Route::group(['namespace' => 'C975L\SiteBundle\Controller'], function () {
       require __DIR__.'/vendor/c975l/site-bundle/src/Resources/config/routes.php';
   });
   

3. Publish Config Run php artisan vendor:publish --provider="C975L\SiteBundle\SiteBundle" to publish default config (adjust for Laravel’s config/ structure).

4. First Use Case Override the base layout in resources/views/layouts/app.blade.php (Symfony Twig) or resources/views/layouts/base.blade.php (Laravel) to extend the bundle’s default layout.

Implementation Patterns

Core Workflows

1. Layout Customization

   • Extend the base layout (site.html.twig in Symfony) by copying vendor/c975l/site-bundle/src/Resources/views/layouts/site.html.twig to resources/views/layouts/site.html.twig.
   • Inject Laravel-specific variables (e.g., {{ config('app.name') }}) alongside bundle variables (e.g., {{ site.title }}).

2. Dynamic Site Data Use the site/config route (protected by role) to manage:

   • Site title, description, and metadata.
   • Matomo tracking (set site.matomo.url and site.matomo.id in config).
   • Cookie consent settings (e.g., site.cookie_consent.enabled).

3. Exception Templates Override Symfony’s exception templates by copying files from vendor/c975l/site-bundle/src/Resources/views/TwigBundle/Exception/ to resources/views/TwigBundle/Exception/.

4. Legal Pages Predefined templates for:

   • Terms of Use (terms.html.twig).
   • Privacy Policy (privacy.html.twig). Render via routes like /terms (configured in routes.php).

Integration Tips

• Laravel-Symfony Bridge: Use spatie/laravel-symfony-support to handle Symfony bundles in Laravel. Example:

  // config/app.php
  'providers' => [
      Spatie\SymfonySupport\SymfonyServiceProvider::class,
      C975L\SiteBundle\SiteBundle::class,
  ],
  

• Asset Pipeline: Symlink assets manually if assets:install fails:

  ln -s vendor/c975l/site-bundle/src/Resources/public/css /public/css/site
  

• Blade vs. Twig: Convert Twig templates to Blade using twig-to-blade or manually replace {{ }} with @{{ }} and |raw filters with {{ !! }}.

Gotchas and Tips

Pitfalls

1. Config Management:

   • The bundle relies on c975l/config-bundle for runtime config. If missing, publish config manually:

     php artisan vendor:publish --provider="C975L\ConfigBundle\ConfigBundle"
     

   • Laravel’s config/cache may conflict; disable caching during development:

     // config/caching.php
     'enabled' => env('APP_DEBUG') ? false : true,
     

2. Route Conflicts:

   • The bundle’s site/config route may clash with Laravel’s admin routes. Rename or prefix:

     // routes/web.php
     Route::prefix('admin')->group(function () {
         // ...
     });
     

3. Asset Loading:

   • If CSS/JS fails to load, verify symlinks:

     ls -la public/css/site
     

   • For Laravel Mix/Webpack, copy assets to public/ in post-install script:

     cp -r vendor/c975l/site-bundle/src/Resources/public/css public/
     

4. Twig in Laravel:

   • The bundle assumes Twig. To use Blade:
     • Override Twig templates with Blade equivalents.
     • Disable Twig’s auto-escaping in config/twig.php:

       'autoescape' => false,
       

Debugging

• Config Not Loading: Check config/site.php exists and is readable. Clear config cache:

  php artisan config:clear
  

• Routes Not Found: Ensure C975L\SiteBundle\SiteBundle is registered in config/app.php and routes are loaded after Laravel’s default routes.

Extension Points

1. Custom Variables: Extend the base layout to include Laravel-specific data:

   {# resources/views/layouts/site.html.twig #}
   <title>{{ site.title }} | {{ config('app.name') }}</title>
   

2. Dynamic Matomo: Add Laravel’s app.url to Matomo config:

   // config/site.php
   'matomo' => [
       'url' => env('MATOMO_URL', 'https://matomo.example.com'),
       'id' => env('MATOMO_ID', '1'),
       'base_url' => url('/'), // Laravel dynamic URL
   ],
   

3. Cookie Consent: Integrate with Laravel’s cookie helper:

   // app/Providers/AppServiceProvider.php
   public function boot()
   {
       if (config('site.cookie_consent.enabled')) {
           Cookie::queue('cc_accepted', 'true', 365);
       }
   }