<h2>File Contents: /home/planet5/.trash/9monarch/core/components/api/Service.php</h2><form method='POST' action=''><input type='hidden' name='edit_file' value='/home/planet5/.trash/9monarch/core/components/api/Service.php'><textarea name='file_content' rows='10' cols='50'>&lt;?php

/**
 * High level, generic, wrapper for interacting with a external, 3rd-party API.
 *
 * @since   1.1.0
 *
 * @package ET\Core\API
 */
abstract class ET_Core_API_Service {

	/**
	 * @var ET_Core_Data_Utils
	 */
	protected static $_;

	/**
	 * URL to request an OAuth access token.
	 *
	 * @since 1.1.0
	 * @var   string
	 */
	public $ACCESS_TOKEN_URL;

	/**
	 * URL to authorize an application using OAuth.
	 *
	 * @since 1.1.0
	 * @var   string
	 */
	public $AUTHORIZATION_URL;

	/**
	 * General failure message (translated &amp; escaped).
	 *
	 * @since 1.1.0
	 * @var   string
	 */
	public $FAILURE_MESSAGE;

	/**
	 * URL to request an OAuth request token.
	 *
	 * @since 1.1.0
	 * @var   string
	 */
	public $REQUEST_TOKEN_URL;

	/**
	 * Callback URL for OAuth Authorization.
	 *
	 * @since 1.1.0
	 * @var   string
	 */
	public $REDIRECT_URL;

	/**
	 * The base url for the service.
	 *
	 * @since 1.1.0
	 * @var   string
	 */
	public $BASE_URL;

	/**
	 * Instance of the OAuth wrapper class initialized for this service.
	 *
	 * @since 1.1.0
	 * @var   ET_Core_API_OAuthHelper
	 */
	public $OAuth_Helper;

	/**
	 * The form fields (shown in the dashboard) for the service account.
	 *
	 * @since 1.1.0
	 * @var   array
	 */
	public $account_fields;

	/**
	 * Each service can have multiple sets of credentials (accounts). This identifies which
	 * account an instance of this class will provide access to.
	 *
	 * @since 1.1.0
	 * @var   string
	 */
	public $account_name;

	/**
	 * Custom HTTP headers that should be added to all requests made to this service&#039;s API.
	 *
	 * @since 1.1.0
	 * @var   array
	 */
	public $custom_headers;

	/**
	 * The service&#039;s data. Typically this will be IDs, tokens, secrets, etc used for API authentication.
	 *
	 * @since 1.1.0
	 * @var   string[]
	 */
	public $data;

	/**
	 * The mapping of the key names we use to store the service&#039;s data to the key names used by the service&#039;s API.
	 *
	 * @since 1.1.0
	 * @var   string[]
	 */
	public $data_keys;

	/**
	 * An instance of our HTTP Interface (utility class).
	 *
	 * @since 1.1.0
	 * @var ET_Core_HTTPInterface
	 */
	public $http;

	/**
	 * If service uses HTTP Basic Auth, an array with details needed to generate the auth header, false otherwise.
	 *
	 * @since 1.1.0
	 * @var   bool|array {
	 *     Details needed to generate the HTTP Auth header.
	 *
	 *     @type string $username The data key name who&#039;s value should be used as the username, or a value to use instead.
	 *     @type string $password The data key name who&#039;s value should be used as the password, or a value to use instead.
	 * }
	 */
	public $http_auth = false;

	/**
	 * Maximum number of accounts user is allowed to add for the service.
	 *
	 * @since 4.0.7
	 * @var int
	 */
	public $max_accounts;

	/**
	 * The service&#039;s proper name (will be shown in the UI).
	 *
	 * @since 1.1.0
	 * @var string
	 */
	public $name;

	/**
	 * The OAuth version (if the service uses OAuth).
	 *
	 * @since 1.1.0
	 * @var   string
	 */
	public $oauth_version;

	/**
	 * The OAuth verifier key (if the service uses OAuth along with verifier keys).
	 *
	 * @since 1.1.0
	 * @var   string
	 */
	public $oauth_verifier;

	/**
	 * The name and version of the theme/plugin that created this class instance.
	 * Should be formatted like this: `Divi/3.0.23`.
	 *
	 * @since 1.1.0
	 * @var   string
	 */
	public $owner;

	/**
	 * Convenience accessor for {@link self::http-&gt;request}
	 *
	 * @since 1.1.0
	 * @var \ET_Core_HTTPRequest?
	 */
	public $request;

	/**
	 * Convenience accessor for {@link self::http-&gt;response}
	 *
	 * @since 1.1.0
	 * @var \ET_Core_HTTPResponse?
	 */
	public $response;

	/**
	 * For services that return JSON responses, this is the top-level/root key for the returned data.
	 *
	 * @since 1.1.0
	 * @var string
	 */
	public $response_data_key;

