README

Product Encyclopedia Lite

Structured educational content pages linked to products, for Shopware 6. Two-tier index pattern: a lightweight browse grid that grows fast + a curated deep-profile registry that grows slowly. Generalised from a stone-encyclopedia reference implementation.

License: MIT · Shopware: 6.7.x · PHP: 8.1 / 8.2

🇬🇧 English · 🇳🇱 Nederlands · 🇩🇪 Deutsch

Lite tier — and what's coming in Pro

Product Encyclopedia Lite (this package, tenbruggencate/productencyclopedia-lite) is the free tier of the Product Encyclopedia family. It handles the foundation: structured educational content pages (browse grid + deep profiles) linked to products, server-rendered Twig templates, per-sales-channel config and the registry pattern you extend from your hosting project. If you need "give a content-heavy catalog a real encyclopedia layer", Lite is the whole answer.

Product Encyclopedia Pro (coming as tenbruggencate/productencyclopedia-pro, distributed via the Shopware Store) will layer on the editorial + scale features that the Lite tier deliberately leaves out:

Rich CMS blocks — video embeds, comparison tables, glossary entries and interactive learning blocks ready to drop into profile content sections from the Shopware admin
Bulk content import / export — manage encyclopedia entries as a CSV / JSON dataset instead of as PHP registry subclasses
Multi-language sync helper — keep nl-NL / en-GB / de-DE profile content in lock-step without copy-pasting between locale registries
Related-product algorithm — automatic, scored recommendations linking profile pages to product detail pages by shared attributes, tags and content overlap

Pro is on the roadmap, not yet released. Lite alone is production-ready for the "structured educational content + product cross-linking" use case and stays free.

Screenshots

_{Encyclopedia index — desktop, browse grid}	_{Encyclopedia profile — Amethist deep page}
_{Encyclopedia index — mobile (responsive)}

What it does

Content-heavy catalogs (wines, stones, spices, knives) need two kinds of pages that are both educational and both link to products — but they shouldn't grow at the same rate:

A fast-growing browse grid where every new SKU can appear immediately with a title + thumbnail + one-liner
A slow-growing deep-profile registry where a handful of curated items get real editorial content (origins, how-to-use, care, history)

Most content plugins force you to pick one. This plugin ships both tiers, linked by slug, so you can add items to the browse grid the day they're in stock and invest in deep profiles at your own pace.

Install

Product Encyclopedia Lite is free and distributable via Composer / Packagist or via the Shopware Store.

composer require tenbruggencate/productencyclopedia-lite
bin/console plugin:refresh
bin/console plugin:install --activate TenBruggencateProductEncyclopedia
bin/console cache:clear

The plugin class name stays TenBruggencateProductEncyclopedia (grandfathered from v1.x — only the composer package name changed in v2.0.0). If you're upgrading from v1.x see the v2.0.0 changelog entry for the one-line composer manifest update.

Two-tier design

BrowseIndex (lightweight tier)


Purpose	fast-growing grid for browsing and discovery
Data per entry	slug, title, one filterable attribute value, one-liner description
Growth rate	fast — new entries appear the moment they're in stock
Example	40+ stones in a visual grid, filterable by colour

ProfileRegistry (rich tier)


Purpose	curated deep profiles with full editorial content
Data per entry	slug, title, description, image, multiple attribute groups, tags, ordered content sections
Growth rate	slow — each entry is a real content commitment
Example	10 stones with chakra/zodiac data, meaning, care instructions, experiments

Browse entries have an optional profileSlug that links to a deep profile when one exists. The browse grid works standalone — not every item needs a deep profile.

Configuration

In the Shopware admin under Settings → System → Plugins → Product Encyclopedia Lite.

Field	Default	Purpose
`enabled`	`true`	Kill switch for all encyclopedia routes
`baseRoute`	`encyclopedia`	URL prefix (display only — actual paths are in route XML)
`itemLabel`	`Item`	What entries are called (stone, wine, spice)
`itemLabelPlural`	`Items`	Plural form
`filterAttribute`	`colour`	Which attribute shows as filter pills on the browse grid

Routes

Route ID	Path	Controller
`product-encyclopedia.browse`	`/encyclopedia/browse`	`BrowseController::index`
`product-encyclopedia.profile`	`/encyclopedia/{slug}`	`ProfileController::show`
`product-encyclopedia.group`	`/encyclopedia/group/{group}/{value}`	`AttributeGroupController::show`

Populating with data

The plugin ships with empty registries. Extend ArrayProfileRegistry in your theme plugin:

final class MyStoneRegistry extends ArrayProfileRegistry
{
    protected function buildItems(): array
    {
        return [
            'amethyst' => new ProfileItem(
                slug: 'amethyst',
                title: 'Amethyst',
                description: 'A purple variety of quartz.',
                imageUrl: '/images/amethyst.jpg',
                attributeGroups: [
                    ['name' => 'chakra', 'values' => ['third-eye', 'crown']],
                ],
                tags: ['calming', 'purple'],
                contentSections: [
                    ['heading' => 'Meaning', 'body' => 'Valued since antiquity...'],
                ],
            ),
        ];
    }
}

<service id="TenBruggencateProductEncyclopedia\Registry\ProfileRegistryInterface"
         class="MyPlugin\Registry\MyStoneRegistry"/>

Standards

