Download the PHP package magendoo/module-faq without Composer

Magendoo FAQ & Product Questions Module for Magento 2

A comprehensive FAQ and Product Questions management system for Magento 2 that transforms customer support into a conversion driver through SEO-optimized knowledge bases, product-specific Q&A, and customer engagement tools.

Screenshots

Product Page — FAQ tab with questions and "Ask a Question" form

Admin — Question editor with WYSIWYG answer, status workflow, and SEO fields

Admin — FAQ Questions grid with filtering, mass actions, and status management

Features

• 📚 Hierarchical FAQ Organization — Categories, tags, and product associations
• 🔍 Advanced Search & Analytics — Full-text search with search term reporting
• ⭐ Customer Engagement — Rating system (thumbs up/down, star ratings)
• 🔗 Product Page Integration — Dedicated FAQ tab on product detail pages
• 📱 Headless Ready — Full REST API coverage for PWA/GraphQL implementations
• 🔒 Security First — reCAPTCHA, GDPR compliance, ACL permissions
• 📈 SEO Optimized — Structured data, sitemap integration, clean URLs
• 🌍 Multi-Store Support — Store-specific content and customer group restrictions

Table of Contents

• Requirements
• Installation
• Configuration
• For E-Commerce Managers
• For Developers
• REST API
• FAQ
• Use Cases
• Troubleshooting
• Changelog
• License
• Contributing
• Support & Resources

Requirements

Supported Magento Editions

• ✅ Magento Open Source (Community)
• ✅ Adobe Commerce (Enterprise)
• ✅ Adobe Commerce Cloud

For E-Commerce Managers: Business Value

Reduce Support Costs, Increase Conversions

Core Business Features

📚 Hierarchical Knowledge Organization

• Categories — Organize FAQs by topic, product line, or customer journey stage
• Tags — Cross-reference questions for flexible discovery paths
• Product Association — Link specific questions directly to product pages
• Multi-Store — Tailor FAQs per storefront, language, or regional requirements

🔍 Intelligent Search & Discovery

• Full-text search across questions and answers
• Search term analytics dashboard — identify what customers can't find
• Configurable results ranking and pagination
• Search results with pagination and sorting

⭐ Customer Engagement & Social Proof

• Three Rating Modes:
  • Yes/No Helpfulness — "Was this answer helpful?"
  • Voting — Thumbs up/down with vote counts
  • Star Rating — Average 5-star rating display
• Social Sharing — Drive traffic via Facebook, Twitter, LinkedIn, Pinterest
• View Counts — Surface most-accessed content automatically

📧 Automated Communication Workflow

• Admin Notifications — Instant alerts for new customer questions
• Customer Follow-up — Automatic email when their question is answered
• Question Status Workflow:
  • Pending → Queue for review
  • Answered → Published to storefront
  • Rejected → Archived with note

🛡️ Compliance & Security

• GDPR Consent — Configurable consent checkbox for question submissions
• reCAPTCHA Integration — Native Magento reCAPTCHA v2/v3/invisible support
• Customer Group Restrictions — Show/hide content by B2B/B2C segments
• Visibility Controls — Public, logged-in-only, or hidden per question

📊 Analytics & Insights

• Search Terms Report — What are customers searching for?
• Rating analytics — Which answers are most/least helpful?
• View tracking — Content performance metrics
• Question submission trends — Identify emerging support topics

🔗 Product Page Integration

• Dedicated FAQ tab on product detail pages
• Configurable tab position and labeling
• "Ask a Question" form embedded in product context
• Shows only relevant Q&A for that specific product
• Reduces cart abandonment by addressing objections at point of decision

For Developers: Technical Architecture

Service Contract Architecture

The module implements Magento's Service Contract pattern for full API coverage and extensibility:

All repositories support:

• SearchCriteria pattern for flexible querying
• getByUrlKey() for SEO-friendly lookups
• Full extension through DI preferences and plugins

REST API Endpoints

Complete REST coverage for headless implementations:

24 endpoints total — 100% test coverage via Playwright.

Custom URL Router

Implements Magento\Framework\App\RouterInterface for clean SEO URLs:

Features:

• Configurable URL prefix per store
• Optional .html suffix
• Trailing slash normalization
• Automatic URL rewrite generation on entity save
• CLI command for bulk regeneration: bin/magento magendoo:faq:reindex

CLI Commands

CMS Widgets

Three widgets for embedding FAQ content on any CMS page via the admin widget inserter:

Database Schema (12 Tables)

Core Entities:

• magendoo_faq_category — Category data with SEO fields
• magendoo_faq_question — Question workflow, content, engagement metrics
• magendoo_faq_tag — Tag taxonomy

Relationship Tables:

• *_store — Multi-store visibility
• *_customer_group — Access control
• magendoo_faq_question_category — Many-to-many categories
• magendoo_faq_question_product — Product associations
• magendoo_faq_question_tag — Tag assignments

Analytics Tables:

• magendoo_faq_rating — Individual vote tracking (prevents duplicates)
• magendoo_faq_search_log — Search query analytics

SEO & Structured Data

Sitemap Integration:

• Implements Magento\Sitemap\Model\ItemProvider\ItemProviderInterface
• Automatic inclusion in sitemap.xml
• Configurable change frequency and priority per entity

Structured Data (Schema.org):

Meta Controls:

• Per-entity meta title, description
• Canonical URL override
• Noindex/nofollow per entity
• Robots meta for search results page

Extensibility Points

Events:

• Standard Magento events on save/load/delete
• Custom events for workflow transitions

Plugins:

• All public methods in repository interfaces
• Controller actions
• Block rendering

DI Preferences:

• All interfaces can be overridden
• Collection classes extensible

UI Components:

• Admin grids use Magento UI Component framework
• XML merge support for customization
• Custom column types available

Security Implementation

ACL Permissions (etc/acl.xml):

Form Security:

• Form key validation on all POST controllers
• CSRF protection on AJAX rating endpoints
• Input sanitization via Magento framework
• SQL injection prevention via prepared statements

Spam Prevention:

• reCAPTCHA observer on question submission
• IP-based duplicate vote prevention
• Customer ID tracking for authenticated users

Code Quality Standards

• PHP 8+ Features: Constructor property promotion, union types, match expressions
• Strict Typing: declare(strict_types=1) on all files
• Return Types: Explicit declarations on all methods
• Static Analysis Friendly: Full type coverage for IDE support
• PSR-12 Compliant: Standard Magento code formatting

Frontend Architecture

RequireJS Components:

Layout Handles:

Block Structure:

Admin Interface

UI Components:

• faq_category_listing — Category grid with mass actions
• faq_category_form — Category edit with store/group selectors
• faq_question_listing — Question grid with workflow filters
• faq_question_form — Question edit with associations
• faq_search_log_grid — Search analytics

Mass Actions:

• Delete, Change Status, Change Visibility for questions
• Delete, Change Status for categories

Configuration Reference

Path: magendoo_faq/general

Path: magendoo_faq/navigation

Path: magendoo_faq/product_page

Path: magendoo_faq/rating

Path: magendoo_faq/seo

Path: magendoo_faq/gdpr

Installation & Deployment

Composer Installation

Manual Installation

Uninstallation

To completely remove the module and its data:

⚠️ Warning: Uninstalling will permanently delete all FAQ categories, questions, tags, ratings, and search logs. Backup your database before proceeding.

Post-Installation Setup

1. Configure Module:

   • Navigate to: Stores → Configuration → Magendoo Extensions → FAQ
   • Set URL prefix, enable features per store view

2. Set Permissions:

   • Navigate to: System → Permissions → User Roles
   • Assign FAQ permissions to appropriate admin roles

3. Configure reCAPTCHA:

   • Navigate to: Stores → Configuration → Security → Google reCAPTCHA Storefront
   • Enable for "FAQ Question Submit" form

4. Configure Email Templates:

   • Navigate to: Marketing → Email Templates
   • Customize: Admin New Question, Customer Answer Notification
5. Create Initial Content:
   • Navigate to: Magendoo → FAQ → Categories → Create categories
   • Navigate to: Magendoo → FAQ → Questions → Create questions

