Symfony Ui Bundle Laravel Package

Getting Started

Minimal Setup

1. Installation

   composer require cooolinho/symfony-ui-bundle
   

   Register the bundle in config/bundles.php (Symfony):

   return [
       // ...
       Coolinho\SymfonyUiBundle\CoolinhoSymfonyUiBundle::class => ['all' => true],
   ];
   

2. First Use Case

   • Basic UI Component Rendering Inject the SymfonyUiManager service into a controller or Twig template:

     use Coolinho\SymfonyUiBundle\Manager\SymfonyUiManager;
     
     class MyController extends AbstractController
     {
         public function index(SymfonyUiManager $uiManager): Response
         {
             $ui = $uiManager->render('button', ['label' => 'Click Me']);
             return $this->render('template.html.twig', ['ui' => $ui]);
         }
     }
     

     In Twig:

     {{ ui|raw }}
     

3. Where to Look First

   • Documentation: Check src/Resources/doc/ for usage examples.
   • Default Components: Browse src/Component/ for built-in components like Button, Alert, or Modal.
   • Configuration: Review config/packages/cooolinho_symfony_ui.yaml for defaults.

Implementation Patterns

Core Workflows

1. Dynamic UI Rendering

   • Use SymfonyUiManager to generate reusable components dynamically:

     $uiManager->render('card', [
         'title' => 'User Profile',
         'content' => $user->bio,
         'actions' => [
             ['type' => 'button', 'label' => 'Edit', 'href' => '/edit']
         ]
     ]);
     

2. Twig Integration

   • Extend Twig with custom filters/tags:

     {# Render a button with Twig logic #}
     {% set button = ui('button', {label: 'Save', icon: 'save'}) %}
     {{ button|render }}
     

   • Create a custom Twig extension:

     // src/Twig/UiExtension.php
     class UiExtension extends \Twig\Extension\AbstractExtension
     {
         public function getFunctions(): array
         {
             return [
                 new \Twig\TwigFunction('ui', [$uiManager, 'render']),
             ];
         }
     }
     

3. Component Composition

   • Nest components for complex UIs:

     $uiManager->render('modal', [
         'title' => 'Confirm Action',
         'body' => $uiManager->render('alert', ['message' => 'Are you sure?']),
         'footer' => $uiManager->render('button', ['label' => 'Confirm', 'type' => 'primary'])
     ]);
     

4. Event-Driven UI

   • Attach JavaScript events to rendered components:

     $uiManager->render('button', [
         'label' => 'Toggle',
         'onClick' => 'toggleModal()'
     ]);
     

   • Use data-* attributes for custom logic:

     $uiManager->render('div', [
         'class' => 'custom-element',
         'data-action' => 'fetch-data'
     ]);
     

Integration Tips

• Symfony Forms: Combine with Symfony’s form system for dynamic forms:

  $form = $formFactory->createNamedBuilder('user', UserType::class, $user)
      ->getForm();
  $ui = $uiManager->render('form', ['form' => $form->createView()]);
  

• Asset Management: Use Symfony’s asset component to bundle JS/CSS:

  $uiManager->render('script', [
      'src' => $assetManager->getUrl('bundles/cooolinho/js/ui.js')
  ]);
  

• Translation: Support i18n by passing translation keys:

  $uiManager->render('button', [
      'label' => 'app.ui.save',
      'translator' => $translator
  ]);
  

Gotchas and Tips

Pitfalls

1. Component Registration

   • Issue: Custom components aren’t recognized.
   • Fix: Ensure they’re registered in services.yaml:

     services:
         Coolinho\SymfonyUiBundle\Component\MyCustomComponent:
             tags: ['cooolinho.ui.component']
     

2. Twig Auto-escaping

   • Issue: Components render escaped HTML (e.g., & becomes &).
   • Fix: Use |raw in Twig or configure Twig’s escaping strategy:

     {{ ui|raw }}
     

     Or in PHP:

     $uiManager->render('div', ['safe' => true]);
     

3. Dependency Injection

   • Issue: SymfonyUiManager not injectable.
   • Fix: Verify the bundle is loaded in config/bundles.php and clear cache:

     php bin/console cache:clear
     

4. JavaScript Conflicts

   • Issue: Dynamic components break existing JS.
   • Tip: Use unique IDs/classes or wrap components in isolated containers:

     $uiManager->render('div', [
         'class' => 'ui-container',
         'data-isolation' => true
     ]);
     

Debugging

• Enable Debug Mode: Set COOLINHO_UI_DEBUG=true in .env to log component rendering.
• Log Component Output: Dump rendered HTML for inspection:

  file_put_contents(
      'debug-ui.html',
      $uiManager->render('button', ['label' => 'Test'])
  );
  

• Check Component Existence: Verify components exist in src/Component/ or are registered via tags.

Configuration Quirks

1. Default Component Paths

   • Components are auto-loaded from src/Component/ or paths defined in cooolinho_symfony_ui.yaml:

     coolinho_symfony_ui:
         component_paths: ['%kernel.project_dir%/src/Components']
     

2. Overriding Defaults

   • Customize default components by extending them:

     class CustomButton extends \Coolinho\SymfonyUiBundle\Component\Button
     {
         public function render(array $options): string
         {
             $options['class'] = 'btn-custom ' . ($options['class'] ?? '');
             return parent::render($options);
         }
     }
     

   • Register the override in services.yaml with a higher priority.

3. Performance

   • Tip: Cache rendered components for static content:

     $cache = $cacheManager->getItem('ui_button_cache');
     if (!$cache->isHit()) {
         $cache->set($uiManager->render('button', [...]));
         $cache->expiresAfter(3600);
     }
     

Extension Points

1. Custom Components

   • Create a new component by extending AbstractComponent:

     namespace App\Component;
     
     use Coolinho\SymfonyUiBundle\Component\AbstractComponent;
     
     class ProgressBar extends AbstractComponent
     {
         public function render(array $options): string
         {
             return sprintf(
                 '<progress value="%s" max="100">%s%%</progress>',
                 $options['value'] ?? 0,
                 $options['value'] ?? 0
             );
         }
     }
     

   • Tag it as a service:

     services:
         App\Component\ProgressBar:
             tags: ['cooolinho.ui.component']
     

2. Component Modifiers

   • Modify rendered output via events (if the bundle supports them). Example for a hypothetical UiRenderEvent:

     $eventDispatcher->addListener(
         'cooolinho.ui.render',
         function (UiRenderEvent $event) {
             $event->setOutput(str_replace('class="btn"', 'class="btn modified"', $event->getOutput()));
         }
     );
     

3. Asset Bundling

   • Extend the bundle’s asset system to include custom JS/CSS:

     # config/packages/cooolinho_symfony_ui.yaml
     coolinho_symfony_ui:
         assets:
             js: ['/bundles/cooolinho/js/custom.js']
             css: ['/bundles/cooolinho/css/custom.css']