Ui Bundle Laravel Package

Getting Started

Minimal Setup

1. Installation Add the bundle to your Laravel project via Composer:

   composer require sylius/ui-bundle
   

   Register the bundle in config/app.php under providers and aliases (if using Sylius components).

2. First Use Case Use the bundle to scaffold a basic UI component (e.g., a product grid or cart summary) by leveraging Sylius’ Twig templates and Symfony UX components. Example:

   {% include '@SyliusUi/Component/product-grid.html.twig' %}
   

   • Key files to inspect:
     • vendor/sylius/ui-bundle/resources/views/ (Twig templates)
     • config/packages/sylius_ui.yaml (default configuration)

3. Prerequisites Ensure your project uses:

   • Symfony 6.4+ (Laravel 10+ via Symfony Bridge or standalone Symfony).
   • Twig for templating (Laravel’s Blade can integrate via twigbridge).
   • Symfony UX (for Stimulus controllers, if needed).

Implementation Patterns

1. Component-Based UI Workflow

• Reuse Sylius UI Components: Leverage pre-built components like:

  • product-grid (for catalogs)
  • cart-summary (for checkout)
  • order-history (for customer accounts)
  • How: Include them in Twig templates or extend via inheritance.

  {% extends '@SyliusUi/base.html.twig' %}
  {% block body %}
      {{ include('@SyliusUi/Component/cart-summary.html.twig') }}
  {% endblock %}
  

• Customize Components: Override templates by copying them to templates/SyliusUi/Component/ (Laravel’s resources/views/). Example: Modify product-grid.html.twig to add a "Quick View" button.

2. Integration with Laravel

• Twig in Laravel: Use twig/bridge to integrate Twig with Blade:

  composer require twig/bridge
  

  Configure in config/twig.php:

  'paths' => [
      'SyliusUi' => [__DIR__.'/../vendor/sylius/ui-bundle/resources/views'],
  ],
  

• Symfony UX + Stimulus: For dynamic behavior (e.g., cart updates), use Stimulus controllers:

  // assets/controllers/cart_controller.js
  import { Controller } from '@hotwired/stimulus';
  
  export default class extends Controller {
    connect() {
      console.log('Cart component loaded!');
    }
  }
  

  Link in Twig:

  <div data-controller="cart">
      {{ include('@SyliusUi/Component/cart-summary.html.twig') }}
  </div>
  

3. Theming and Assets

• CSS/JS Overrides: Publish assets to customize:

  php bin/console assets:install public
  

  Override SCSS variables in assets/app.scss:

  @import '~sylius/ui-bundle/assets/styles/_variables';
  $primary-color: #3498db; // Customize Sylius’ default palette
  

• Asset Management: Use Laravel Mix/Vite to compile Sylius’ assets alongside your project’s assets.

4. API-Driven UI

• Fetch Data via API: SyliusUiBundle assumes data comes from Sylius’ API (e.g., /api/products). For Laravel, use:

  // Example: Fetch products via Sylius API client
  $products = $syliusApiClient->products()->all();
  

  Pass data to Twig:

  {{ include('@SyliusUi/Component/product-grid.html.twig', {
      products: products,
      perPage: 12
  }) }}
  

Gotchas and Tips

Pitfalls

1. Twig vs. Blade Conflicts:

   • Issue: SyliusUiBundle uses Twig, but Laravel defaults to Blade.
   • Fix: Use twig/bridge and configure Twig to ignore Blade tags:

     // config/twig.php
     'auto_reload' => true,
     'autoescape' => false,
     'strict_variables' => true,
     

2. Asset Paths in Laravel:

   • Issue: Sylius assumes assets are in /public/build/, but Laravel uses /public/mix/.
   • Fix: Override asset paths in sylius_ui.yaml:

     sylius_ui:
         assets:
             javascripts:
                 - '%kernel.project_dir%/public/mix/js/app.js'
             stylesheets:
                 - '%kernel.project_dir%/public/mix/css/app.css'
     

3. Symfony UX Dependencies:

   • Issue: Stimulus/Turbo require Symfony UX, which may conflict with Laravel’s frontend stack.
   • Fix: Use symfony/ux-laravel or manually include UX assets.

4. Caching Headaches:

   • Issue: Twig templates may not update after changes.
   • Fix: Clear caches:

     php artisan cache:clear
     php artisan view:clear
     

Debugging Tips

• Template Debugging: Enable Twig debug mode in config/twig.php:

  'debug' => env('APP_DEBUG', true),
  

  Use {{ dump(_context) }} in Twig to inspect variables.

• Stimulus Debugging: Add data-action="click->console.log(event)" to test Stimulus controllers.

• API Data Mismatches: Verify Sylius API responses match SyliusUiBundle’s expected structure (e.g., products should include id, name, price).

Extension Points

1. Custom Components: Extend the bundle by creating new Twig components in templates/SyliusUi/Component/. Example: my-custom-component.html.twig.

2. Override Templates: Copy any template from vendor/sylius/ui-bundle/resources/views/ to your project’s templates/SyliusUi/ to customize.

3. Configuration: Override default settings in config/packages/sylius_ui.yaml:

   sylius_ui:
       options:
           theme: 'dark' # Override default theme
           product_grid:
               items_per_page: 20
   

4. Event Listeners: Hook into Sylius events (e.g., sylius.ui.component.render) to modify UI behavior dynamically.

Performance Tips

• Lazy-Load Components: Use Stimulus to load components dynamically (e.g., infinite scroll for product grids).
• Asset Optimization: Combine Sylius’ assets with Laravel Mix/Vite to reduce HTTP requests.
• Caching: Cache Twig templates for static pages:

  // In a controller
  return $this->renderView('SyliusUi/page.html.twig', [], ['cache_key' => 'homepage']);