← All changes | jetpack_vendor/automattic/jetpack-connection/src/interface-storage-provider.php +129 -0 16.2-beta → 16.3 View file →

		@@ -1,0 +1,129 @@
	1	+<?php
	2	+/**
	3	+ * Storage Provider Interface for External Storage.
	4	+ *
	5	+ * Defines the contract that all external storage providers must implement
	6	+ * to be compatible with the Jetpack Connection External Storage system.
	7	+ *
	8	+ * @package automattic/jetpack-connection
	9	+ */
	10	+
	11	+namespace Automattic\Jetpack\Connection;
	12	+
	13	+/**
	14	+ * Interface for external storage providers.
	15	+ *
	16	+ * All storage providers must implement this interface to ensure
	17	+ * compatibility with the External_Storage system.
	18	+ *
	19	+ * ## Required Methods
	20	+ *
	21	+ * - `is_available()` - Check if storage backend is accessible
	22	+ * - `should_handle( $option_name )` - Determine if provider handles the option
	23	+ * - `get( $option_name )` - Retrieve value from external storage
	24	+ * - `get_environment_id()` - Return environment identifier for logging
	25	+ *
	26	+ * ## Optional Methods
	27	+ *
	28	+ * Providers may implement these additional methods for enhanced functionality:
	29	+ *
	30	+ * ### handle_error_event( string $event_type, string $key, string $details, string $environment )
	31	+ *
	32	+ * Called when External_Storage detects an error or empty state. Implement this
	33	+ * to report errors to your host's monitoring system.
	34	+ *
	35	+ * - `$event_type` - 'error' or 'empty'
	36	+ * - `$key` - The option key that triggered the event
	37	+ * - `$details` - Additional error details (error message, etc.)
	38	+ * - `$environment` - Environment identifier from get_environment_id()
	39	+ *
	40	+ * Example:
	41	+ *
	42	+ * public function handle_error_event( $event_type, $key, $details, $environment ) {
	43	+ * // Report to your monitoring system
	44	+ * wp_remote_post(
	45	+ * 'https://your-api/errors',
	46	+ * array(
	47	+ * 'body' => array(
	48	+ * 'event_type' => $event_type,
	49	+ * 'key' => $key,
	50	+ * 'details' => $details,
	51	+ * 'environment' => $environment,
	52	+ * ),
	53	+ * )
	54	+ * );
	55	+ * }
	56	+ *
	57	+ * ### get_empty_state_delay_threshold()
	58	+ *
	59	+ * Customize the delay before reporting empty states. Returns delay in seconds.
	60	+ * Default (when not implemented) is 5 minutes (300 seconds). Use this if your
	61	+ * storage system has different sync times.
	62	+ *
	63	+ * - Return `0` if external storage is the source of truth (written first)
	64	+ * - Return higher values for slower sync systems
	65	+ * - Maximum allowed value is 15 minutes (900 seconds); values above this are ignored
	66	+ *
	67	+ * Example:
	68	+ *
	69	+ * public function get_empty_state_delay_threshold() {
	70	+ * return 90; // 90 seconds for fast-syncing storage
	71	+ * // return 0; // No delay - external storage is written first
	72	+ * }
	73	+ *
	74	+ * @since 6.18.0
	75	+ */
	76	+interface Storage_Provider_Interface {
	77	+
	78	+ /**
	79	+ * Check if the storage provider is available in the current environment.
	80	+ *
	81	+ * This method should return true if the storage backend is accessible
	82	+ * and ready to handle requests, false otherwise.
	83	+ *
	84	+ * @since 6.18.0
	85	+ *
	86	+ * @return bool True if storage is available, false otherwise.
	87	+ */
	88	+ public function is_available();
	89	+
	90	+ /**
	91	+ * Determine if this provider should handle the given option.
	92	+ *
	93	+ * This method allows providers to selectively handle certain options
	94	+ * based on their configuration, environment, or other criteria.
	95	+ *
	96	+ * @since 6.18.0
	97	+ *
	98	+ * @param string $option_name The name of the option to check.
	99	+ * @return bool True if this provider should handle the option, false otherwise.
	100	+ */
	101	+ public function should_handle( $option_name );
	102	+
	103	+ /**
	104	+ * Retrieve a value from external storage.
	105	+ *
	106	+ * This method should return the value from external storage, or null
	107	+ * if the value is not found or cannot be retrieved.
	108	+ *
	109	+ * @since 6.18.0
	110	+ *
	111	+ * @param string $option_name The name of the option to retrieve.
	112	+ * @return mixed The option value, or null if not found/available.
	113	+ * @throws \Exception If there's an error retrieving the value.
	114	+ */
	115	+ public function get( $option_name );
	116	+
	117	+ /**
	118	+ * Get the environment identifier for this provider.
	119	+ *
	120	+ * This method should return a unique identifier for the environment
	121	+ * or storage type (e.g., 'atomic', 'vip', 'kubernetes', etc.).
	122	+ * Used for logging and debugging purposes.
	123	+ *
	124	+ * @since 6.18.0
	125	+ *
	126	+ * @return string The environment identifier.
	127	+ */
	128	+ public function get_environment_id();
	129	+}