Core Architecture

Relevant source files

Purpose and Scope

This document explains the foundational architectural patterns and design decisions that underpin the Multisite Language Switcher plugin. It covers the layered architecture, core design patterns, key classes, and how components interact during initialization and runtime.

For specific implementation details:

Plugin initialization sequence: see Plugin Initialization and Lifecycle
Blog collection management: see Blog Collection and Network Management
Options storage and retrieval: see Configuration and Options System
Content type routing: see Content Type Detection and Routing
Singleton management: see Registry Pattern and Singleton Management

Architectural Layers

The plugin employs a layered architecture that separates concerns and enables maintainability:

Sources: MultisiteLanguageSwitcher.php1-246 includes/MslsPlugin.php1-247 includes/MslsOptions.php1-433 includes/MslsOutput.php1-216

Layer Responsibilities

Layer	Primary Classes	Responsibility
Entry Point	`MultisiteLanguageSwitcher.php`	Define constants, autoload, register public API functions
Core	`MslsPlugin`, `MslsRegistry`	Initialize WordPress hooks, manage plugin lifecycle
Configuration	`MslsOptions`, `MslsBlogCollection`, `MslsContentTypes`	Store settings, discover network blogs, detect content types
Admin	`MslsAdmin`, `MslsMetaBox`, `MslsPostTag`, `MslsCustomColumn`	Render admin UI, handle form submissions
Output	`MslsOutput`, `MslsWidget`, `MslsBlock`	Generate frontend HTML, alternate links
Data	`MslsOptionsPost`, `MslsOptionsTax`, `MslsOptionsQuery`	Persist and retrieve translation relationships

Sources: includes/MslsPlugin.php34-100 includes/MslsAdmin.php43-68 includes/MslsOutput.php27-31

Core Design Patterns

Factory Pattern

The plugin uses the Factory pattern extensively to instantiate appropriate classes based on runtime context:

The MslsOptions::create() method determines context and returns the appropriate options subclass:

includes/MslsOptions.php83-107

Key decision points:

is_admin() - determines admin vs frontend context
msls_content_types()->is_taxonomy() - checks if current page is taxonomy
self::is_main_page() - checks for front page, search, or 404
self::is_tax_page() - checks for category, tag, or custom taxonomy
self::is_query_page() - checks for date, author, or post type archive

Sources: includes/MslsOptions.php76-134

Registry Pattern

MslsRegistry provides centralized singleton management for component instances:

The registry ensures that only one instance of each component exists per request. Classes like MslsAdmin and MslsMetaBox use MslsRegistry::get_object() and MslsRegistry::set_object() to manage their instances.

Sources: includes/MslsAdmin.php44-49 includes/MslsMetaBox.php80-92

Inheritance Hierarchy

The options system uses inheritance to share common functionality:

Each subclass overrides specific methods like get_postlink() and get_permalink() to provide context-specific URL generation.

Sources: includes/MslsOptions.php29-432 includes/MslsOptionsPost.php1-147 includes/MslsOptionsTax.php1-208

WordPress Integration Points

Hook Registration

MslsPlugin::init() registers WordPress hooks based on context:

Sources: includes/MslsPlugin.php34-100

WordPress Core Interaction

The plugin heavily utilizes WordPress Multisite functions:

Function	Purpose	Usage Location
`switch_to_blog()`	Change context to another blog	includes/MslsOutput.php66 includes/MslsBlog.php139
`restore_current_blog()`	Restore original blog context	includes/MslsOutput.php69 includes/MslsBlog.php145
`get_blogs_of_user()`	Get blogs accessible by user	includes/MslsBlogCollection.php136
`get_blog_option()`	Retrieve option from specific blog	includes/MslsBlogCollection.php111
`get_current_blog_id()`	Current blog ID	includes/MslsBlogCollection.php55

Sources: includes/MslsBlogCollection.php50-96 includes/MslsOutput.php47-103

Data Flow Architecture

Configuration Retrieval