FAQ

Q: Can customers submit questions without creating an account?

Yes, guest submissions can be enabled in configuration (magendoo_faq/general/allow_guest_questions). reCAPTCHA validation is recommended for anonymous submissions.

Q: Does this module work with Magento's Page Builder?

Yes, the module is compatible with Page Builder. You can link to FAQ pages or embed FAQ content using widgets (custom development may be required for specific Page Builder integrations).

Q: Can I migrate FAQs from another platform?

Yes! Use the built-in CLI import command with a CSV file:

The CSV header row must match the database column names. You can also use the REST API for programmatic imports.

Q: Is the FAQ content indexed by search engines?

Yes, the module includes:

• SEO-friendly URLs
• XML sitemap integration
• JSON-LD structured data (Schema.org FAQPage)
• Customizable meta titles and descriptions

Q: Can I restrict FAQs to specific customer groups?

Yes, both categories and questions support customer group restrictions. This is ideal for B2B scenarios where you want different content for wholesale vs. retail customers.

Q: Does the module support multiple languages?

Yes, full multi-store support allows you to create store-view-specific FAQs. Translation CSV files are included in i18n/.

Q: What rating systems are available?

Three rating modes:

• Yes/No — "Was this answer helpful?"
• Voting — Thumbs up/down with vote counts
• Average Rating — 5-star rating display

Q: How do I prevent spam submissions?

Enable reCAPTCHA in Stores → Configuration → Security → Google reCAPTCHA Storefront and select the "FAQ Question Submit" form.

Q: Can questions be associated with multiple categories?

Yes, questions support many-to-many relationships with categories for flexible organization.

Q: Is there a limit to the number of FAQs?

No hard limit. Performance depends on your server resources and database optimization.

Use Cases

Fashion E-Commerce

• Size guide FAQs by product category
• Care instructions linked to specific materials
• "Ask a Question" on product pages for fit inquiries
• Customer-submitted Q&A builds confidence in sizing

Electronics Retailer

• Technical specifications explained per product line
• Troubleshooting guides organized by symptom
• Warranty and return policy FAQs
• Product comparison questions and answers

B2B Wholesale

• Customer group restrictions show different FAQs for retail vs. wholesale
• Bulk ordering process documentation
• Payment term explanations per customer segment
• Account application Q&A

Multi-Regional Stores

• Store-specific FAQs for shipping policies by country
• Localized return procedures
• Currency and payment method guides
• Language-specific content management

Support & Extension

Extension Points

Create custom plugins in app/code/Vendor/Module/etc/di.xml:

Troubleshooting

Common Issues

FAQ URLs Return 404

Problem: FAQ pages show "404 Not Found" error.

Solutions:

1. Regenerate URL rewrites:

2. Check URL prefix configuration doesn't conflict with existing CMS pages
3. Verify web server rewrite rules are enabled:
   • Apache: .htaccess in root directory
   • Nginx: nginx.conf sample configuration
4. Flush Magento cache:

Admin Grid Not Loading

Problem: FAQ grid shows infinite loading spinner.

Solutions:

1. Check browser console for JavaScript errors
2. Verify file permissions on var/ and pub/ directories
3. Check var/log/system.log for PHP errors
4. Recompile static assets:

Questions Not Visible on Frontend

Problem: Questions exist in admin but don't appear on storefront.

Solutions:

1. Verify question status is set to Answered
2. Check visibility is set to Public (or Logged In if testing as customer)
3. Confirm store assignment in the question edit page
4. Check customer group restrictions don't exclude current user
5. Verify category association if viewing category-specific list
6. Clear cache and reindex:

Email Notifications Not Sending

Problem: Admin or customer notifications not received.

Solutions:

1. Check Magento email configuration: Stores → Configuration → Sales → Sales Emails
2. Verify cron is running: bin/magento cron:run
3. Check email templates are configured correctly
4. Review var/log/exception.log for email errors
5. Test with a simple PHP mail script to verify server email capability

reCAPTCHA Not Working

