# magendoo/module-faq

> Magento 2 FAQ and Product Questions module — SEO-optimized FAQ pages, product Q&A tabs, ask-a-question forms, ratings, and admin knowledge base management.

`composer require magendoo/module-faq`

Canonical URL: https://packagento.com/magendoo/module-faq

## At a glance

- **Vendor**: magendoo (https://packagento.com/magendoo.md)
- **Latest version**: 1.0.0 — released 2026-04-13
- **Pricing**: Free
- **Package type**: Magento 2 module
- **Status**: active, accepting new buyers

## Installation

Packagento is licence-gated, so even free packages need a licence on a project before Composer can resolve them.

1. **Sign in or create an account** at https://packagento.com/customer/account/.

2. **Add the package to your account.** Open https://packagento.com/magendoo/module-faq and complete the free checkout. A licence is minted automatically.

3. **Create or pick a project, then activate the licence on it.**
   - Projects represent the Magento installs you deploy to. Manage them at https://packagento.com/projects/.
   - Activate the new licence on the project you'll deploy this package to. Activation is what generates the Composer credentials scoped to that project.

4. **Add the project credentials to your Magento codebase.**

   Grab the project's public + private key from https://packagento.com/projects/ (open the project, then its Credentials tab), and add them to `auth.json`:

   ```json
   {
     "http-basic": {
       "packagento.com": {
         "username": "ppk_live_...",
         "password": "psk_live_..."
       }
     }
   }
   ```

   Add the Packagento Composer repository to `composer.json`:

   ```json
   {
     "repositories": [
       { "type": "composer", "url": "https://packagento.com" }
     ]
   }
   ```

5. **Install and apply.**

   ```bash
   composer require magendoo/module-faq:*
   bin/magento setup:upgrade
   bin/magento setup:di:compile
   bin/magento cache:flush
   ```

## What it does

Magento 2 FAQ and Product Questions module — SEO-optimized FAQ pages, product Q&A tabs, ask-a-question forms, ratings, and admin knowledge base management.

## README

[![Magento 2](https://img.shields.io/badge/Magento-2.4.x-orange.svg)](https://magento.com)
[![PHP](https://img.shields.io/badge/PHP-8.0%2B-blue.svg)](https://php.net)
[![License](https://img.shields.io/badge/License-OSL--3.0-green.svg)](https://opensource.org/licenses/OSL-3.0)

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

![Product Page FAQ Tab](docs/magento2-catalog-faq-geo.png)

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

![Admin Question Editor](docs/magento2-catalog-faq-geo-edit.png)

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

![Admin Questions Grid](docs/magento2-catalog-faq-geo-list.png)

### 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](#requirements)
- [Installation](#installation--deployment)
- [Configuration](#configuration-reference)
- [For E-Commerce Managers](#for-e-commerce-managers-business-value)
- [For Developers](#for-developers-technical-architecture)
- [REST API](#rest-api-endpoints)
- [FAQ](#faq)
- [Use Cases](#use-cases)
- [Troubleshooting](#troubleshooting)
- [Changelog](#changelog)
- [License](#license)
- [Contributing](#contributing)
- [Support & Resources](#support--resources)

### Requirements

| Requirement | Version |
|-------------|---------|
| Magento | 2.4.x |
| PHP | 8.0+ |
| MySQL/MariaDB | 8.0+ / 10.4+ |
| Composer | 2.x |

#### Supported Magento Editions

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

---

### For E-Commerce Managers: Business Value

#### Reduce Support Costs, Increase Conversions

| Metric | Impact |
|--------|--------|
| **Support Tickets** | Proactive FAQ addressing reduces repetitive inquiries |
| **SEO Traffic** | Structured data and SEO-friendly URLs drive organic discovery |
| **Conversion Rate** | Product-specific Q&A removes purchase hesitation |
| **Customer Trust** | Social proof through ratings and helpfulness voting |
| **Content ROI** | Search analytics reveal knowledge gaps and content opportunities |

#### 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:

```
Api/
├── CategoryRepositoryInterface      # Category CRUD
├── QuestionRepositoryInterface      # Question CRUD  
├── QuestionManagementInterface      # Business operations
└── TagRepositoryInterface           # Tag CRUD
```

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:

_(README truncated for .md surface. Full README on https://packagento.com/magendoo/module-faq.)_

## Changelog

All notable changes to this project will be documented in this file.

The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
This project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).

### [Unreleased]

### [1.0.0] - 2026-04-13

#### Added
- SEO-optimized FAQ home page, category pages, and question pages with configurable URL prefix and suffix
- Custom frontend router for `faq/{category-slug}/{question-slug}` URL structure
- Product Questions tab on product detail pages (configurable tab name and position)
- Ask-a-Question form on product pages with guest/logged-in support and GDPR consent checkbox
- Answer helpfulness rating system (Yes/No, Voting, and Average Rating modes)
- Social share buttons on question pages (Facebook, Twitter, LinkedIn, Pinterest, Email)
- Admin grids and forms for FAQ Categories and FAQ Questions with full CRUD
- WYSIWYG editor for full answers; short answer field for listing previews
- Question workflow: Pending → Answered → Rejected status transitions
- Question visibility: Public, Logged-in only, Hidden
- 12 database tables: categories, questions, tags, ratings, search log, and M:N junction tables for stores, products, customer groups
- REST API: category CRUD (`/V1/faq/categories`), question CRUD (`/V1/faq/questions`), product questions, category questions, search, submit, rate
- URL rewrites generated on category/question save for SEO tool compatibility
- FAQPage JSON-LD structured data on category and question pages
- XML sitemap integration via `ItemProviderInterface`
- Hreflang tag support for multi-store setups
- Breadcrumbs with Home > FAQ > Category > Question hierarchy
- FAQ search with search terms report in admin
- Tag system with tag cloud and tag pages
- Three FAQ Widgets: Questions List, Categories List, Search Box
- Per-entity robots meta tag (noindex/nofollow) override
- Email notifications: admin notified on new question, customer notified on answer
- Customer group visibility restrictions on categories and questions
- Admin system configuration under Stores > Magendoo Extensions > FAQ and Product Questions
- CLI command `magendoo:faq:reindex` to regenerate URL rewrites
- i18n/en_US.csv translation file

[Unreleased]: https://github.com/magendooro/magento2-catalog-faq-geo/compare/v1.0.0...HEAD
[1.0.0]: https://github.com/magendooro/magento2-catalog-faq-geo/releases/tag/v1.0.0

## Recent Versions

| Version | Released |
|---|---|
| 1.0.0 | 2026-04-13 |

## Dependencies

### Require

| Package | Constraint |
|---|---|
| magento/framework | >=103.0.0 |
| magento/module-backend | >=102.0.0 |
| magento/module-catalog | >=104.0.0 |
| magento/module-cms | >=104.0.0 |
| magento/module-customer | >=103.0.0 |
| magento/module-store | >=101.0.0 |
| magento/module-ui | >=101.2.0 |
| magento/module-url-rewrite | >=102.0.0 |
| php | >=8.1 |

### Require (dev)

| Package | Constraint |
|---|---|
| phpstan/phpstan | ^1.10 \|\| ^2.0 |
| phpunit/phpunit | ^10.5 |

## Quality

Latest release (1.0.0) fails the Packagento QA pipeline. Verdicts below are per-cell (Magento line × PHP version) for the matrixed tools, and run-once for the static / security tiers.


### Compatibility

Each Magento line is installed on its supported PHP versions, then the module is built (DI compile + static-content deploy). Cells show passed / failed / untested; staircase gaps render as `–`.

| Magento | PHP 8.2 | PHP 8.3 | PHP 8.4 | PHP 8.5 |
|---|---|---|---|---|
| 2.4.7 | Pass | Pass | – | – |
| 2.4.8 | – | Pass | Pass | – |
| 2.4.9 | – | – | Pass | Pass |


### Code Quality

Advisory checks against the module's source. Never affect the Compatibility verdict — a phpcs finding can't make a module incompatible.

#### Static Analysis

Coding standards (phpcs), mess detection (phpmd), copy-pasted code (cpd), PHP cross-version compatibility, composer.json validity. Each runs once for the whole module.

| Tool | Status | Findings | Summary |
|---|---|---|---|
| PHPCS | Warning | 139 | 139 warnings (ruleset: Magento2), 86 auto-fixable with phpcbf |
| PHPMD | Warning | 77 | 77 rule violations (UnusedPrivateField:77) |
| Cpd | Warning | 3 | 3 duplicated chunks spanning 257 total lines (min-lines=5, min-tokens=70) |
| Composer validate | Info | 9 | valid; 9 advisory notes (composer validate --strict) |

#### PHPStan

Type-checks the module against a real Magento install. Re-runs per Magento + PHP version because resolvable symbols differ between releases.

| Magento | PHP 8.2 | PHP 8.3 | PHP 8.4 | PHP 8.5 |
|---|---|---|---|---|
| 2.4.7 | 49 | 49 | – | – |
| 2.4.8 | – | 49 | 49 | – |
| 2.4.9 | – | – | 49 | 49 |


### Tests

Unit and integration suites run per Magento + PHP cell. Test failures speak to the module's behaviour, not its compatibility with a line, so they're reported here separately.

#### Unit Tests

| Magento | PHP 8.2 | PHP 8.3 | PHP 8.4 | PHP 8.5 |
|---|---|---|---|---|
| 2.4.7 | N/A | N/A | – | – |
| 2.4.8 | – | N/A | N/A | – |
| 2.4.9 | – | – | N/A | N/A |

#### Integration Tests

| Magento | PHP 8.2 | PHP 8.3 | PHP 8.4 | PHP 8.5 |
|---|---|---|---|---|
| 2.4.7 | N/A | N/A | – | – |
| 2.4.8 | – | N/A | N/A | – |
| 2.4.9 | – | – | N/A | N/A |


### Security

Dependency-advisory audit (composer audit) plus a source malware scan. A malware detection fails the version outright.

| Tool | Status | Findings | Summary |
|---|---|---|---|
| Composer audit | Pass | 0 |  |
| Malware scan | Pass | 0 |  |

## Licence and pricing

Free. A licence is still minted on checkout and bound to your project for Composer access — no payment step.

Refundable within 14 days of first purchase via https://packagento.com/account/refunds/.

## Install via Claude Code or any MCP client

The Packagento MCP server can run the licence + project + Composer steps above in one tool call:

```
purchase_and_install_packages(
  composer_names=["magendoo/module-faq"],
  project_id="proj_xxx"
)
```

This handles cart, checkout, licence minting, project activation, and writes auth.json credentials. Connect a client with `claude mcp add packagento https://mcp.packagento.com`. Full setup at https://packagento.com/docs/mcp-setup.

## Vendor

magendoo is a Magento 2 vendor on Packagento. See https://packagento.com/magendoo.md for their full catalogue.