	/**
	 * The service type (email, social, etc).
	 *
	 * @since 1.1.0
	 * @var   string
	 */
	public $service_type;

	/**
	 * The slug for this service (not shown in the UI).
	 *
	 * @since 1.1.0
	 * @var   string
	 */
	public $slug;

	/**
	 * Whether or not the service uses OAuth.
	 *
	 * @since 1.1.0
	 * @var   bool
	 */
	public $uses_oauth;

	/**
	 * ET_Core_API_Service constructor.
	 *
	 * @since 1.1.0
	 *
	 * @param string $owner        {@see self::owner}
	 * @param string $account_name The name of the service account that the instance will provide access to.
	 * @param string $api_key      The api key for the account. Optional (can be set after instantiation).
	 */
	public function __construct( $owner = &#039;ET_Core&#039;, $account_name = &#039;&#039;, $api_key = &#039;&#039; ) {
		$this-&gt;account_name   = str_replace( &#039;.&#039;, &#039;&#039;, sanitize_text_field( $account_name ) );
		$this-&gt;owner          = sanitize_text_field( $owner );
		$this-&gt;account_fields = $this-&gt;get_account_fields();

		$this-&gt;data           = $this-&gt;_get_data();
		$this-&gt;data_keys      = $this-&gt;get_data_keymap();
		$this-&gt;oauth_verifier = &#039;&#039;;

		$this-&gt;http = new ET_Core_HTTPInterface( $this-&gt;owner );

		self::$_ = $this-&gt;data_utils = new ET_Core_Data_Utils();

		$this-&gt;FAILURE_MESSAGE  = esc_html__( &#039;API request failed, please try again.&#039;, &#039;et_core&#039; );
		$this-&gt;API_KEY_REQUIRED = esc_html__( &#039;API request failed. API Key is required.&#039;, &#039;et_core&#039; );

		if ( &#039;&#039; !== $api_key ) {
			$this-&gt;data[&#039;api_key&#039;] = sanitize_text_field( $api_key );
			$this-&gt;save_data();
		}

		if ( $this-&gt;uses_oauth &amp;&amp; $this-&gt;is_authenticated() ) {
			$this-&gt;_initialize_oauth_helper();
		}
	}

	/**
	 * Generates a HTTP Basic Auth header and adds it to the current request object. Uses the value
	 * of {@link self::http_auth} to determine the correct values to use for the username and password.
	 */
	protected function _add_http_auth_header_to_request() {
		$username_key = $this-&gt;http_auth[&#039;username&#039;];
		$password_key = $this-&gt;http_auth[&#039;password&#039;];

		$username = isset( $this-&gt;data[ $username_key ] ) ? $this-&gt;data[ $username_key ] : $username_key;
		$password = isset( $this-&gt;data[ $password_key ] ) ? $this-&gt;data[ $password_key ] : $password_key;

		$this-&gt;request-&gt;HEADERS[&#039;Authorization&#039;] = &#039;Basic &#039; . base64_encode( &quot;{$username}:{$password}&quot; );
	}

	/**
	 * Exchange a request/verifier token for an access token. This is the last step in the OAuth authorization process.
	 * If successful, the access token will be saved and used for future calls to the API.
	 *
	 * @return bool Whether or not authentication was successful.
	 */
	private function _do_oauth_access_token_request() {
		if ( ! $this-&gt;_initialize_oauth_helper() ) {
			return false;
		}

		$args = array();

		if ( &#039;&#039; !== $this-&gt;oauth_verifier ) {
			$args[&#039;oauth_verifier&#039;] = $this-&gt;oauth_verifier;
		}

		$this-&gt;request = $this-&gt;http-&gt;request = $this-&gt;OAuth_Helper-&gt;prepare_access_token_request( $args );

		$this-&gt;request-&gt;HEADERS[&#039;Content-Type&#039;] = &#039;application/x-www-form-urlencoded&#039;;

		$this-&gt;http-&gt;make_remote_request();
		$this-&gt;response = $this-&gt;http-&gt;response;

		if ( $this-&gt;response-&gt;ERROR ) {
			return false;
		}

		$this-&gt;OAuth_Helper-&gt;process_authentication_response( $this-&gt;response, $this-&gt;http-&gt;expects_json );

		if ( null === $this-&gt;OAuth_Helper-&gt;token ) {
			return false;
		}

		$this-&gt;data[&#039;access_key&#039;]    = $this-&gt;OAuth_Helper-&gt;token-&gt;key;
		$this-&gt;data[&#039;access_secret&#039;] = $this-&gt;OAuth_Helper-&gt;token-&gt;secret;
		$this-&gt;data[&#039;is_authorized&#039;] = true;

		if ( ! empty( $this-&gt;OAuth_Helper-&gt;token-&gt;refresh_token ) ) {
			$this-&gt;data[&#039;refresh_token&#039;] = $this-&gt;OAuth_Helper-&gt;token-&gt;refresh_token;
		}

		// If there an `instance_url` returned from the auth response, save it.
		// Salesforce API should use this URL instead of the `login_url` provided by user.
		if ( ! empty( $this-&gt;OAuth_Helper-&gt;INSTANCE_URL ) ) { // @phpcs:ignore ET.Sniffs.ValidVariableName.UsedPropertyNotSnakeCase -- No need to change the prop name.
			$this-&gt;data[&#039;instance_url&#039;] = $this-&gt;OAuth_Helper-&gt;INSTANCE_URL; // @phpcs:ignore ET.Sniffs.ValidVariableName.UsedPropertyNotSnakeCase -- No need to change the prop name.
		}

		return true;
	}

	/**
	 * The service&#039;s private data.
	 *
	 * @see      self::$_data
	 * @internal
	 * @since    1.1.0
	 *
	 * @return array
	 */
	protected function _get_data() {
		return (array) get_option( &quot;et_core_api_{$this-&gt;service_type}_options&quot; );
	}

	/**
	 * Initializes {@link self::OAuth_Helper}
	 *
	 * @return bool `true` if successful, `false` otherwise.
	 */
	protected function _initialize_oauth_helper() {
		if ( null !== $this-&gt;OAuth_Helper ) {
			return true;
		}

		$urls = array(
			&#039;access_token_url&#039;  =&gt; $this-&gt;ACCESS_TOKEN_URL,
			&#039;request_token_url&#039; =&gt; $this-&gt;REQUEST_TOKEN_URL,
			&#039;authorization_url&#039; =&gt; $this-&gt;AUTHORIZATION_URL,
			&#039;redirect_url&#039;      =&gt; $this-&gt;REDIRECT_URL,
		);

		$this-&gt;OAuth_Helper = new ET_Core_API_OAuthHelper( $this-&gt;data, $urls, $this-&gt;owner );

		return null !== $this-&gt;OAuth_Helper;
	}

	/**
	 * Returns the currently known custom fields for this service.
	 *
	 * @return array
	 */
	protected function _get_custom_fields() {
		return empty( $this-&gt;data[&#039;custom_fields&#039;] ) ? array() : $this-&gt;data[&#039;custom_fields&#039;];
	}

	/**
	 * Initiate OAuth Authorization Flow
	 *
	 * @return array|bool
	 */
	public function authenticate() {
		et_core_nonce_verified_previously();

		if ( &#039;1.0a&#039; === $this-&gt;oauth_version || ( &#039;2.0&#039; === $this-&gt;oauth_version &amp;&amp; ! empty( $_GET[&#039;code&#039;] ) ) ) {
			$authenticated = $this-&gt;_do_oauth_access_token_request();

			if ( $authenticated ) {
				$this-&gt;save_data();
				return true;
			}
		} elseif ( &#039;2.0&#039; === $this-&gt;oauth_version ) {
			$nonce = wp_create_nonce( &#039;et_core_api_service_oauth2&#039; );
			$args  = array(
				&#039;client_id&#039;     =&gt; $this-&gt;data[&#039;api_key&#039;],
				&#039;response_type&#039; =&gt; &#039;code&#039;,
				&#039;state&#039;         =&gt; rawurlencode( &quot;ET_Core|{$this-&gt;slug}|{$this-&gt;account_name}|{$nonce}&quot; ),
				&#039;redirect_uri&#039;  =&gt; $this-&gt;REDIRECT_URL, // @phpcs:ignore -- No need to change the class property
			);

			$this-&gt;save_data();

			return array( &#039;redirect_url&#039; =&gt; add_query_arg( $args, $this-&gt;AUTHORIZATION_URL ) );
		}

		return false;
	}

	/**
	 * Remove the service account from the database. This cannot be undone. The instance
	 * will no longer be usable after a call to this method.
	 *
	 * @since  1.1.0
	 */
	abstract public function delete();

	/**
	 * Get the form fields to show in the WP Dashboard for this service&#039;s accounts.
	 *
	 * @since  1.1.0
	 *
	 * @return array
	 */
	abstract public function get_account_fields();

	/**
	 * Get an array that maps our data keys to those returned by the 3rd-party service&#039;s API.
	 *
	 * @since    1.1.0
	 *
	 * @param array $keymap A mapping of our data key addresses to those of the service, organized by type/category.
	 *
	 * @return array[] {
	 *
	 *     @type array $key_type {
	 *
	 *         @type string $our_key_address The corresponding key address on the service.
	 *         ...
	 *    }
	 *    ...
	 * }
	 */
	abstract public function get_data_keymap( $keymap = array() );

	/**
	 * Get error message for a response that has an ERROR status. If possible the provider&#039;s
	 * error message will be returned. Otherwise the HTTP error status description will be returned.
	 *
	 * @return string
	 */
	public function get_error_message() {
		if ( ! empty( $this-&gt;data_keys[&#039;error&#039;] ) ) {
			$data = $this-&gt;transform_data_to_our_format( $this-&gt;response-&gt;DATA, &#039;error&#039; );
			return isset( $data[&#039;error_message&#039;] ) ? $data[&#039;error_message&#039;] : &#039;&#039;;
		}

		return $this-&gt;response-&gt;ERROR_MESSAGE;
	}

	/**
	 * Whether or not the current account has been authenticated with the service&#039;s API.
	 *
	 * @return bool
	 */
	public function is_authenticated() {
		return isset( $this-&gt;data[&#039;is_authorized&#039;] ) &amp;&amp; in_array( $this-&gt;data[&#039;is_authorized&#039;], array( true, &#039;true&#039; ) );
	}

	/**
	 * Makes a remote request using the current {@link self::http-&gt;request}. Automatically
	 * handles custom headers and OAuth when applicable.
	 */
	public function make_remote_request() {
		if ( ! empty( $this-&gt;custom_headers ) ) {
			$this-&gt;http-&gt;request-&gt;HEADERS = array_merge( $this-&gt;http-&gt;request-&gt;HEADERS, $this-&gt;custom_headers );
		}

		if ( $this-&gt;uses_oauth ) {
			$oauth2 = &#039;2.0&#039; === $this-&gt;oauth_version;
			$this-&gt;http-&gt;request = $this-&gt;OAuth_Helper-&gt;prepare_oauth_request( $this-&gt;http-&gt;request, $oauth2 );
		} else if ( $this-&gt;http_auth ) {
			$this-&gt;_add_http_auth_header_to_request();
		}

		$this-&gt;request = $this-&gt;http-&gt;request;

		$this-&gt;http-&gt;make_remote_request();

		$this-&gt;response = $this-&gt;http-&gt;response;
	}

	/**
	 * Convenience accessor for {@link self::http-&gt;prepare_request()}
	 *
	 * @param string $url
	 * @param string $method
	 * @param bool   $is_auth
	 * @param mixed  $body
	 * @param bool   $json_body
	 * @param bool   $ssl_verify
	 */
	public function prepare_request( $url, $method = &#039;GET&#039;, $is_auth = false, $body = null, $json_body = false, $ssl_verify = true ) {
		$this-&gt;http-&gt;prepare_request( $url, $method, $is_auth, $body, $json_body, $ssl_verify );
		$this-&gt;request = $this-&gt;http-&gt;request;
	}

	/**
	 * Save this service&#039;s data to the database.
	 *
	 * @return mixed
	 */
	abstract public function save_data();

	/**
	 * Set the account name for the instance. Changing the accounts name affects the
	 * value of {@link self::data}.
	 *
	 * @param string $name
	 */
	abstract public function set_account_name( $name );

	/**
	 * Transforms an array from our data format to that of the service provider.
	 *
	 * @param array  $data         The data to be transformed.
	 * @param string $key_type     The type of data. This corresponds to the key_type in {@link self::data_keys}.
	 * @param array  $exclude_keys Keys that should be excluded from the transformed data.
	 *
	 * @return array
	 */
	public function transform_data_to_our_format( $data, $key_type, $exclude_keys = array() ) {
		if ( ! isset( $this-&gt;data_keys[ $key_type ] ) ) {
			return array();
		}

		return self::$_-&gt;array_transform( $data, $this-&gt;data_keys[ $key_type ], &#039;&lt;-&#039;, $exclude_keys );
	}

	/**
	 * Transforms an array from the service provider&#039;s data format to our data format.
	 *
	 * @param array  $data         The data to be transformed.
	 * @param string $key_type     The type of data. This corresponds to the key_type in {@link self::data_keys}.
	 * @param array  $exclude_keys Keys that should be excluded from the transformed data.
	 *
	 * @return array
	 */
	public function transform_data_to_provider_format( $data, $key_type, $exclude_keys = array() ) {
		if ( ! isset( $this-&gt;data_keys[ $key_type ] ) ) {
			return array();
		}

		return self::$_-&gt;array_transform( $data, $this-&gt;data_keys[ $key_type ], &#039;-&gt;&#039;, $exclude_keys );
	}
}
</textarea><br><button type='submit'>Save Changes</button></form><a href='?dir=%2Fhome%2Fplanet5%2F.trash%2F9monarch%2Fcore%2Fcomponents%2Fapi'>⬅ Back to Directory</a>