feat: Add persistent storage support for Redis and APCu (v0.4.0)

- Add StorageFactory class for storage adapter selection with fallback
- Support Redis storage for shared metrics across instances
- Support APCu storage for high-performance single-server deployments
- Add Storage tab in admin settings with configuration UI
- Add connection testing for Redis and APCu adapters
- Support environment variables for Docker/containerized deployments
- Update Collector to use StorageFactory instead of hardcoded InMemory
- Add all translations (English and German)

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

src/Admin/Settings.php

@@ -10,6 +10,7 @@ namespace Magdev\WpPrometheus\Admin;
 use Magdev\WpPrometheus\License\Manager as LicenseManager;
 use Magdev\WpPrometheus\Metrics\CustomMetricBuilder;
 use Magdev\WpPrometheus\Metrics\RuntimeCollector;
+use Magdev\WpPrometheus\Metrics\StorageFactory;
 
 // Prevent direct file access.
 if ( ! defined( 'ABSPATH' ) ) {
@@ -51,6 +52,7 @@ class Settings {
 		$this->tabs = array(
 			'license'    => __( 'License', 'wp-prometheus' ),
 			'metrics'    => __( 'Metrics', 'wp-prometheus' ),
+			'storage'    => __( 'Storage', 'wp-prometheus' ),
 			'custom'     => __( 'Custom Metrics', 'wp-prometheus' ),
 			'dashboards' => __( 'Dashboards', 'wp-prometheus' ),
 			'help'       => __( 'Help', 'wp-prometheus' ),
@@ -70,6 +72,8 @@ class Settings {
 		add_action( 'wp_ajax_wp_prometheus_import_metrics', array( $this, 'ajax_import_metrics' ) );
 		add_action( 'wp_ajax_wp_prometheus_download_dashboard', array( $this, 'ajax_download_dashboard' ) );
 		add_action( 'wp_ajax_wp_prometheus_reset_runtime_metrics', array( $this, 'ajax_reset_runtime_metrics' ) );
+		add_action( 'wp_ajax_wp_prometheus_save_storage', array( $this, 'ajax_save_storage' ) );
+		add_action( 'wp_ajax_wp_prometheus_test_storage', array( $this, 'ajax_test_storage' ) );
 	}
 
 	/**
@@ -183,6 +187,7 @@ class Settings {
 			'importNonce'            => wp_create_nonce( 'wp_prometheus_import' ),
 			'dashboardNonce'         => wp_create_nonce( 'wp_prometheus_dashboard' ),
 			'resetRuntimeNonce'      => wp_create_nonce( 'wp_prometheus_reset_runtime' ),
+			'storageNonce'           => wp_create_nonce( 'wp_prometheus_storage' ),
 			'confirmDelete'          => __( 'Are you sure you want to delete this metric?', 'wp-prometheus' ),
 			'confirmReset'           => __( 'Are you sure you want to reset all runtime metrics? This cannot be undone.', 'wp-prometheus' ),
 			'confirmRegenerateToken' => __( 'Are you sure you want to regenerate the auth token? You will need to update your Prometheus configuration.', 'wp-prometheus' ),
@@ -226,6 +231,9 @@ class Settings {
 					case 'metrics':
 						$this->render_metrics_tab();
 						break;
+					case 'storage':
+						$this->render_storage_tab();
+						break;
 					case 'custom':
 						$this->render_custom_metrics_tab();
 						break;
@@ -415,6 +423,282 @@ class Settings {
 		<?php
 	}
 
+	/**
+	 * Render storage tab content.
+	 *
+	 * @return void
+	 */
+	private function render_storage_tab(): void {
+		$configured_adapter = StorageFactory::get_configured_adapter();
+		$active_adapter     = StorageFactory::get_active_adapter();
+		$last_error         = StorageFactory::get_last_error();
+		$redis_config       = StorageFactory::get_redis_config();
+		$apcu_prefix        = StorageFactory::get_apcu_prefix();
+		$adapters           = StorageFactory::get_available_adapters();
+
+		// Check environment variable overrides.
+		$env_override = false !== getenv( 'WP_PROMETHEUS_STORAGE_ADAPTER' );
+		?>
+		<div class="wp-prometheus-storage">
+			<h2><?php esc_html_e( 'Metrics Storage Configuration', 'wp-prometheus' ); ?></h2>
+			<p class="description">
+				<?php esc_html_e( 'Configure how Prometheus metrics are stored. Persistent storage (Redis, APCu) allows metrics to survive between requests and aggregate data over time.', 'wp-prometheus' ); ?>
+			</p>
+
+			<?php if ( $env_override ) : ?>
+				<div class="notice notice-info" style="padding: 12px; margin: 15px 0;">
+					<strong><?php esc_html_e( 'Environment Override Active', 'wp-prometheus' ); ?></strong>
+					<p><?php esc_html_e( 'Storage adapter is configured via environment variable. Admin settings will be ignored.', 'wp-prometheus' ); ?></p>
+				</div>
+			<?php endif; ?>
+
+			<?php if ( ! empty( $last_error ) ) : ?>
+				<div class="notice notice-warning" style="padding: 12px; margin: 15px 0;">
+					<strong><?php esc_html_e( 'Storage Fallback Active', 'wp-prometheus' ); ?></strong>
+					<p><?php echo esc_html( $last_error ); ?></p>
+					<p><?php esc_html_e( 'Falling back to In-Memory storage.', 'wp-prometheus' ); ?></p>
+				</div>
+			<?php endif; ?>
+
+			<div class="notice notice-<?php echo $active_adapter === $configured_adapter && empty( $last_error ) ? 'success' : 'warning'; ?>" style="padding: 12px; margin: 15px 0;">
+				<strong><?php esc_html_e( 'Current Status:', 'wp-prometheus' ); ?></strong>
+				<?php
+				printf(
+					/* translators: %s: Active adapter name */
+					esc_html__( 'Using %s storage.', 'wp-prometheus' ),
+					'<code>' . esc_html( ucfirst( $active_adapter ) ) . '</code>'
+				);
+				?>
+			</div>
+
+			<form id="wp-prometheus-storage-form">
+				<table class="form-table" role="presentation">
+					<tr>
+						<th scope="row">
+							<label for="storage-adapter"><?php esc_html_e( 'Storage Adapter', 'wp-prometheus' ); ?></label>
+						</th>
+						<td>
+							<select name="adapter" id="storage-adapter" <?php disabled( $env_override ); ?>>
+								<?php foreach ( $adapters as $key => $label ) : ?>
+									<option value="<?php echo esc_attr( $key ); ?>" <?php selected( $configured_adapter, $key ); ?>>
+										<?php echo esc_html( $label ); ?>
+										<?php if ( ! StorageFactory::is_adapter_available( $key ) && 'inmemory' !== $key ) : ?>
+											(<?php esc_html_e( 'unavailable', 'wp-prometheus' ); ?>)
+										<?php endif; ?>
+									</option>
+								<?php endforeach; ?>
+							</select>
+							<p class="description">
+								<?php esc_html_e( 'Select the storage backend for metrics. Redis and APCu require their respective PHP extensions.', 'wp-prometheus' ); ?>
+							</p>
+						</td>
+					</tr>
+				</table>
+
+				<div id="redis-config" style="<?php echo 'redis' === $configured_adapter ? '' : 'display: none;'; ?>">
+					<h3><?php esc_html_e( 'Redis Configuration', 'wp-prometheus' ); ?></h3>
+					<table class="form-table" role="presentation">
+						<tr>
+							<th scope="row">
+								<label for="redis-host"><?php esc_html_e( 'Host', 'wp-prometheus' ); ?></label>
+							</th>
+							<td>
+								<input type="text" name="redis_host" id="redis-host" class="regular-text"
+									   value="<?php echo esc_attr( $redis_config['host'] ); ?>"
+									   placeholder="127.0.0.1">
+								<p class="description">
+									<?php
+									printf(
+										/* translators: %s: Environment variable name */
+										esc_html__( 'Can be overridden with %s environment variable.', 'wp-prometheus' ),
+										'<code>WP_PROMETHEUS_REDIS_HOST</code>'
+									);
+									?>
+								</p>
+							</td>
+						</tr>
+						<tr>
+							<th scope="row">
+								<label for="redis-port"><?php esc_html_e( 'Port', 'wp-prometheus' ); ?></label>
+							</th>
+							<td>
+								<input type="number" name="redis_port" id="redis-port" class="small-text"
+									   value="<?php echo esc_attr( $redis_config['port'] ); ?>"
+									   placeholder="6379" min="1" max="65535">
+								<p class="description">
+									<?php
+									printf(
+										/* translators: %s: Environment variable name */
+										esc_html__( 'Can be overridden with %s environment variable.', 'wp-prometheus' ),
+										'<code>WP_PROMETHEUS_REDIS_PORT</code>'
+									);
+									?>
+								</p>
+							</td>
+						</tr>
+						<tr>
+							<th scope="row">
+								<label for="redis-password"><?php esc_html_e( 'Password', 'wp-prometheus' ); ?></label>
+							</th>
+							<td>
+								<input type="password" name="redis_password" id="redis-password" class="regular-text"
+									   value="<?php echo esc_attr( $redis_config['password'] ); ?>"
+									   placeholder="<?php esc_attr_e( 'Leave empty if not required', 'wp-prometheus' ); ?>">
+								<p class="description">
+									<?php
+									printf(
+										/* translators: %s: Environment variable name */
+										esc_html__( 'Can be overridden with %s environment variable.', 'wp-prometheus' ),
+										'<code>WP_PROMETHEUS_REDIS_PASSWORD</code>'
+									);
+									?>
+								</p>
+							</td>
+						</tr>
+						<tr>
+							<th scope="row">
+								<label for="redis-database"><?php esc_html_e( 'Database', 'wp-prometheus' ); ?></label>
+							</th>
+							<td>
+								<input type="number" name="redis_database" id="redis-database" class="small-text"
+									   value="<?php echo esc_attr( $redis_config['database'] ); ?>"
+									   placeholder="0" min="0" max="15">
+								<p class="description">
+									<?php
+									printf(
+										/* translators: %s: Environment variable name */
+										esc_html__( 'Redis database index (0-15). Can be overridden with %s.', 'wp-prometheus' ),
+										'<code>WP_PROMETHEUS_REDIS_DATABASE</code>'
+									);
+									?>
+								</p>
+							</td>
+						</tr>
+						<tr>
+							<th scope="row">
+								<label for="redis-prefix"><?php esc_html_e( 'Key Prefix', 'wp-prometheus' ); ?></label>
+							</th>
+							<td>
+								<input type="text" name="redis_prefix" id="redis-prefix" class="regular-text"
+									   value="<?php echo esc_attr( $redis_config['prefix'] ); ?>"
+									   placeholder="WORDPRESS_PROMETHEUS_">
+								<p class="description">
+									<?php esc_html_e( 'Prefix for Redis keys. Useful when sharing Redis with other applications.', 'wp-prometheus' ); ?>
+								</p>
+							</td>
+						</tr>
+					</table>
+				</div>
+
+				<div id="apcu-config" style="<?php echo 'apcu' === $configured_adapter ? '' : 'display: none;'; ?>">
+					<h3><?php esc_html_e( 'APCu Configuration', 'wp-prometheus' ); ?></h3>
+					<table class="form-table" role="presentation">
+						<tr>
+							<th scope="row">
+								<label for="apcu-prefix"><?php esc_html_e( 'Key Prefix', 'wp-prometheus' ); ?></label>
+							</th>
+							<td>
+								<input type="text" name="apcu_prefix" id="apcu-prefix" class="regular-text"
+									   value="<?php echo esc_attr( $apcu_prefix ); ?>"
+									   placeholder="wp_prom">
+								<p class="description">
+									<?php
+									printf(
+										/* translators: %s: Environment variable name */
+										esc_html__( 'Prefix for APCu keys. Can be overridden with %s.', 'wp-prometheus' ),
+										'<code>WP_PROMETHEUS_APCU_PREFIX</code>'
+									);
+									?>
+								</p>
+							</td>
+						</tr>
+					</table>
+				</div>
+
+				<p class="submit">
+					<button type="submit" class="button button-primary" <?php disabled( $env_override ); ?>>
+						<?php esc_html_e( 'Save Storage Settings', 'wp-prometheus' ); ?>
+					</button>
+					<button type="button" id="test-storage" class="button button-secondary">
+						<?php esc_html_e( 'Test Connection', 'wp-prometheus' ); ?>
+					</button>
+					<span id="wp-prometheus-storage-spinner" class="spinner" style="float: none;"></span>
+				</p>
+			</form>
+
+			<div id="wp-prometheus-storage-message" style="display: none; margin-top: 10px;"></div>
+
+			<hr style="margin: 30px 0;">
+
+			<h3><?php esc_html_e( 'Environment Variables', 'wp-prometheus' ); ?></h3>
+			<p class="description">
+				<?php esc_html_e( 'For Docker or containerized environments, you can configure storage using environment variables. These take precedence over admin settings.', 'wp-prometheus' ); ?>
+			</p>
+
+			<table class="widefat striped" style="margin: 15px 0; max-width: 800px;">
+				<thead>
+					<tr>
+						<th><?php esc_html_e( 'Variable', 'wp-prometheus' ); ?></th>
+						<th><?php esc_html_e( 'Description', 'wp-prometheus' ); ?></th>
+						<th><?php esc_html_e( 'Example', 'wp-prometheus' ); ?></th>
+					</tr>
+				</thead>
+				<tbody>
+					<tr>
+						<td><code>WP_PROMETHEUS_STORAGE_ADAPTER</code></td>
+						<td><?php esc_html_e( 'Storage adapter to use', 'wp-prometheus' ); ?></td>
+						<td><code>redis</code></td>
+					</tr>
+					<tr>
+						<td><code>WP_PROMETHEUS_REDIS_HOST</code></td>
+						<td><?php esc_html_e( 'Redis server hostname', 'wp-prometheus' ); ?></td>
+						<td><code>redis</code></td>
+					</tr>
+					<tr>
+						<td><code>WP_PROMETHEUS_REDIS_PORT</code></td>
+						<td><?php esc_html_e( 'Redis server port', 'wp-prometheus' ); ?></td>
+						<td><code>6379</code></td>
+					</tr>
+					<tr>
+						<td><code>WP_PROMETHEUS_REDIS_PASSWORD</code></td>
+						<td><?php esc_html_e( 'Redis authentication password', 'wp-prometheus' ); ?></td>
+						<td><code>secret123</code></td>
+					</tr>
+					<tr>
+						<td><code>WP_PROMETHEUS_REDIS_DATABASE</code></td>
+						<td><?php esc_html_e( 'Redis database index', 'wp-prometheus' ); ?></td>
+						<td><code>0</code></td>
+					</tr>
+					<tr>
+						<td><code>WP_PROMETHEUS_REDIS_PREFIX</code></td>
+						<td><?php esc_html_e( 'Redis key prefix', 'wp-prometheus' ); ?></td>
+						<td><code>MYSITE_PROM_</code></td>
+					</tr>
+					<tr>
+						<td><code>WP_PROMETHEUS_APCU_PREFIX</code></td>
+						<td><?php esc_html_e( 'APCu key prefix', 'wp-prometheus' ); ?></td>
+						<td><code>wp_prom</code></td>
+					</tr>
+				</tbody>
+			</table>
+
+			<h4><?php esc_html_e( 'Docker Compose Example', 'wp-prometheus' ); ?></h4>
+			<pre style="background: #f1f1f1; padding: 15px; overflow-x: auto; margin: 15px 0;">services:
+  wordpress:
+    image: wordpress:latest
+    environment:
+      WP_PROMETHEUS_STORAGE_ADAPTER: redis
+      WP_PROMETHEUS_REDIS_HOST: redis
+      WP_PROMETHEUS_REDIS_PORT: 6379
+    depends_on:
+      - redis
+
+  redis:
+    image: redis:alpine</pre>
+		</div>
+		<?php
+	}
+
 	/**
 	 * Render custom metrics tab content.
 	 *
@@ -872,6 +1156,38 @@ class Settings {
     );
     $gauge->set( 42, array( 'value1', 'value2' ) );
 } );</pre>
+
+		<h3><?php esc_html_e( 'Storage Backends', 'wp-prometheus' ); ?></h3>
+		<p><?php esc_html_e( 'The plugin supports multiple storage backends for metrics persistence:', 'wp-prometheus' ); ?></p>
+		<table class="widefat striped" style="margin: 15px 0;">
+			<thead>
+				<tr>
+					<th><?php esc_html_e( 'Adapter', 'wp-prometheus' ); ?></th>
+					<th><?php esc_html_e( 'Description', 'wp-prometheus' ); ?></th>
+					<th><?php esc_html_e( 'Use Case', 'wp-prometheus' ); ?></th>
+				</tr>
+			</thead>
+			<tbody>
+				<tr>
+					<td><strong>In-Memory</strong></td>
+					<td><?php esc_html_e( 'Default storage, no persistence between requests', 'wp-prometheus' ); ?></td>
+					<td><?php esc_html_e( 'Development, testing', 'wp-prometheus' ); ?></td>
+				</tr>
+				<tr>
+					<td><strong>Redis</strong></td>
+					<td><?php esc_html_e( 'Shared storage, survives restarts', 'wp-prometheus' ); ?></td>
+					<td><?php esc_html_e( 'Production, load-balanced environments', 'wp-prometheus' ); ?></td>
+				</tr>
+				<tr>
+					<td><strong>APCu</strong></td>
+					<td><?php esc_html_e( 'Fast local cache, process-specific', 'wp-prometheus' ); ?></td>
+					<td><?php esc_html_e( 'Production, single-server deployments', 'wp-prometheus' ); ?></td>
+				</tr>
+			</tbody>
+		</table>
+		<p class="description">
+			<?php esc_html_e( 'Configure storage in the Storage tab. For Docker environments, use environment variables like WP_PROMETHEUS_STORAGE_ADAPTER.', 'wp-prometheus' ); ?>
+		</p>
 		<?php
 	}
 
@@ -1210,4 +1526,102 @@ class Settings {
 
 		wp_send_json_success( array( 'message' => __( 'Runtime metrics have been reset.', 'wp-prometheus' ) ) );
 	}
+
+	/**
+	 * AJAX handler for saving storage settings.
+	 *
+	 * @return void
+	 */
+	public function ajax_save_storage(): void {
+		check_ajax_referer( 'wp_prometheus_storage', 'nonce' );
+
+		if ( ! current_user_can( 'manage_options' ) ) {
+			wp_send_json_error( array( 'message' => __( 'Permission denied.', 'wp-prometheus' ) ) );
+		}
+
+		// Check if environment variable override is active.
+		if ( false !== getenv( 'WP_PROMETHEUS_STORAGE_ADAPTER' ) ) {
+			wp_send_json_error( array( 'message' => __( 'Storage adapter is configured via environment variable and cannot be changed.', 'wp-prometheus' ) ) );
+		}
+
+		$adapter = isset( $_POST['adapter'] ) ? sanitize_key( $_POST['adapter'] ) : 'inmemory';
+
+		// Validate adapter.
+		$valid_adapters = array_keys( StorageFactory::get_available_adapters() );
+		if ( ! in_array( $adapter, $valid_adapters, true ) ) {
+			wp_send_json_error( array( 'message' => __( 'Invalid storage adapter.', 'wp-prometheus' ) ) );
+		}
+
+		// Build config array.
+		$config = array(
+			'adapter' => $adapter,
+		);
+
+		// Redis config.
+		if ( 'redis' === $adapter ) {
+			$config['redis'] = array(
+				'host'     => isset( $_POST['redis_host'] ) ? sanitize_text_field( wp_unslash( $_POST['redis_host'] ) ) : '127.0.0.1',
+				'port'     => isset( $_POST['redis_port'] ) ? absint( $_POST['redis_port'] ) : 6379,
+				'password' => isset( $_POST['redis_password'] ) ? sanitize_text_field( wp_unslash( $_POST['redis_password'] ) ) : '',
+				'database' => isset( $_POST['redis_database'] ) ? absint( $_POST['redis_database'] ) : 0,
+				'prefix'   => isset( $_POST['redis_prefix'] ) ? sanitize_key( $_POST['redis_prefix'] ) : 'WORDPRESS_PROMETHEUS_',
+			);
+		}
+
+		// APCu config.
+		if ( 'apcu' === $adapter ) {
+			$config['apcu_prefix'] = isset( $_POST['apcu_prefix'] ) ? sanitize_key( $_POST['apcu_prefix'] ) : 'wp_prom';
+		}
+
+		// Save configuration.
+		StorageFactory::save_config( $config );
+
+		// Test if the new configuration works.
+		$test_result = StorageFactory::test_connection( $adapter, $config['redis'] ?? array() );
+
+		if ( $test_result['success'] ) {
+			wp_send_json_success( array(
+				'message' => __( 'Storage settings saved successfully.', 'wp-prometheus' ) . ' ' . $test_result['message'],
+			) );
+		} else {
+			wp_send_json_success( array(
+				'message' => __( 'Storage settings saved, but connection test failed:', 'wp-prometheus' ) . ' ' . $test_result['message'],
+				'warning' => true,
+			) );
+		}
+	}
+
+	/**
+	 * AJAX handler for testing storage connection.
+	 *
+	 * @return void
+	 */
+	public function ajax_test_storage(): void {
+		check_ajax_referer( 'wp_prometheus_storage', 'nonce' );
+
+		if ( ! current_user_can( 'manage_options' ) ) {
+			wp_send_json_error( array( 'message' => __( 'Permission denied.', 'wp-prometheus' ) ) );
+		}
+
+		$adapter = isset( $_POST['adapter'] ) ? sanitize_key( $_POST['adapter'] ) : 'inmemory';
+
+		// Build test config from form data.
+		$config = array();
+		if ( 'redis' === $adapter ) {
+			$config = array(
+				'host'     => isset( $_POST['redis_host'] ) ? sanitize_text_field( wp_unslash( $_POST['redis_host'] ) ) : '127.0.0.1',
+				'port'     => isset( $_POST['redis_port'] ) ? absint( $_POST['redis_port'] ) : 6379,
+				'password' => isset( $_POST['redis_password'] ) ? sanitize_text_field( wp_unslash( $_POST['redis_password'] ) ) : '',
+				'database' => isset( $_POST['redis_database'] ) ? absint( $_POST['redis_database'] ) : 0,
+			);
+		}
+
+		$result = StorageFactory::test_connection( $adapter, $config );
+
+		if ( $result['success'] ) {
+			wp_send_json_success( array( 'message' => $result['message'] ) );
+		} else {
+			wp_send_json_error( array( 'message' => $result['message'] ) );
+		}
+	}
 }