Sitemap Widget Laravel Package

Getting Started

This is not a Laravel package. It is a Symfony bundle for Victoire DCMS (a Symfony-based CMS). There is no service provider, facade, config file, or Blade integration. Treat it as a Symfony bundle you would only encounter while maintaining an existing Victoire site.

Minimal steps

1. Confirm the package is installable. The repository is FriendsOfVictoire/WidgetSitemapBundle, and the Packagist name is likely friendsofvictoire/sitemap-widget; verify with:

   composer show friendsofvictoire/sitemap-widget
   

   If it is not on Packagist, add a VCS repository entry and pin a commit:

   {
     "repositories": [
       { "type": "vcs", "url": "https://github.com/FriendsOfVictoire/WidgetSitemapBundle" }
     ],
     "require": {
       "friendsofvictoire/sitemap-widget": "dev-master"
     }
   }
   

2. Register the bundle in the Symfony kernel (Symfony 2/3 style, which is what Victoire targets):

   // app/AppKernel.php
   $bundles = [
       // ...
       new FriendsOfVictoire\Widget\SitemapBundle\WidgetSitemapBundle(),
   ];
   

3. Clear cache and publish assets:

   php app/console cache:clear --env=prod
   php app/console assets:install web --symlink
   

4. Look first at these files in vendor/friendsofvictoire/sitemap-widget/:

   • The widget class under Widget/ — it defines the widget name, template, and business entity binding.
   • Form/ — the widget configuration form shown in the Victoire editor.
   • Resources/views/ — the Twig template that renders the sitemap.
   • Resources/config/services.yml — the victoire_widget service tag. This is the source of truth for how the widget is exposed.

5. First use case: open a page in the Victoire editorial UI, add the “Sitemap” widget from the widget picker, configure its root page or content source, publish, and view the rendered page tree.

Implementation Patterns

Widget placement and configuration

Victoire widgets are not called from application code the way a Laravel view component would be. Editors place them into page slots. Your job is usually to make the widget configurable and to control what it renders.

A typical widget registration mirrors this shape (copy the exact tag attributes from the bundle’s services.yml, since Victoire versions differ):

services:
    victoire.widget.sitemap:
        class: FriendsOfVictoire\Widget\SitemapBundle\Widget\SitemapWidget
        tags:
            - { name: victoire_widget, alias: sitemap }

Overriding the template

Do not edit vendor files. Override the Twig template from your app:

app/Resources/FriendsOfVictoireWidgetSitemapBundle/views/widget.html.twig

In newer Symfony skeleton layouts this may be templates/bundles/FriendsOfVictoireWidgetSitemapBundle/. Confirm which convention your Symfony version uses.

Extending rather than forking

If you need a different page source, ordering, or markup:

1. Subclass the widget class.
2. Override the template path and any getWidgetName() / configuration methods.
3. Register your subclass as a new victoire_widget service with a different alias.
4. Leave the vendor bundle untouched so you can still pull upstream fixes.

Caching rendered output

Sitemap widgets often walk the page tree and can be expensive. Cache the rendered fragment and invalidate it when pages are published:

$cacheKey = 'victoire.sitemap.' . $page->getId() . '.' . $locale;

return $this->cache->get($cacheKey, function () use ($page) {
    return $this->renderView('@WidgetSitemap/widget.html.twig', [
        'page' => $page,
    ]);
});

Wire invalidation to Victoire’s page publish events rather than a short TTL; otherwise editors will not see updates immediately.

Separating “visual sitemap” from “XML sitemap”

This bundle is a CMS widget that renders a human-facing sitemap, not an XML sitemap generator. If you need /sitemap.xml for search engines, do not bend the widget into that role. Implement a small Symfony controller or console command that queries published pages and emits XML, or use an existing sitemap generator for the stack you are actually on. In Laravel, that would be spatie/laravel-sitemap.

Testing

Write a functional test that boots the kernel, creates a published page with children, places the widget, and asserts the response contains the expected links. Because the bundle has no test suite of its own, this is your only regression safety net.

Gotchas and Tips

• Zero stars, zero dependents, no maintainers. This is effectively an unmaintained artifact. Pin an exact commit in composer.json, fork it internally, and assume there will be no security or compatibility fixes. Do not introduce it into a new project.
• Not Laravel-compatible. You cannot composer require this and use it in a Laravel app. It depends on Symfony’s kernel, Victoire’s widget rendering pipeline, and Doctrine’s page tree. Bridging it would mean porting the widget logic, at which point you should just write the sitemap yourself.
• Version constraints will bite. Victoire targets older Symfony (2.x/3.x) and older PHP. Expect conflicts with modern Symfony, PHP 8, and any current Laravel project sharing the same vendor/ directory. Composer resolution failures are the most likely first obstacle.
• Widget does not appear in the editor. Almost always a registration or cache problem. Run:

  php app/console debug:container --tag=victoire_widget
  php app/console cache:clear
  

  Verify the tag alias matches what the editor expects and that the bundle is registered in the correct environment kernel.
• Template overrides silently ignored. Twig bundle override paths changed between Symfony versions. If your override is not picked up, check debug:twig for the resolved template path and use the correct app/Resources/... or templates/bundles/... location.
• Page tree queries can be N+1. A recursive sitemap walk over a large site will issue many queries. Use Doctrine tree repositories (childrenHierarchy, getChildren) or eager-load translations, and cache the result.
• Rendering errors are swallowed by the CMS. A broken widget template can render as an empty block in the editor rather than throwing a visible error. Check app/logs/dev.log, enable the Symfony profiler, and test the widget template directly in a controller if needed.
• Asset paths are easy to get wrong. Widget CSS/JS, if any, require assets:install and may need a --symlink flag in development. Missing styles usually mean assets were installed into the wrong web root.
• Extension points are limited. The realistic extension points are the widget class, the form type, and the Twig template. There is no event system or configuration layer in this bundle. If you need behavior beyond those three, subclassing is the only clean route.
• Budget for replacement. Given the adoption level, the pragmatic day-to-day posture is: use it only to keep an existing Victoire site running, isolate it behind your own subclass, and plan to replace the widget with a small custom implementation when the site is next touched.