13. phpMyFAQ Architecture & Class Diagrams
This document describes the architecture of the phpMyFAQ PHP backend
(phpmyfaq/src/phpMyFAQ) and visualizes the most important classes and their
relationships as Mermaid class diagrams.
Because the backend contains several hundred classes, a single flat diagram
would be unreadable. Instead the system is broken into its main subsystems, and
each gets a focused diagram showing the key classes, interfaces, inheritance,
and composition relationships. Helper, repository, and value-object classes are
included only where they clarify the design.
Notation: <|.. = implements interface, <|-- = extends class,
--> = uses / holds a reference (composition), ..> = creates (factory).
Table of Contents
- Subsystem Overview
- Request Lifecycle: Bootstrap, Kernel and Routing
- Database Abstraction Layer
- Authentication, User and Permission
- FAQ Domain Model
- Search Subsystem
- Export and Mail Subsystems
- Cross-Cutting Patterns
13.1 Subsystem Overview
phpMyFAQ is a request/response web application built on Symfony HttpKernel,
Symfony Routing (via PHP 8 #[Route] attributes), Twig templates, and a
home-grown database abstraction layer that supports MySQL, PostgreSQL, SQLite,
and SQL Server. Four entry points (index.php, admin/index.php,
api/index.php, admin/api/index.php) each boot a Kernel configured for a
different routing context.
flowchart TD
subgraph Entry["Entry Points"]
FE["index.php (public)"]
ADM["admin/index.php (admin)"]
API["api/index.php (api)"]
AAPI["admin/api/index.php (admin-api)"]
end
subgraph HTTP["HTTP / Kernel Layer"]
BOOT["Bootstrapper"]
KERNEL["Kernel (HttpKernelInterface)"]
ROUTING["Routing (attribute-based)"]
LISTENERS["EventListeners (request/controller/exception)"]
CTRL["Controllers (AbstractController)"]
end
subgraph Domain["Domain Services"]
FAQ["Faq / Category / News / Comments / Tags"]
SEARCH["Search"]
EXPORT["Export"]
USER["User / Auth / Permission"]
end
subgraph Infra["Infrastructure"]
CONFIG["Configuration"]
DB["DatabaseDriver"]
TWIG["TwigWrapper"]
MAIL["Mail"]
CACHE["Cache / Session"]
end
Entry --> BOOT --> KERNEL
KERNEL --> ROUTING
KERNEL --> LISTENERS --> CTRL
CTRL --> Domain
Domain --> CONFIG
CONFIG --> DB
CTRL --> TWIG
Domain --> MAIL
Domain --> CACHE
The Configuration object is the backbone of the system: nearly every
domain service receives it via constructor injection, and it in turn exposes the
active DatabaseDriver, the plugin manager, the logger, and grouped settings
objects (mail, search, security, LDAP, layout, URL).
13.2 Request Lifecycle: Bootstrap, Kernel and Routing
A request is bootstrapped, routed against attribute-defined routes, dispatched
through Symfony event listeners, and resolved to a controller that is fetched —
fully dependency-injected — from the DI container.
classDiagram
direction LR
class Bootstrapper {
+run() self
+getFaqConfig() Configuration
+getDb() DatabaseDriver
+getRequest() Request
}
class Kernel {
<<HttpKernelInterface>>
+__construct(routingContext, debug)
+boot() void
+handle(Request) Response
+getContainer() ContainerInterface
+getRoutingContext() string
}
class Environment {
+init()$ void
+isDebugMode()$ bool
+get(key, default)$ mixed
}
class Configuration {
+get(item) mixed
+set(key, value) bool
+getAll() array
+getDb() DatabaseDriver
+getPluginManager() PluginManager
+getConfigurationInstance()$ Configuration
}
class System {
+getVersion()$ string
+isUpdateNecessary(installedVersion)$ bool
+checkRequiredExtensions() bool
}
class RouteCollectionBuilder {
+build(context, attributesOnly) RouteCollection
}
class AttributeRouteLoader {
+load(controllerDir, context) RouteCollection
}
class RouteCacheManager {
+getRoutes(context, loader) RouteCollection
+clear() void
}
class ContainerControllerResolver {
+getController(Request) callable
}
class AbstractController {
<<abstract>>
+setContainer(ContainerInterface) void
+render(file, context) Response
+json(data, status) JsonResponse
+userIsAuthenticated() void
#userHasPermission(PermissionType) void
#verifySessionCsrfToken(page, token) bool
}
class RouterListener {
+onKernelRequest(RequestEvent) void
}
class LanguageListener {
+onKernelRequest(RequestEvent) void
}
class ControllerContainerListener {
+onKernelController(ControllerEvent) void
}
class ApiRateLimiterListener {
+onKernelRequest(RequestEvent) void
}
class ApiExceptionListener {
+onKernelException(ExceptionEvent) void
}
class WebExceptionListener {
+onKernelException(ExceptionEvent) void
}
class SecurityHeadersListener {
+onKernelResponse(ResponseEvent) void
}
Bootstrapper --> Configuration : builds
Bootstrapper --> Environment : initializes
Kernel --> RouteCollectionBuilder : loads routes
Kernel --> RouteCacheManager : caches routes
Kernel --> RouterListener : registers
Kernel --> LanguageListener : registers
Kernel --> ControllerContainerListener : registers
Kernel --> ApiRateLimiterListener : registers (api)
Kernel --> ApiExceptionListener : registers
Kernel --> WebExceptionListener : registers
Kernel --> SecurityHeadersListener : registers
Kernel --> ContainerControllerResolver : resolves with
RouteCollectionBuilder --> AttributeRouteLoader : delegates
ContainerControllerResolver --> AbstractController : fetches from container
ControllerContainerListener --> AbstractController : injects container
AbstractController --> Configuration : uses
System ..> Configuration : reads
Flow: index.php → src/Bootstrap.php (runs Bootstrapper::run()) →
new Kernel(routingContext, debug) → Kernel::handle(), which boots the kernel
on first use (Kernel::boot() builds or loads the cached container from
services.php and loads routes from cache or attributes) and dispatches the
Symfony kernel events:
LanguageListener (request, priority 300) initializes i18n.
RouterListener (request, priority 256) matches the URL to a route.
ApiRateLimiterListener (request, priority 150, api context only) enforces
rate limits.
ContainerControllerResolver fetches the controller from the DI container,
falling back to plain instantiation for unregistered controllers.
ControllerContainerListener (controller event) injects the shared
container into the AbstractController and enforces authentication for
every controller in the Administration namespace unless it implements
SkipsAuthenticationCheck.
- On error,
ApiExceptionListener (priority 0, RFC 7807 JSON) or
WebExceptionListener (priority -10, HTML error pages) produces the
response.
SecurityHeadersListener (response, priority -100) adds CSP and hardening
headers to HTML responses. Its script-src carries the per-request nonce of
ContentSecurityPolicyNonce instead of 'unsafe-inline'; the templates render the
same nonce into every inline <script> through the cspNonce() Twig function.
13.3 Database Abstraction Layer
All persistence goes through the DatabaseDriver interface. A static Database
factory instantiates the configured driver; native and PDO-based
implementations exist for every supported engine.
classDiagram
direction TB
class Database {
<<factory>>
+factory(type)$ DatabaseDriver
+getInstance()$ DatabaseDriver
+getType()$ string
+setTablePrefix(prefix)$ void
}
class DatabaseDriver {
<<interface>>
+connect(host, user, password, db, port) bool
+query(query, offset, rowcount) mixed
+escape(string) string
+fetchObject(result) mixed
+queryPrepared(query, params) mixed
+fetchAll(result) array
+numRows(result) int
+lastInsertId() int
}
class Mysqli
class Pgsql
class Sqlite3
class Sqlsrv
class PdoMysql
class PdoPgsql
class PdoSqlite
class PdoSqlsrv
class DatabaseHelper {
<<readonly>>
+alignTablePrefix(query, old, new)$ string
+buildInsertQueries(query, table) array
}
DatabaseDriver <|.. Mysqli
DatabaseDriver <|.. Pgsql
DatabaseDriver <|.. Sqlite3
DatabaseDriver <|.. Sqlsrv
DatabaseDriver <|.. PdoMysql
DatabaseDriver <|.. PdoPgsql
DatabaseDriver <|.. PdoSqlite
DatabaseDriver <|.. PdoSqlsrv
Database ..> DatabaseDriver : creates
DatabaseHelper --> Configuration : uses
Configuration --> DatabaseDriver : exposes
The native Mysqli, Pgsql, Sqlite3, and Sqlsrv drivers are deprecated in
favor of the PDO variants and scheduled for removal in phpMyFAQ 5.0.
13.4 Authentication, User and Permission
Authentication uses the strategy pattern: Auth::selectAuth() returns a
driver that extends Auth and implements AuthDriverInterface. A User
composes one or more auth drivers plus a PermissionInterface strategy.
CurrentUser extends User with session/cookie handling, login throttling, and
2FA. AuthWebAuthn extends Auth for passkey logins but is not an
AuthDriverInterface driver. For API requests, AuthChain tries session → API
key → OAuth2 (an optional callable set via setOAuth2Authenticator()) in turn.
classDiagram
direction TB
class AuthDriverInterface {
<<interface>>
+create(login, password, domain) mixed
+update(login, password) bool
+delete(login) bool
+checkCredentials(login, password, data) bool
+isValidLogin(login, data) int
}
class Auth {
+selectAuth(method) Auth
+getEncryptionContainer(type) Encryption
+encrypt(string) string
}
class AuthDatabase
class AuthLdap
class AuthSso
class AuthKeycloak
class AuthOidc
class AuthEntraId
class AuthHttp
class AuthWebAuthn
class PasswordHasher {
<<final>>
+hash(password) string
+verify(login, password, hash) bool
+needsRehash(hash) bool
}
class User {
+addPerm(PermissionInterface) bool
+addAuth(AuthDriverInterface, name) bool
+createUser(login, pass, domain, userId) bool
+getUserByLogin(login, raiseError) bool
+changePassword(pass) bool
+setStatus(status) bool
}
class CurrentUser {
+login(login, password) bool
+getFromSession(Configuration)$ CurrentUser
+getFromCookie(Configuration)$ CurrentUser
+deleteFromSession(deleteCookie) bool
+isLoggedIn() bool
+twoFactorSuccess() bool
}
class UserData {
+get(field) mixed
+set(field, value) bool
}
class UserSession {
+checkSessionId(sessionId, ipAddress) void
+userTracking(action, data) void
+setCookie(name, sessionId, timeout, strict) void
}
class AuthChain {
<<final>>
+authenticate(request, scopes) bool
+setOAuth2Authenticator(callable) void
+getAuthenticatedUserId() int
}
class ApiKeyAuthenticator {
<<final>>
+authenticate(request, scopes) bool
+getAuthenticatedUserId() int
}
class PermissionInterface {
<<interface>>
+hasPermission(userId, right) bool
+grantUserRight(userId, rightId) bool
+getRightData(rightId) array
}
class BasicPermission {
+checkUserRight(userId, rightId) bool
+refuseAllUserRights(userId) bool
+getAllUserRights(userId) array
}
class MediumPermission {
+grantGroupRight(groupId, rightId) bool
+addToGroup(userId, groupId) bool
+getGroupRights(groupId) array
}
AuthDriverInterface <|.. AuthDatabase
AuthDriverInterface <|.. AuthLdap
AuthDriverInterface <|.. AuthSso
AuthDriverInterface <|.. AuthKeycloak
AuthDriverInterface <|.. AuthOidc
AuthDriverInterface <|.. AuthEntraId
AuthDriverInterface <|.. AuthHttp
Auth <|-- AuthDatabase
Auth <|-- AuthLdap
Auth <|-- AuthSso
Auth <|-- AuthKeycloak
Auth <|-- AuthOidc
Auth <|-- AuthEntraId
Auth <|-- AuthHttp
Auth <|-- AuthWebAuthn
User <|-- CurrentUser
User --> PermissionInterface : composes
User --> AuthDriverInterface : auth container
User --> UserData : profile
CurrentUser --> UserSession : session and cookies
AuthDatabase --> PasswordHasher : uses
PermissionInterface <|.. BasicPermission
BasicPermission <|-- MediumPermission
AuthChain --> ApiKeyAuthenticator : chains
AuthChain --> CurrentUser : session auth
PermissionInterface has two implementations: BasicPermission (per-user
rights) and MediumPermission (adds group rights and group membership). Both are
backed by readonly repository classes (BasicPermissionRepository,
MediumPermissionRepository, GroupCategoryPermissionRepository).
13.5 FAQ Domain Model
The domain layer is service-oriented: each aggregate (Faq, Category,
News, …) is a service that operates on plain entity value objects from the
Entity\ namespace and persists through dedicated repositories (FaqRepository,
CategoryRepository, CommentsRepository, NewsRepository, …). The services
are largely independent of each other; controllers such as the frontend
FaqController combine them to build a page.
classDiagram
direction TB
class Faq {
+getFaq(faqId, revisionId, isAdmin) void
+getAllAvailableFaqsByCategoryId(id, ...) array
+create(FaqEntity) FaqEntity
+update(FaqEntity) FaqEntity
+delete(id, lang) bool
}
class Category {
+getOrderedCategories(...) array
+getCategoryData(id) CategoryEntity
+buildCategoryTree(id, depth) void
+getPath(id) array
}
class News {
<<readonly>>
+getAll(showArchive, active) array
+create(NewsMessage) bool
+update(NewsMessage) bool
}
class Comments {
+getCommentsData(referenceId, type) array
+create(Comment) bool
+delete(type, id) bool
}
class Tags {
+getAllTagsById(id) array
+create(id, tags) bool
+getPopularTags(limit) array
}
class Rating {
<<readonly>>
+get(id) string
+create(Vote) bool
}
class Visits {
<<readonly>>
+logViews(id) void
+add(id) bool
}
class Question {
<<readonly>>
+add(QuestionEntity) int
+getAll(showAll, language) array
}
class Glossary {
+insertItemsIntoContent(content) string
+fetchAll() array
}
class Bookmark {
+add(faqId) bool
+getAll() array
+remove(faqId) bool
}
class FaqEntity {
<<entity>>
-id : int
-language : string
-solutionId : int
-status : FaqStatus
-question : string
-answer : string
}
class CategoryEntity {
<<entity>>
-id : int
-parentId : int
-name : string
}
class Comment {
<<entity>>
-id : int
-type : string
-comment : string
}
class NewsMessage {
<<entity>>
}
class QuestionEntity {
<<entity>>
}
class Vote {
<<entity>>
}
class Tag {
<<entity>>
}
class FaqRepository
class FaqStatus {
<<enum>>
}
class PermissionType {
<<enum>>
}
class CommentType {
<<enum>>
}
class SeoType {
<<enum>>
}
Faq --> FaqEntity : reads/writes
Faq --> FaqRepository : persists via
Faq --> Category : category data
FaqEntity --> FaqStatus : typed by
Category --> CategoryEntity : reads/writes
Comments --> Comment : reads/writes
Comments --> CommentType : typed by
News --> NewsMessage : reads/writes
Question --> QuestionEntity : reads/writes
Rating --> Vote : reads/writes
Tags --> Tag : reads/writes
Bookmark --> CurrentUser : owner
Faq ..> Configuration : injected
Category ..> Configuration : injected
News ..> Configuration : injected
All services receive Configuration via the constructor (omitted from most
arrows above for clarity). Entities are fluent data containers with private
properties and getters/setters; enums such as FaqStatus, PermissionType,
AdminLogType, and SeoType (in Enums\) model fixed sets to keep illegal
states unrepresentable. CommentType lives in Entity\ and holds string
constants (CommentType::FAQ, …).
13.6 Search Subsystem
Search follows the strategy + factory pattern. The high-level Search
service routes to a database, Elasticsearch, or OpenSearch backend depending on
configuration; all three extend AbstractSearch and implement SearchInterface.
SearchResultSet post-processes hits, applying permission filtering.
classDiagram
direction TB
class SearchService {
<<final>>
+processSearch(input, tag, category, allLang, page) array
+shouldRedirectToSolutionId(input, num) bool
}
class Search {
+search(term, allLanguages) array
+autoComplete(term) array
+logSearchTerm(term) void
+getMostPopularSearches(num, withLang, window) array
}
class SearchInterface {
<<interface>>
+search(searchTerm) mixed
}
class AbstractSearch {
<<abstract>>
#resultSet
#configuration
}
class SearchDatabase {
+setTable(table) self
+setMatchingColumns(cols) self
+setConditions(conds) self
}
class Elasticsearch {
+autoComplete(term) array
+setCategoryIds(ids) void
}
class OpenSearch {
+autoComplete(term) array
+setCategoryIds(ids) void
}
class SearchFactory {
+create(config, handler)$ SearchDatabase
}
class SearchResultSet {
+reviewResultSet(set) void
+getResultSet() array
+getNumberOfResults() int
}
SearchInterface <|.. SearchDatabase
SearchInterface <|.. Elasticsearch
SearchInterface <|.. OpenSearch
AbstractSearch <|-- SearchDatabase
AbstractSearch <|-- Elasticsearch
AbstractSearch <|-- OpenSearch
SearchService --> Search : orchestrates
SearchService --> SearchResultSet : reviews hits
SearchService --> Faq : resolves
SearchService --> Category : resolves
Search --> SearchFactory : builds database backend
Search ..> Elasticsearch : creates
Search ..> OpenSearch : creates
SearchFactory ..> SearchDatabase : creates
SearchResultSet --> CurrentUser : permission filter
13.7 Export and Mail Subsystems
Export uses a static factory on the Export base class to produce a
Pdf or Json exporter. Mail separates two extension points: low-level
user agents (MailUserAgentInterface: SMTP, PHP mail()) and high-level
providers (MailProviderInterface: SendGrid, Mailgun, AWS SES).
classDiagram
direction TB
class Export {
+create(faq, cat, config, mode)$ Export
+getExportTimestamp()$ string
}
class Json {
+generate(categoryId, downwards, lang) string
}
class Pdf {
+generate(categoryId, downwards, lang) string
}
Export <|-- Json
Export <|-- Pdf
Export ..> Json : creates
Export ..> Pdf : creates
Pdf --> Wrapper : renders via
class Wrapper {
+Open() void
+SetDisplayMode(zoom) void
+Output(name, dest) string
}
class PdfEngineInterface {
<<interface>>
}
class TcpdfEngine
PdfEngineInterface <|.. TcpdfEngine
Wrapper --> PdfEngineInterface : uses
class Mail {
+addTo(address, name) bool
+send(forceSynchronousDelivery) int
}
class MailUserAgentInterface {
<<interface>>
+send(recipients, headers, body) int
}
class Smtp
class Builtin
class MailProviderInterface {
<<interface>>
+send(recipients, headers, body) int
}
class SendGridProvider
class MailgunProvider
class SesProvider
MailUserAgentInterface <|.. Smtp
MailUserAgentInterface <|.. Builtin
MailProviderInterface <|.. SendGridProvider
MailProviderInterface <|.. MailgunProvider
MailProviderInterface <|.. SesProvider
Mail --> MailUserAgentInterface : delegates
Mail --> MailProviderInterface : delegates
The Setup/Migration subsystem (not diagrammed here) follows the same
philosophy: a MigrationInterface / AbstractMigration hierarchy records
OperationInterface steps (SQL, config, file, permission operations) into an
OperationRecorder, executed or dry-run by MigrationExecutor against a
database-specific DialectInterface produced by DialectFactory.
13.8 Cross-Cutting Patterns
The codebase consistently applies a small set of design patterns. Recognizing
them makes the rest of the system predictable:
| Pattern |
Where |
Purpose |
| Factory |
Database::factory(), Auth::selectAuth(), Export::create(), SearchFactory, DialectFactory |
Pick a concrete implementation from configuration |
| Strategy |
DatabaseDriver, AuthDriverInterface, PermissionInterface, SearchInterface, MailUserAgentInterface |
Swap behavior behind a stable interface |
| Repository |
*Repository classes per domain service |
Isolate SQL from business logic |
| Entity / Value Object |
Entity\* |
Typed, fluent data containers |
| Chain of Responsibility |
AuthChain (session → API key → OAuth2) |
Try multiple authenticators in order |
| Event Listener |
*Listener on Symfony kernel events |
Cross-cutting request/exception handling |
| Dependency Injection |
services.php + Symfony container |
Constructor-wire all services and controllers |
| Builder / Fluent |
SearchDatabase, QueryBuilder, entity setters |
Stepwise, readable construction |
| Enum for fixed sets |
Enums\* (PermissionType, SeoType, …) |
Make illegal states unrepresentable |
Where to look in the code
| Concern |
Path |
| Bootstrap & kernel |
phpmyfaq/src/Bootstrap.php, phpmyfaq/src/phpMyFAQ/Bootstrapper.php, Kernel.php, Bootstrap/ |
| Event listeners |
phpmyfaq/src/phpMyFAQ/EventListener/ |
| Routing |
phpmyfaq/src/phpMyFAQ/Routing/, controller #[Route] attributes |
| Controllers |
phpmyfaq/src/phpMyFAQ/Controller/ |
| DI configuration |
phpmyfaq/src/services.php |
| Database |
phpmyfaq/src/phpMyFAQ/Database/ |
| Auth / User / Permission |
phpmyfaq/src/phpMyFAQ/Auth/, User/, Permission/ |
| Domain services |
phpmyfaq/src/phpMyFAQ/Faq.php, Category.php, News.php, … |
| Entities & enums |
phpmyfaq/src/phpMyFAQ/Entity/, Enums/ |
| Search |
phpmyfaq/src/phpMyFAQ/Search.php, Search/ |
| Export / Mail |
phpmyfaq/src/phpMyFAQ/Export.php, Export/, Mail.php, Mail/ |
| Setup / migrations |
phpmyfaq/src/phpMyFAQ/Setup/Migration/ |
| Plugins |
phpmyfaq/src/phpMyFAQ/Plugin/, phpmyfaq/content/plugins/ |
| Templating |
phpmyfaq/src/phpMyFAQ/Twig/, Template/ |
Generated from static analysis of the phpmyfaq/src/phpMyFAQ source tree.
Diagrams render automatically on GitHub and in any Mermaid-aware Markdown viewer.