README

Product Encyclopedia Lite

Structured educational content pages 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 Pro adds

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), 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 is shipped and installs side by side with Lite — it requires this package and extends it rather than replacing it. tenbruggencate/productencyclopedia-pro is not on Packagist: it is delivered directly today, with a Shopware Store listing in preparation. Pro adds the product coupling that Lite deliberately leaves out:

Choose per profile which products are recommended and in what order
A "Related products" section using Shopware's standard product cards: price, availability and add-to-cart work out of the box
Managed under Settings → Product Encyclopedia Pro: product picker with search-as-you-type, list with edit and delete; EN/NL/DE
Robust: deleted products lose their links automatically, no duplicate links, profiles without links stay unchanged
Twig helpers tb_pepro_related_products() and tb_pepro_load_related_products() for your own templates
Export all data button: JSON with links and configuration, also via API; keep or remove data on uninstall

→ More about Product Encyclopedia Pro

Screenshots

Neutral storefront screenshots follow in a later release.

What it does

Content-heavy catalogs (wines, stones, spices, knives) need two kinds of educational page — 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`

While a sales channel has no entries to show, the browse hub is served noindex,follow with no canonical and is omitted from that channel's sitemap — the same EncyclopediaIndexability rule drives the controller and EncyclopediaUrlProvider, so they cannot drift.

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

Package info

Security

Statistics