System Overview

This document provides a high-level architectural overview of the Auth0 WordPress plugin, describing its core components, initialization patterns, and how different subsystems interact. The focus is on the plugin's structure and the relationships between major classes and subsystems.

For detailed information about specific subsystems:

• Plugin initialization lifecycle: see Plugin Initialization and Bootstrap
• Authentication flow details: see Authentication Flow
• Configuration system details: see Configuration Management
• Database schema: see Database Schema

Core Architecture

The Auth0 WordPress plugin is structured around several key architectural patterns:

1. Singleton Pattern: The wpAuth0() function provides global access to a single Plugin instance
2. Action-Based Architecture: Business logic is organized into action classes that register with WordPress hooks
3. SDK Delegation: The plugin wraps the Auth0-PHP SDK and delegates authentication operations to it
4. Lazy Initialization: Components are instantiated on-demand to minimize resource usage

System Component Diagram

Sources: wpAuth0.php79-89 src/Plugin.php21-330 src/Actions/Base.php16-122 src/Hooks.php7-63 src/Database.php9-149

Plugin Entry Point and Singleton Pattern

The plugin uses a singleton pattern implemented through the wpAuth0() global helper function. This function is the primary entry point for accessing plugin functionality throughout WordPress.

wpAuth0() Function Implementation

Function Location: wpAuth0.php79-89

The function signature is:

The null coalescing assignment operator ??= ensures the instance is created only once. Optional parameters allow dependency injection for testing purposes.

Sources: wpAuth0.php79-89

Plugin Class Structure

The Plugin class serves as the central orchestrator and maintains several key responsibilities:

Responsibility	Method	Description
SDK Management	getSdk()	Returns configured Auth0 SDK instance
Configuration	getConfiguration()	Returns SdkConfiguration object
Database Access	database()	Returns Database singleton
Action Registration	run()	Registers all action/filter classes
Hook Management	actions(), filters()	Returns Hooks singletons
Instance Registry	getClassInstance()	Manages action class instances

Sources: src/Plugin.php21-330

Plugin Constants and Class Registry

The Plugin class defines two critical constants that specify which action and filter classes to register:

Location: src/Plugin.php26-31

Sources: src/Plugin.php26-31

Action-Based Architecture

The plugin organizes business logic into action classes that inherit from Auth0\WordPress\Actions\Base. Each action class defines a registry of WordPress hooks it responds to.

Action Class Pattern

Sources: src/Actions/Base.php16-122 src/Actions/Authentication.php20-725 src/Actions/Configuration.php16-1279 src/Actions/Sync.php14-283

Action Registry Pattern

Each action class defines a $registry array that maps WordPress hook names to method names:

Authentication Action Registry: src/Actions/Authentication.php25-51

Configuration Action Registry: src/Actions/Configuration.php468-475

Sync Action Registry: src/Actions/Sync.php39-43

The array values can be either:

• A string (method name with 1 argument)
• An array [methodName, argumentCount] for hooks passing multiple arguments

Sources: src/Actions/Authentication.php25-51 src/Actions/Configuration.php468-475 src/Actions/Sync.php39-43

Base Class Methods

The Base class provides common functionality for all action classes:

Method	Purpose	Location
register()	Iterates through $registry and calls addAction()	src/Actions/Base.php89-96
addAction()	Registers callback with WordPress via Hooks	src/Actions/Base.php27-50
removeAction()	Unregisters callback from WordPress	src/Actions/Base.php98-121
getPlugin()	Returns Plugin instance	src/Actions/Base.php52-55
getSdk()	Returns Auth0 SDK instance	src/Actions/Base.php72-75
getPriority()	Gets hook priority (supports constants)	src/Actions/Base.php57-70

Sources: src/Actions/Base.php16-122

SDK Integration

The plugin wraps the Auth0-PHP SDK (Auth0\SDK\Auth0) and provides configuration through the SdkConfiguration class. The configuration is built from WordPress options stored in wp_options.

Configuration Building Process

Sources: src/Plugin.php98-103 src/Plugin.php274-329

Configuration Options Mapping

The importConfiguration() method maps WordPress options to SDK configuration parameters:

WordPress Option Group	Option Key	SDK Parameter	Line Reference
auth0_client	domain	domain	src/Plugin.php293-306
auth0_client	id	clientId	src/Plugin.php294-307
auth0_client	secret	clientSecret	src/Plugin.php295-308
auth0_client_advanced	custom_domain	customDomain	src/Plugin.php309
auth0_client_advanced	apis	audience	src/Plugin.php276-310
auth0_client_advanced	organizations	organization	src/Plugin.php277-311
auth0_cookies	secret	cookieSecret	src/Plugin.php312
auth0_cookies	domain	cookieDomain	src/Plugin.php313
auth0_cookies	path	cookiePath	src/Plugin.php314
auth0_cookies	ttl	cookieExpires	src/Plugin.php283-315
auth0_cookies	secure	cookieSecure	src/Plugin.php282-316
auth0_cookies	samesite	cookieSameSite	src/Plugin.php317

Sources: src/Plugin.php274-329

SDK Strategy Selection

The plugin uses different SDK strategies based on the execution context:

WP_Cron Context: src/Plugin.php285-298

• Strategy: SdkConfiguration::STRATEGY_NONE
• No session storage configured
• Used for background sync operations

Normal Context: src/Plugin.php300-320

• Strategy: SdkConfiguration::STRATEGY_REGULAR
• Full session management enabled
• Redirect URI: wp-login.php

Sources: src/Plugin.php285-320

Hooks System

The Hooks class provides a thin abstraction over WordPress's add_action() and add_filter() functions, supporting both hook types through a single interface.

Hooks Class Implementation

Sources: src/Hooks.php7-63

Hook Registration Flow

The Plugin::run() method orchestrates the registration of all action and filter classes:

Location: src/Plugin.php224-245

Sources: src/Plugin.php224-245 src/Actions/Base.php89-96 src/Hooks.php23-44

Database Layer

The Database class provides an abstraction layer over WordPress's global $wpdb object for plugin-specific database operations.

Database Table Constants

The plugin uses two custom tables defined by constants:

Constant	Value	Purpose	Schema Location
CONST_TABLE_ACCOUNTS	'accounts'	Maps WordPress users to Auth0 connections	src/Database.php14
CONST_TABLE_SYNC	'sync'	Event queue for background synchronization	src/Database.php29

Table Name Prefix: All tables are prefixed with wp_auth0_ (or the configured WordPress table prefix).

Sources: src/Database.php9-149

Database Class Methods

Method	Purpose	Return Type	Location
createTable($table)	Creates table if not exists	mixed	src/Database.php31-40
getTableName($table)	Returns prefixed table name	string	src/Database.php50-54
insertRow($table, $data, $formats)	Inserts row	int|bool	src/Database.php56-66
selectRow($select, $from, $query, $args)	Selects single row	array|object|null	src/Database.php90-99
selectResults($select, $from, $query, $args)	Selects multiple rows	array|object|null	src/Database.php79-88
selectDistinctResults(...)	Selects distinct rows	array|object|null	src/Database.php68-77
deleteRow($table, $where, $format)	Deletes rows	int|bool	src/Database.php42-48

Sources: src/Database.php9-149

Component Initialization Flow

The complete initialization sequence from plugin load to action registration:

Sources: wpAuth0.php1-90 src/Plugin.php224-245 src/Actions/Base.php89-96

Component Dependency Graph

This diagram shows how components access each other through the Plugin class:

Sources: wpAuth0.php79-89 src/Plugin.php21-330 src/Actions/Base.php52-75

Key Design Principles

The architecture implements several important design principles:

1. Lazy Initialization

Components like the SDK, configuration, and database are only instantiated when first accessed:

• Plugin::getSdk() src/Plugin.php164-169
• Plugin::getConfiguration() src/Plugin.php98-103
• Plugin::database() src/Plugin.php61-70

2. Singleton Pattern

Multiple singleton implementations ensure single instances:

• Global: wpAuth0() function wpAuth0.php79-89
• Per-Plugin: actions(), filters(), database() methods src/Plugin.php47-83

3. Dependency Injection

The Plugin class accepts optional dependencies for testability:

• Constructor: __construct(?Auth0 $auth0, ?SdkConfiguration $sdkConfiguration) src/Plugin.php38-42
• wpAuth0() parameters support override wpAuth0.php79-83

4. Registry Pattern

Action classes use declarative registries to define WordPress hook mappings:

• Base class processes registries uniformly src/Actions/Base.php89-96
• Each action defines its own $registry array src/Actions/Authentication.php25-51

5. Separation of Concerns

Clear boundaries between subsystems:

• Actions: Business logic and WordPress integration
• Plugin: Orchestration and dependency management
• Hooks: WordPress hook abstraction
• Database: Data persistence abstraction
• SDK: Auth0 API communication

Sources: src/Plugin.php21-330 src/Actions/Base.php16-122 src/Hooks.php7-63 src/Database.php9-149