ETechFlow_VehicleCompat — Vehicle Compatibility + Part Finder for Magento 2

A complete vehicle compatibility (Make / Model / Year / Part) system for Magento 2 stores selling automotive products. Theme-agnostic by design — bundles its own Alpine.js loader so it works on Hyvä, Luma, and any custom theme without code changes.

• Version: 1.0.0
• Package: etechflow/module-vehicle-compat
• Magento: 2.4.4 – 2.4.8
• PHP: 8.1, 8.2, 8.3
• License: proprietary (see LICENSE.txt)
• Vendor: ETechFlow — https://etechflow.com

What's in the box

Two halves of one feature, intentionally bundled in one module:

Half 1 — Vehicle compatibility data

• vehicle_compat_data product attribute (JSON) storing every (Make, Model, Year) combination a product fits.
• parts_required product attribute (multi-select) tagging which part-types each product covers (key blade, transponder, immobilizer chip, etc.).
• Admin CRUD for Makes and Models under Catalog → Vehicles → Makes / Models.
• CSV import for bulk-loading vehicle compatibility data (bin/magento etechflow:vehiclecompat:import-parts).
• Product edit form modifier — a visual Make/Model/Year picker tab on every product, so the admin doesn't hand-edit JSON.

Half 2 — Part Finder widget

• /kvc/options/index — server-side filtered options endpoint. Each dropdown click sends field=make|model|year|part + current selections, server applies bidirectional filter and returns only matching options.
• /kvc/tree/index — full vehicle tree (cached, browser-cacheable for 1h).
• /kvc/find/index — find-parts results page that filters the catalog by the customer's vehicle.
• Shareable form fragment (ETechFlow_VehicleCompat::partfinder/form.phtml) that drops into any layout — header modal, hero section, PDP sidebar, all use the same template.
• Self-contained Alpine.js bootstrap — on Hyvä stores Alpine is already loaded; on Luma / custom themes the bootstrap lazy-loads Alpine from a CDN (URL is overridable for stores that want to self-host).
• Shared Alpine store so multiple form instances on the same page (desktop hero + mobile hero + header modal) stay in sync.

Theme compatibility

See COMPATIBILITY.md for the full audit.

Quick start

# 1. Extract into your Magento root
unzip etechflow-module-vehicle-compat-1.0.0.zip -d <magento-root>/

# 2. Enable + migrate (creates DB tables + product attributes)
cd <magento-root>
bin/magento module:enable ETechFlow_VehicleCompat
bin/magento setup:upgrade
bin/magento setup:di:compile      # production-mode only
bin/magento setup:static-content:deploy -f
bin/magento cache:flush

# 3. Visit the admin
open https://your-store.example.com/admin/etechflow_vehicle/make/index
# (Admin sidebar → Catalog → Vehicles → Makes / Models)

# 4. Embed the Part Finder on your homepage / header
#    Reference: USAGE.md → "Embedding the Part Finder form"

Documentation index

Support

• Email: [email protected]
• Include: Magento version, PHP version, active theme, sample product with vehicle data, screenshot.

License

proprietary — see LICENSE.txt.

Changelog — ETechFlow_VehicleCompat

1.0.0 — 2026-05-20

First public release as a standalone, theme-agnostic Magento 2 module.

Added

• Vehicle compatibility data
  • vehicle_compat_data product attribute (JSON) — Make / Model / Year tuples per product
  • parts_required multi-select product attribute
  • Admin Makes CRUD under Catalog → Vehicles → Makes
  • Admin Models CRUD under Catalog → Vehicles → Models
  • Product editor tab with visual Make/Model/Year picker (no hand-edited JSON)
  • CSV import command: bin/magento etechflow:vehiclecompat:import-parts
• Part Finder widget
  • Reusable form fragment (ETechFlow_VehicleCompat::partfinder/form.phtml) — embed anywhere
  • Server-side filtered options endpoint /kvc/options/index (bidirectional)
  • Full vehicle tree endpoint /kvc/tree/index (cached, browser-cacheable)
  • Find-parts results page /kvc/find/index with category chips
  • Shared Alpine store keeps multiple form instances in sync (header modal + hero + sidebar)
• Theme-agnostic JS bootstrap
  • alpine-bootstrap.js detects Alpine, lazy-loads it from CDN if absent
  • kvc-part-finder.js factory function — loaded once via layout XML
  • Both loaded on every storefront page via view/frontend/layout/default.xml
• Scoped namespaced CSS
  • .kvc-* class prefix prevents theme collisions
  • Inline <style> block in partfinder/styles.phtml
• Catalog filter integration
  • Plugin\Catalog\Layer\FilterByVehicle narrows product collections by ?make_id=&model_id=&year=&part_id= URL params
  • Plugin\Catalog\Block\HideLayeredNav hides the layered nav on /kvc/find/index pages
• Documentation bundle
  • README, INSTALL, USAGE, CONFIGURATION, COMPATIBILITY, CHANGELOG, UNINSTALL, LICENSE

Compatibility

• Magento 2.4.4 – 2.4.8
• PHP 8.1, 8.2, 8.3
• Hyvä Theme (native — Alpine global)
• Luma / Blank / custom themes (Alpine auto-loaded from CDN)
• Adobe Commerce + Magento Open Source + Mage-OS