[Summary view] [Print] [Text view]

   1  <?php
   2  /**
   3   * Secrets API: WP_Secrets_Store class
   4   *
   5   * @package WordPress
   6   * @subpackage Secrets
   7   * @since 7.2.0
   8   */
   9  
  10  /**
  11   * Where a secret's encrypted record lives.
  12   *
  13   * An implementation is never handed a plaintext secret, only the record array
  14   * produced by WP_Secrets_Cipher and assembled by the functions in secrets.php, and
  15   * cannot turn encryption off; there is no method here that accepts or returns
  16   * anything but ciphertext-bearing structures.
  17   *
  18   * A platform store that is read-only from the application, with credentials managed
  19   * by a separate CLI or dashboard, returns WP_Error from set() rather than pretending
  20   * the write succeeded. Providers declare writability up front through
  21   * WP_Secrets_Provider::is_writable().
  22   *
  23   * Implementations extend this class. It is abstract rather than an interface so
  24   * that a later release can add a method with a default implementation, and every
  25   * existing subclass keeps working.
  26   *
  27   * @since 7.2.0
  28   */
  29  abstract class WP_Secrets_Store {
  30  
  31      /**
  32       * Reads a secret's stored record.
  33       *
  34       * @since 7.2.0
  35       *
  36       * @param string $name    The secret's namespaced name.
  37       * @param bool   $network Whether this is a network-scope secret.
  38       * @return array<mixed>|null|WP_Error The record array if it exists. Null if it does not.
  39       *                             WP_Error if it could not be determined which.
  40       */
  41      abstract public function get( string $name, bool $network = false );
  42  
  43      /**
  44       * Writes a secret's record.
  45       *
  46       * @since 7.2.0
  47       *
  48       * @param string       $name    The secret's namespaced name.
  49       * @param array<mixed> $record  The record to store.
  50       * @param bool         $network Whether this is a network-scope secret.
  51       * @return bool|WP_Error True on success. WP_Error on failure, including when the
  52       *                       store does not accept writes.
  53       */
  54      abstract public function set( string $name, array $record, bool $network = false );
  55  
  56      /**
  57       * Deletes a secret's record.
  58       *
  59       * @since 7.2.0
  60       *
  61       * @param string $name    The secret's namespaced name.
  62       * @param bool   $network Whether this is a network-scope secret.
  63       * @return bool|WP_Error True on success (including if it did not exist).
  64       *                       WP_Error on failure.
  65       */
  66      abstract public function delete( string $name, bool $network = false );
  67  
  68      /**
  69       * Lists the names of every secret in this store, for this scope. Never a value.
  70       *
  71       * @since 7.2.0
  72       *
  73       * @param bool $network Whether to list network-scope secrets.
  74       * @return string[]|WP_Error Array of secret names on success. WP_Error on failure.
  75       */
  76      abstract public function list_names( bool $network = false );
  77  }