Sulu Site Configuration Bundle Laravel Package

Getting Started

Minimal Steps

1. Installation:

   • Require via Composer: composer require agence-raid/sulu-site-configuration-bundle
   • Register the bundle in config/bundles.php.
   • Add routes in config/routes/admin.yaml.

2. Database Setup:

   • Run migrations: bin/adminconsole doctrine:migrations:diff and bin/adminconsole doctrine:migrations:migrate.

3. Define Configuration Form:

   • Create a basic form in config/forms/webspace_configs/default.xml with essential fields (e.g., logo, website_email).
   • Example:

     <property name="logo" type="single_media_selection">
         <meta><title lang="en">Logo</title></meta>
     </property>
     

4. Grant Permissions:

   • Navigate to Settings → Roles in Sulu admin and assign {webspace-key}.configuration permissions to relevant roles.

First Use Case

• Access Configuration in Twig:

  {{ site_config('website_email') }}
  

  • Verify the configuration appears in the Configuration tab of the webspace view.

Implementation Patterns

Core Workflows

1. Form Customization:

   • Override the default form per webspace by creating config/forms/webspace_configs/{webspace-key}.xml.
   • Use the site_configuration_{webspace-key} key in the form definition.

2. Dynamic Configuration Retrieval:

   • Twig: Use site_config('key', 'default_value') for fallback values.
   • PHP: Inject SiteConfigurationService to fetch values programmatically:

     $this->configurationService->get('webspace-key', 'en', 'key');
     

3. Media Handling:

   • For media fields (e.g., logo), resolve the media object in Twig:

     {% set logo = sulu_resolve_media(site_config('logo').id, app.request.locale) %}
     <img src="{{ logo.url }}" alt="{{ logo.title }}">
     

4. Multi-Locale Support:

   • Store locale-specific configurations (e.g., en, fr) and fetch them dynamically:

     $config = $this->configurationService->getAll('webspace-key', app()->getLocale());
     

Integration Tips

• Validation: Extend the form with validation rules (e.g., required, email for website_email).
• Caching: Cache frequently accessed configurations in a service layer to reduce database calls.
• Webspace-Specific Logic: Use the webspace key to conditionally load configurations in controllers or Twig templates.

Gotchas and Tips

Pitfalls

1. Missing Permissions:

   • If the Configuration tab is invisible, ensure the role has {webspace-key}.configuration permissions.
   • Debug: Check Sulu’s permission system under Settings → Roles.

2. Form Key Mismatch:

   • The form must use the site_configuration key (or site_configuration_{webspace-key} for overrides). A typo here will break the UI.

3. Media Resolution:

   • Always resolve media objects in Twig using sulu_resolve_media to avoid null references:

     {% if site_config('logo') is not null %}
         {% set logo = sulu_resolve_media(site_config('logo').id, app.request.locale) %}
     {% endif %}
     

4. Locale Fallback:

   • If a locale-specific config is missing, the service returns null. Provide default values in Twig/PHP:

     {{ site_config('phone', '+1 234 567 890') }}
     

Debugging

• Database Checks:

  • Verify the sulu_site_configuration table contains entries for your webspace/locale.
  • Run bin/adminconsole doctrine:schema:update --dump-sql to check migration status.

• Form Validation:

  • Test form submissions in the Sulu admin to ensure validation works (e.g., required fields).

Extension Points

1. Custom Field Types:

   • Extend the form with custom field types by implementing a SuluFormType and registering it in the bundle’s configuration.

2. Event Listeners:

   • Listen to sulu_site_configuration.update events to trigger actions (e.g., cache invalidation) when configurations change:

     use AgenceRaid\SuluSiteConfigurationBundle\Event\SiteConfigurationEvent;
     
     public function onConfigurationUpdate(SiteConfigurationEvent $event) {
         // Logic here
     }
     

3. API Exposure:

   • Expose configurations via a custom API endpoint using Symfony’s JsonResponse:

     return new JsonResponse($this->configurationService->getAll($webspaceKey, $locale));