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	}