The configuration system uses lazy initialization. The first call to msls_options() creates an instance that's reused for subsequent calls within the same request.

Sources: MultisiteLanguageSwitcher.php154-156 includes/MslsOptions.php138-143

Translation Link Storage

Translation relationships are stored as WordPress post meta or term meta:

Each post stores IDs of its translations indexed by language code. The MslsOptionsPost class manages this data using WordPress's post meta functions.

Sources: includes/MslsOptionsPost.php1-147 includes/MslsOptionsTax.php1-208

Public API Surface

The plugin exposes helper functions for theme and plugin integration:

API Functions:

Function	Return Type	Purpose
`msls_get_switcher(array $attr)`	`string`	Generate language switcher HTML
`msls_the_switcher(array $arr)`	`void`	Echo language switcher HTML
`msls_get_permalink(string $locale)`	`string`	Get translated post URL
`msls_blog(string $locale)`	`MslsBlog\|null`	Get blog object for locale
`msls_blog_collection()`	`MslsBlogCollection`	Get collection of all blogs
`msls_options()`	`MslsOptions`	Get plugin settings
`msls_output()`	`MslsOutput`	Get output generator

Sources: MultisiteLanguageSwitcher.php50-192

Extension Architecture

Filter Hooks

The plugin provides numerous filter hooks for customization:

Key filter hooks:

msls_get_output - Override entire output generation (includes/MslsPlugin.php50)
msls_options_get_permalink - Modify generated URLs (includes/MslsOptions.php226-230)
msls_blog_collection_construct - Filter blog list (includes/MslsBlogCollection.php70-73)
msls_admin_validate - Validate settings before save (includes/MslsAdmin.php458)

Sources: includes/MslsPlugin.php50 includes/MslsOptions.php218-233 includes/MslsBlogCollection.php63-73

Action Hooks

Action hooks enable extending functionality at specific lifecycle points:

Hook	Location	Purpose
`MSLS_REGISTER_ACTION`	includes/MslsAdmin.php29-238	Add custom settings sections
`msls_content_import_before_import`	ContentImport system	Execute before content import
`msls_content_import_after_import`	ContentImport system	Execute after content import

Sources: includes/MslsAdmin.php238

Multisite Context Management

Blog Switching Pattern

The plugin frequently switches between blog contexts to retrieve data:

This pattern is used extensively in:

MslsOutput::get() for generating language switcher links (includes/MslsOutput.php66-76)
MslsBlog::get_permalink() for URL generation (includes/MslsBlog.php139-145)
Content import operations

Critical Note: Every switch_to_blog() must be paired with restore_current_blog() to prevent context corruption.

Sources: includes/MslsOutput.php47-103 includes/MslsBlog.php121-148

Performance Optimization

SQL Caching

MslsSqlCacher implements query result caching:

The cacher uses WordPress's object cache to store query results, reducing database load for repeated queries across blogs.

Sources: includes/MslsSqlCacher.php1-100 (referenced in high-level diagrams)

Singleton Pattern

Many components use the singleton pattern via MslsRegistryInstance:

MslsBlogCollection::instance() - Single blog collection per request
MslsOptions::instance() - Single options instance per request
MslsContentTypes::create() - Cached content type detection

This ensures expensive operations (like blog discovery) occur only once per request.

Sources: includes/MslsBlogCollection.php10 includes/MslsOptions.php154-156

Error Handling and Validation

Admin Configuration Validation

The admin interface validates settings before persistence:

Validation steps:

Apply msls_admin_validate filter (includes/MslsAdmin.php458)
Cast display value to integer (includes/MslsAdmin.php460)
Sanitize image URL (includes/MslsAdmin.php461-463)
Update blog language (includes/MslsAdmin.php475-482)

Sources: includes/MslsAdmin.php450-483

Multisite Requirement Check

The plugin validates multisite activation and displays an error if not enabled:

includes/MslsPlugin.php82-99

Sources: includes/MslsPlugin.php39-100