Sensi Yaml Gui Bundle Laravel Package

Getting Started

Minimal Setup

1. Installation

   composer require bupychuk/sensi-yaml-gui-bundle
   

   Update AppKernel.php to register the bundle:

   new Sensi\Bundle\YamlGuiBundle\SensiYamlGuiBundle(),
   

2. Routing Add to app/config/routing.yml:

   sensi_yaml_gui:
       resource: "@SensiYamlGuiBundle/Resources/config/routing.yml"
       prefix: /yamlgui
   

3. Configuration Create app/config/yamlgui.yml:

   sensi_yaml_gui:
       config_root_dir: "%kernel.root_dir%/config/yamlgui/"
       managed_files:
           "demo.yml": { title: "Demo Config" }
   

   Include it in config.yml:

   imports:
       - { resource: yamlgui.yml }
   

4. First Use Case Place a YAML file (e.g., demo.yml) in config/yamlgui/ and access /yamlgui to edit it via a web form.

Implementation Patterns

Workflows

1. Standalone Usage

   • Skip SonataAdmin integration by setting sonata_admin_modus: false in yamlgui.yml.
   • Directly access /yamlgui for a lightweight form-based YAML editor.

2. SonataAdmin Integration

   • Enable sonata_admin_modus: true to embed the editor in Sonata’s dashboard.
   • Customize the template by overriding SensiYamlGuiBundle::default.html.twig.

3. File Management

   • Add Files: Extend managed_files in yamlgui.yml with new YAML paths and titles.
   • Permissions: Ensure config_root_dir is writable by the web server (e.g., chmod -R 775 config/yamlgui).

4. Validation

   • Leverage Symfony’s YAML parser for validation (e.g., invalid YAML breaks rendering).
   • Add custom validation via Twig filters or Symfony form events (see Extension Points).

Integration Tips

• Twig Extensions: Use {{ dump(yamlgui_config) }} in templates to debug parsed YAML.
• Event Listeners: Subscribe to sensi.yaml_gui.save event to trigger actions post-save:

  // src/Acme/EventListener/YamlGuiListener.php
  public function onYamlSave(YamlGuiEvent $event) {
      $file = $event->getFile();
      // Reload config or trigger cache clear
  }
  

• Security: Restrict access via firewall rules (e.g., IP whitelisting) or Symfony’s voter system.

Gotchas and Tips

Pitfalls

1. File Permissions

   • Issue: "Permission denied" errors if config_root_dir lacks write access.
   • Fix: Run chmod -R 775 config/yamlgui and ensure the web server user (e.g., www-data) owns the directory.

2. YAML Parsing Errors

   • Issue: Broken forms or blank pages if YAML is malformed.
   • Debug: Check Symfony’s profiler for parsing exceptions or enable debug mode (APP_DEBUG=true).

3. Caching Quirks

   • Issue: Changes to yamlgui.yml may not reflect immediately due to Symfony’s config cache.
   • Fix: Clear cache after config changes:

     php bin/console cache:clear
     

4. SonataAdmin Conflicts

   • Issue: Template conflicts if sonata_admin_modus: true but SonataAdmin isn’t installed.
   • Fix: Install SonataAdminBundle or disable the mode.

Debugging

• Log Parsed YAML: Override the template to dump parsed data:

  {% extends 'SensiYamlGuiBundle::default.html.twig' %}
  {% block body %}
      {{ dump(yamlgui_config) }}
      {{ parent() }}
  {% endblock %}
  

• Check Events: Verify listeners are triggered by adding a logger:

  public function onYamlSave(YamlGuiEvent $event) {
      \Log::info('Saved file:', [$event->getFile()]);
  }
  

Extension Points

1. Custom Templates Override the default template at app/Resources/SensiYamlGuiBundle/views/default.html.twig.

2. Form Type Extensions Extend the base form type to add custom fields or validation:

   // src/Acme/SensiYamlGui/Extension/YamlGuiExtension.php
   public function loadExtension(YamlGuiExtension $extension, FormBuilderInterface $builder, array $options) {
       $builder->add('custom_field', TextType::class);
   }
   

3. Post-Save Logic Use the sensi.yaml_gui.save event to integrate with other systems (e.g., database sync):

   # config/services.yml
   services:
       acme.yaml_gui_listener:
           tag: kernel.event_listener
           class: Acme\EventListener\YamlGuiListener
           arguments: ['@some_service']
           calls:
               - [setContainer, ['@service_container']]
           tags:
               - { name: kernel.event_listener, event: sensi.yaml_gui.save, method: onYamlSave }
   

4. Security Hardening Add a voter to restrict access to sensitive configs:

   public function supportsAttribute($attribute) {
       return $attribute === 'yaml_edit';
   }
   public function vote(TokenInterface $token, $object, array $attributes) {
       return $token->hasRole('ROLE_YAML_ADMIN') ? AccessDecisionInterface::ACCESS_GRANTED : AccessDecisionInterface::ACCESS_DENIED;
   }