Articlelist Widget Laravel Package

Getting Started

This is not a standalone library — it is a Victoire CMS widget bundle. It only makes sense inside a running Victoire installation, so your first job is confirming the host app is compatible. Expect Symfony 2.8/3.4-era constraints and a Victoire 2.x stack; if you are on Symfony 4+, stop here and budget for a fork or a rewrite.

1. Install alongside Victoire:

   composer require friendsofvictoire/articlelist-widget
   

   If the tagged release does not resolve against your victoire/victoire constraint, pin dev-master and inspect composer.json in the package.
2. Register the bundle in app/AppKernel.php:

   new FriendsOfVictoire\WidgetArticleListBundle\WidgetArticleListBundle(),
   

3. Clear cache (bin/console cache:clear) and open the Victoire page editor. The widget should now appear in the widget picker as an "Article list" type.
4. Look first at these four files, in order:
   • Widget/ArticleListWidget.php — the widget entity and its persisted config fields (maxResults, ordering, business entity reference, template name).
   • Resources/config/config.yml — how the widget is declared to victoire_core.
   • Form/ArticleListType.php — the admin form editors use to configure an instance.
   • Resources/views/Widget/ArticleList/template.html.twig — the front-end rendering.

First use case: drop the widget onto a blog index or "latest news" page, point it at the BlogBundle business entity, set a result limit, and confirm articles render. That single flow exercises install, registration, persistence, query, and template resolution.

Implementation Patterns

Editor-managed instances (the normal path). Widgets are entities persisted per page, not Twig includes. A content editor adds the widget in the admin, fills the form (entity, limit, ordering, template), and Victoire stores the configuration in the widget table and an entry in the widget map for the page/slot. Day-to-day work is mostly: register widget → editors configure → developers override presentation.

Programmatic placement. For fixtures or seed data, create the widget entity, set its config properties, persist it, then attach it to a page's WidgetMap with the target slot and position. Keep slot names consistent with the theme's layout templates.

Template overrides. Never edit vendor/. Copy the front template to app/Resources/Victoire/Widget/ArticleList/template.html.twig (or the Symfony 3.4+ templates/bundles/... equivalent) and customize there. Victoire's template resolution prefers the app-level path, so overrides are clean and survive composer update.

Custom query logic. If the widget's default repository call is too narrow (e.g., you need category filtering or a custom Article subclass), subclass ArticleListWidget or override the item-fetching method, then register your subclass as the widget type. Prefer this over adding query flags to the base widget entity.

Extending the edit form. Add fields by subclassing ArticleListType and registering a form theme/section. Any new persisted field must also be added to the widget entity with a Doctrine migration, since widget config lives in the database.

Integration tip: keep business-entity selection explicit in the form. Hard-coded entity lookups inside the widget make it fragile when editors reuse the same widget across multiple blogs or sections.

Gotchas and Tips

• Abandoned since April 2019, zero stars, zero dependents. Treat it as reference code, not a dependency you can rely on for support. Read the source before adopting.
• Composer constraint hell. The package will likely refuse to install on modern PHP/Symfony. Options: platform-config override in composer.json, or fork and relax constraints. Forking is usually the honest choice.
• Hard coupling to Victoire\Bundle\BlogBundle. The widget assumes an Article entity exists. If the blog bundle is missing or the entity is renamed, the widget fails at render or form time, often with a vague error.
• Cache is aggressive. After touching config.yml, the form type, or templates, always bin/console cache:clear. Victoire also caches widget declarations, so a "widget disappeared" bug is almost always a stale cache.
• DB-backed configuration. Every widget instance is a row. Changing widget entity fields without a migration leaves old rows with missing columns — expect NULL-related template errors.
• Template resolution order. Verify which template actually renders using the Symfony profiler's Twig panel before debugging markup. An app-level override silently shadowing the bundle template is the usual culprit.
• Debugging checklist: inspect the widget table row for the instance's config, verify the WidgetMap entry points at the right page/slot, then debug:container to confirm the widget service is registered. That sequence isolates persistence vs. rendering vs. registration failures quickly.
• No pagination out of the box. If the widget exposes only a maxResults limit, a "view all" link or custom pagination is your responsibility in the overridden template.
• Extension points, preferred order: app-level Twig override → subclassed widget entity → subclassed form type → patched vendor code (last resort, never commit).