Problem: "Ask Question" form submits without reCAPTCHA validation.

Solutions:

1. Verify reCAPTCHA keys are configured: Stores → Configuration → Security → Google reCAPTCHA Storefront
2. Ensure form key magendoo_faq_question_submit is enabled
3. Check JavaScript console for reCAPTCHA loading errors
4. Verify domain is registered in Google reCAPTCHA admin console

Product Tab Not Showing

Problem: FAQ tab missing on product detail pages.

Solutions:

1. Verify module is enabled in product page config: Stores → Configuration → Magendoo Extensions → FAQ → Product Page → Enabled
2. Check if questions are associated with the product
3. Ensure layout XML is loaded (check for theme overrides)
4. Verify tab position doesn't conflict with other tabs

Getting Help

1. Check Logs: Review var/log/system.log and var/log/exception.log

2. Enable Developer Mode: Temporarily switch to developer mode for detailed errors:

3. Contact Support: Create an issue on GitHub for assistance

Changelog

[1.2.0] - 2026-04-13

Phase 3+4 Features

• FAQ CMS Widgets — Questions List (list/accordion), Categories List, Search Box
• Tag system frontend — tag cloud, tag pages with linked questions, Router support
• Search autocomplete — AJAX suggest endpoint + JS dropdown on FAQ home
• CSV Import/Export CLI — magendoo:faq:export and magendoo:faq:import
• Product tab deep-link fix — #product_faq hash now reliably opens the tab
• Complete REST API — 24 endpoints with 100% test coverage
• Tag CRUD API + URL-key lookups + view count + notification endpoints

[1.1.0] - 2026-04-12

Phase 2 + SEO Sprint

• Ask a Question form on product pages (guest + logged-in)
• reCAPTCHA integration via Magento's native framework
• GDPR consent checkbox with configurable text
• Email notifications (admin new question + customer answer)
• Rating system — 3 modes (Yes/No, Voting, Average Stars)
• Social share buttons (Facebook, Twitter, LinkedIn, Pinterest, Email)
• Structured data JSON-LD (FAQPage schema) on question + category pages
• Robots meta per entity (noindex/nofollow from DB fields)
• XML Sitemap integration via ItemProviderInterface
• Search terms logging + admin report
• Hreflang tags for multi-store SEO
• Customer group visibility filtering on all frontend surfaces
• Product/category assignment in admin question form

[1.0.0] - 2026-04-10

Initial Release (Phase 1 MVP)

• 12 database tables with declarative schema
• FAQ category + question + tag management (admin CRUD)
• Product page FAQ tab integration
• Custom URL router with SEO-friendly paths
• Full-text search with pagination
• REST API (category + question CRUD)
• ACL permissions, admin menu, system configuration
• URL rewrite generation + CLI reindex command
• Multi-store support via junction tables

License

This module is licensed under the Open Software License v. 3.0 (OSL-3.0).

See https://opensource.org/licenses/OSL-3.0 for the full license text.

Contributing

Contributions are welcome! Please follow these guidelines:

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

Please ensure your code:

• Follows PSR-12 coding standards
• Includes proper PHPDoc comments
• Uses strict typing (declare(strict_types=1))
• Includes unit tests where applicable

Support & Resources

• Issue Tracker: https://github.com/magendooro/magento2-catalog-faq-geo/issues
• Implementation & Customization Services: [email protected]

Summary

Magendoo_Faq delivers enterprise-grade FAQ management that scales from single-store boutiques to multi-store, multi-region B2B/B2C operations. With full API coverage for headless implementations, comprehensive SEO features for organic traffic growth, and deep product page integration for conversion optimization, it transforms static FAQ pages into dynamic, customer-driven knowledge platforms.

Key Differentiators:

• ✅ Full REST API for PWA/headless implementations
• ✅ Product-specific Q&A to reduce purchase hesitation
• ✅ Advanced SEO with structured data and sitemap integration
• ✅ Customer engagement through ratings and social sharing
• ✅ Enterprise access control (multi-store, customer groups)
• ✅ GDPR-compliant with native reCAPTCHA integration
• ✅ Analytics-driven content insights