Performance — registries are in-memory arrays; zero DB queries for profile lookup. Browse grid uses server-side filtering (no JS framework, works without JavaScript).
SEO — every profile page emits structured Article JSON-LD. meta_title and meta_description are derived from the profile data and overridable per entry. Filter-pill URLs are crawlable as /encyclopedia/group/{attribute}/{value} (server-rendered, no #fragment routing).
GDPR — stateless. No cookies, no tracking, no per-visitor data. Full data-flow documentation in GDPR.md.
WCAG 2.2 AA — semantic heading hierarchy (h1 → profile title; h2 → content section headings); filter pills are <a> tags (keyboard + screen-reader accessible); focus state inherited from theme. Live axe-core audit output + localised-copy evidence: docs/ACCESSIBILITY.md.
Security — all profile / browse data comes from PHP registries; no user-controllable input reaches templates or DB. No XSS surface.
Uninstall — plugin:uninstall --keep-user-data preserves every TenBruggencateProductEncyclopedia.config.* row; without the flag the destructive path clears them all. No owned tables — content comes from your hosting project's registries, not from this plugin.

Production-readiness checklist

A deliberately short list of things to verify before enabling the plugin on a customer-facing storefront. Not legal cover — the MIT license already disclaims warranty — but practical guidance an experienced operator would want anyway.

[ ] Provide BrowseEntry + ProfileItem registries from your hosting project. This plugin defines the shape (interfaces, controllers, templates) but doesn't ship content — your theme plugin or a content-only sibling registers the actual entries. With no registry wired in, /encyclopedia/browse renders an empty grid and profile slugs return 404. Plan the content shape before flipping the install on prod.
[ ] Decide on your route prefix. Default routes are at /encyclopedia/*, but most projects rebrand them to a domain-appropriate base (/stones/*, /wines/*, /spices/*). Configure the SEO URL templates in Shopware admin so the public URLs match your category nomenclature, not the generic plugin term.
[ ] Test profile-slug ↔ browse-entry linkage on staging. Browse cards optionally link to deep profiles via profileSlug; a typo in either side silently breaks the cross-link without a 404 (the card just doesn't become a link). Render a few cards and confirm the ones with deep profiles do link out.
[ ] Run axe-core on a profile page before launch. The plugin's templates are WCAG-clean, but your theme's typography + colour-contrast applies once tokens are inherited — the audit has to happen with your theme active, not against the plugin in isolation.
[ ] Plan content cadence honestly. The two-tier model only pays off if browse entries grow fast and profiles grow slow. Shipping 20 cards with 0 deep profiles is fine; shipping 20 cards with 20 half-finished profiles is a maintenance burden visible to every visitor — leave a slug empty rather than ship Lorem Ipsum.

Snippets

Ships with translations for nl-NL, en-GB, and de-DE. Override in your theme plugin's snippet JSON files using the product-encyclopedia.* key namespace.

Compatibility

Core platform

Shopware	PHP	Status
6.7.x — tested against 6.7.8, 6.7.9	8.1, 8.2	Stable
6.6.x	—	Not supported
6.5.x and earlier	—	Not supported

Database

Engine	Version	Notes
MySQL	8.0+	Primary target; JSON functions used for config-row manipulation in migrations
MariaDB	10.11+	Tested end-to-end; earlier versions lack some JSON operator support

Browsers (storefront)

Evergreen browsers only — the two most recent stable releases of each:

Browser	Desktop	Mobile
Chrome / Chromium	✅	✅
Firefox	✅	✅
Safari	✅ (macOS)	✅ (iOS 16+)
Edge	✅	—

Internet Explorer and legacy Edge are not supported. The plugin emits no runtime JS (where applicable) so graceful degradation on older browsers usually still renders content, just without progressive enhancements.

Admin browsers

Same evergreen matrix — the Shopware admin is Vue-based and has its own compatibility baseline that this plugin doesn't extend or narrow.

Development

Tool	Version	Scope
PHP	≥ 8.1	Runtime + test suite
Composer	2.x	Dependency management
Node.js	≥ 18	Only needed if you edit SCSS and re-run the theme compile
Python	≥ 3.9	Only needed for the repo's asset-pipeline scripts (`scripts/*.py`)

Accessibility

WCAG 2.2 level A + AA — see docs/ACCESSIBILITY.md for axe-core audit output and per-page violations.

What we test before each release

Full PHPUnit unit suite against PHP 8.1 + 8.2 (source-inspection tests don't need a kernel)
PHPStan level 8 + PHP-CS-Fixer (@PSR12 + @Symfony)
Composer validate on every plugin
Live-DB smoke tests (plugin install → activate → route render → uninstall cycle)
axe-core audit on the primary storefront surfaces (see ACCESSIBILITY.md)

Related plugins

Sibling plugins from the same publisher:

TenBruggencateMultiBrand — when active, profiles render with per-brand --brand-* tokens so the same encyclopedia looks distinct across brand domains
TenBruggencateAnalytics — profile views and filter-pill clicks are tracked as custom events when Analytics is active
TenBruggencateNewsletterLite — GDPR-safe newsletter signup with double opt-in
TenBruggencateMaintenance — branded maintenance page with HTTP 503 + Retry-After
TenBruggencateLegalPages — drop-in legal templates with merge fields

Support

Email: guy@tenbruggencatedevelopment.nl
Docs & news: tenbruggencatedevelopment.nl
Source / issues: Bitbucket repo
Security vulnerabilities: see SECURITY.md — email first, no public issues, 72-hour acknowledgement SLA

tenbruggencate / productencyclopedia-lite

Maintainers

Package info

Statistics

Security