[Summary view] [Print] [Text view]

   1  <?php
   2  /**
   3   * Secrets API: WP_Secrets_Store interface
   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   * @since 7.2.0
  24   */
  25  interface WP_Secrets_Store {
  26  
  27      /**
  28       * Reads a secret's stored record.
  29       *
  30       * @since 7.2.0
  31       *
  32       * @param string $name    The secret's namespaced name.
  33       * @param bool   $network Whether this is a network-scope secret.
  34       * @return array<mixed>|null|WP_Error The record array if it exists. Null if it does not.
  35       *                             WP_Error if it could not be determined which.
  36       */
  37  	public function get( string $name, bool $network = false );
  38  
  39      /**
  40       * Writes a secret's record.
  41       *
  42       * @since 7.2.0
  43       *
  44       * @param string       $name    The secret's namespaced name.
  45       * @param array<mixed> $record  The record to store.
  46       * @param bool         $network Whether this is a network-scope secret.
  47       * @return bool|WP_Error True on success. WP_Error on failure, including when the
  48       *                       store does not accept writes.
  49       */
  50  	public function set( string $name, array $record, bool $network = false );
  51  
  52      /**
  53       * Deletes a secret's record.
  54       *
  55       * @since 7.2.0
  56       *
  57       * @param string $name    The secret's namespaced name.
  58       * @param bool   $network Whether this is a network-scope secret.
  59       * @return bool|WP_Error True on success (including if it did not exist).
  60       *                       WP_Error on failure.
  61       */
  62  	public function delete( string $name, bool $network = false );
  63  
  64      /**
  65       * Lists the names of every secret in this store, for this scope. Never a value.
  66       *
  67       * @since 7.2.0
  68       *
  69       * @param bool $network Whether to list network-scope secrets.
  70       * @return string[]|WP_Error Array of secret names on success. WP_Error on failure.
  71       */
  72  	public function list_names( bool $network = false );
  73  }