DOCSEARCHbyAlgolia
Submit Docs

phpMyFAQ Documentation

repository·main·Indexed 20 days ago

https://github.com/thorsten/phpmyfaq

An open source, multilingual, and AI-ready FAQ web application for PHP 8.4+ (version 4.2.0-alpha). It features multi-database support (MariaDB, PostgreSQL, Azure SQL Edge), Elasticsearch/OpenSearch integration, a REST API documented via OpenAPI 3.0, and a robust plugin system. The documentation covers installation via official packages or GitHub source, Docker-based development using service profiles, E2E testing with Playwright, and administrative workflows for system upgrades and AI-powered page translation.

Tokens
51.6K
Snippets
136
Records
238
Agent score
70%

What's inside phpMyFAQ

  1. Overview of phpMyFAQ features and capabilities

    main

    phpMyFAQ is a database-driven, multilingual FAQ system. It is designed for high flexibility and can be deployed on standard web hosting or via Docker containers.

    Core Capabilities:

    • Content Management: Multi-language CMS with WYSIWYG editor, Image Manager, and wiki-like revision history.
    • Search: Real-time search capabilities using Elasticsearch or OpenSearch.
    • User Management: Multi-user functionality with group-based permissions for categories and FAQs, including support for 2FA and external identity providers (OpenLDAP, Microsoft Active Directory, Microsoft Entra ID, Keycloak).
    • Extensibility: Built-in plugin system, Twig-based responsive templates, and a REST API for external integration.
    • AI & Translation: AI-assisted translation via Google Cloud Translation, DeepL, Azure Translator, Amazon Translate, or LibreTranslate. Also includes an MCP Server for AI agents.
    • Security & Administration: Detailed activity logs, spam protection, and a backup system.

  2. Access phpMyFAQ Support and Resources

    main

    If you require assistance, documentation, or community support for phpMyFAQ, use the following official channels:

    For paid customization and professional support services, visit the official support page.

  3. View phpMyFAQ statistics and reports

    main

    phpMyFAQ provides several statistical tools to monitor content quality and user behavior:

    • Ratings: View average ratings (1-5) and vote counts for FAQs. Average ratings of 2 or worse are highlighted in red, while ratings above 4 are green.
    • View sessions: Track visitor IDs to reconstruct how users navigate your categories, content, and keywords.
    • Admin log: Audit all actions taken by users within the administration area to monitor system security.
    • Search statistics: Review reports on which keywords are being searched, including frequency, language, and overall percentage.
    • Reports: Generate custom reports by selecting specific data columns regarding content and usage. Reports can be exported as CSV files.

  4. Overview of AI-Assisted Translation

    main
    phpMyFAQ features an AI-assisted translation system that allows you to translate FAQ content, custom pages, categories, and news articles into multiple languages. The feature integrates with professional translation APIs and is designed to preserve HTML formatting (such as bold, links, and lists) within your content during the translation process.

  5. Supported Translation Providers

    main

    phpMyFAQ supports the following five translation providers:

    1. Google Cloud Translation: Neural machine translation with 100+ languages.
    2. DeepL: High-quality, natural-sounding translations (best for European languages).
    3. Azure Translator: Microsoft's service with 90+ languages.
    4. Amazon Translate: AWS translation service with 75+ languages.
    5. LibreTranslate: An open-source, self-hosted option for privacy and cost control.

  6. Integrate Custom Pages with Search and Sitemaps

    main

    Custom pages are automatically integrated into the system's search and sitemap features.

    Search Integration:

    • Database Search: Automatically indexed via title and content.
    • Elasticsearch/OpenSearch: Automatically indexed with content_type='page'. They have a priority of 0.80. Use Elasticsearch/OpenSearch → Import Data for bulk imports.
    • Visuals: Custom pages appear with a file-text icon (📄) in results.

    Sitemap Integration:

    • Only active pages (active='y') are included in the XML sitemap.
    • Priority is set to 0.80 (FAQs are 1.00).
    • URLs follow the format: https://example.com/page/{slug}.html.
    • Sitemaps are available at /sitemap.xml and /sitemap.xml.gz.

  7. Understand the FAQ Domain Model architecture

    main

    The domain layer follows a service-oriented architecture. Each major content aggregate (such as Faq, Category, or News) is implemented as a service. These services operate on plain entity value objects located in the Entity\ namespace and use dedicated repositories for persistence.

    Key characteristics:

    • Services as Hubs: The Faq service acts as a central hub, collaborating with other services like Comments, Tags, Rating, and Visits.
    • Entities: Classes in the Entity\ namespace (e.g., FaqEntity, CategoryEntity) are fluent data containers.
    • Enums: Fixed sets of values (e.g., PermissionType, SeoType, CommentType) are used to ensure type safety and prevent illegal states.
    • Dependency Injection: All services receive a Configuration object via their constructor.

  8. Manage group privileges and administration

    main

    In addition to individual users, phpMyFAQ allows you to manage permissions for groups.

    Important Rules:

    • Precedence: Permissions assigned to a group are rated higher than permissions assigned to an individual user.
    • Activation: To enable group permissions, you must change the permission level from basic to medium in the main configuration.

  9. Understand the phpMyFAQ Request Lifecycle

    main

    The request lifecycle follows a structured flow from entry point to response:

    1. Bootstrap: An entry point (e.g., index.php) calls Bootstrapper::run().
    2. Kernel Boot: Kernel::boot() initializes the DI container (from services.php) and loads routes via RouteCollectionBuilder.
    3. Request Handling: Kernel::handle(Request) dispatches Symfony kernel events in a specific order:
      • LanguageListener: Initializes internationalization (i18n).
      • RouterListener: Matches the URL to a route.
      • ApiRateLimiterListener: (API contexts only) Enforces rate limits.
      • ControllerContainerListener: Injects the shared container into the AbstractController and enforces admin authentication.
      • ContainerControllerResolver: Resolves and instantiates the controller.
    4. Response: On error, either ApiExceptionListener (returns RFC 7807 JSON) or WebExceptionListener (returns HTML) produces the response.

  10. How user resolution and account linking works in Keycloak integration

    main

    phpMyFAQ identifies and links Keycloak users to local accounts using the following priority order:

    1. Keycloak Subject (sub): The most durable link. If a local account is already linked to a specific Keycloak sub, that account is used.
    2. Preferred Username: The username provided by Keycloak.
    3. Email Address: The email address provided by Keycloak.
    4. Automatic Provisioning: If keycloak.autoProvision is enabled, a new local account is created if no match is found.

    Note: If keycloak.autoProvision is disabled, the user must already exist in phpMyFAQ (via email or username) before they can successfully sign in via Keycloak.

  11. Configure Database and Web Server Architecture

    main

    When editing docker-compose.prod.yml, you must select one option from each category by uncommenting the desired service and commenting out the others.

    Database Options

    • MariaDB (Recommended): Set PMF_DB_TYPE=mysqli and PMF_DB_HOST=mariadb.
    • PostgreSQL: Set PMF_DB_TYPE=pgsql and PMF_DB_HOST=postgres.

    Web Server Options

    • Apache + mod_php (Default): Simple setup with .htaccess support.
    • Nginx + PHP-FPM: Higher performance and lower memory footprint; requires manual nginx.conf for rules instead of .htaccess.
    • FrankenPHP: Modern server with HTTP/2, HTTP/3, and automatic HTTPS via Caddy.

  12. Manage Encrypted Attachments

    main

    phpMyFAQ supports encrypted attachments using the AES algorithm (via the mcrypt extension or native PHP Rijndael implementation).

    Critical Security Warnings

    • Encryption Key: Do not change the default attachment encryption key once files have been uploaded. If you change the key, all previously uploaded files will fail to decrypt. If a key change is necessary, you must re-upload all files.
    • Key Loss: Always memorize your encryption keys. There is no way to decrypt files without the correct key.
    • File Naming: Files are saved using a virtual hash based on tokens (key, issue ID, etc.). You cannot identify or access files directly via their original uploaded filenames.

    Performance and Storage

    • The mcrypt extension is strongly recommended for better performance.
    • Disabling encryption allows files to be saved unencrypted, which can save disk space by allowing identical files to be stored only once.