# Class RESTian_Client

Base class for a simplied Web API access for PHP with emphasis on WordPress.

RESTian can be used without WordPress, but its design is WordPress influenced.

Uses Exceptions ONLY to designate obvious programming errors. IOW, callers of this client do NOT need to use try {} catch {} because RESTian_Client should only throw exceptions when there code has well understood bugs.

  RESTian_Base
  RESTian_Client

Abstract
Priorart:: https://guzzlephp.org/guide/service/service_descriptions.html
Located at core-classes/class-client.php

Methods summary
`public` | # `__construct( object|boolean $caller = false )` #### Parameters $caller `object|boolean` $caller
`public string` | # `get_user_agent( )` #### Returns `string`
`public string` | # `get_cachable( )` #### Returns `string`
`public` | # `initialize_from( mixed $cached )` #### Parameters $cached `mixed` $cached
`public` | # `set_credentials( mixed $credentials )` Set the grants value. Set the grants value. Note: Throws away keys that are not needed. #### Parameters $credentials `mixed` $credentials
`public array|boolean` | # `get_credentials( )` #### Returns `array|boolean`
`public` | # `set_grant( mixed $grant )` Set the grant value. Set the grant value. Note: Throws away keys that are not needed. #### Parameters $grant `mixed` $grant
`public` | # `maybe_set_grant( mixed $grant )` Set the grant value but only if not already set. Set the grant value but only if not already set. #### Parameters $grant `mixed` $grant
`public array|boolean` | # `get_grant( )` #### Returns `array|boolean`
`public array|boolean` | # `is_grant( array|boolean $grant = array() )` Returns true if the grant passed is validated by the auth provider. Returns true if the grant passed is validated by the auth provider. This does NOT mean we ARE authenticated but that we should ASSUME we are and try doing calls without first authenticating. This functionality is defined because the client (often a WordPress plugin) may have captured auth info from a prior page load where this class did authenticate, but this class is not in control of maintaining that auth info so we can only assume it is correct if the client of this code tells us it is by giving us completed credentials (or maybe some other way we discover as this code evolves base on new use-cases.) Another use-case where our assumption will fail is if the access_key expires or has since been revoked. #### Parameters $grant `array|boolean` $grant #### Returns `array|boolean`
`public array|boolean` | # `has_grant( )` Returns true if the contained grant is validated by the auth provider. Returns true if the contained grant is validated by the auth provider. #### Returns `array|boolean`
`public boolean|`RESTian_Service`` | # `get_auth_service( )` #### Returns `boolean|`RESTian_Service``
`public `RESTian_Auth_Provider_Base`` | # `get_auth_provider( )` #### Returns ``RESTian_Auth_Provider_Base``
`public array|boolean` | # `is_credentials( array|boolean $credentials )` Evaluate passed credentials to see if the auth provider considers the credentials to be valid. Evaluate passed credentials to see if the auth provider considers the credentials to be valid. This does not authenticate, it just makes sure we have credentials that might work. IOW, if username or password are empty for basic auth then clearly we don't have credentials. #### Parameters $credentials `array|boolean` $credentials #### Returns `array|boolean`
`public string` | # `get_message( )` Retrieves the last error message set by the auth provider Retrieves the last error message set by the auth provider #### Returns `string`
`public array|boolean` | # `has_credentials( )` Evaluate if the the contained credentials are considered to be valid. Evaluate if the the contained credentials are considered to be valid. This does not authenticate, it just makes sure we have credentials that might work. IOW, if username or password are empty for basic auth then clearly we don't have credentials. #### Returns `array|boolean`
`public array` | # `register_service_defaults( mixed $defaults )` #### Parameters $defaults `mixed` $defaults #### Returns `array`
`public mixed` | # `get_service_defaults( )` #### Returns `mixed`
`public array` | # `register_var_defaults( mixed $defaults )` #### Parameters $defaults `mixed` $defaults #### Returns `array`
`public mixed` | # `get_var_defaults( )` #### Returns `mixed`
`public array` | # `_register_defaults( mixed $type, mixed $defaults )` #### Parameters $type `mixed` $type $defaults `mixed` $defaults #### Returns `array`
`public mixed` | # `_get_defaults( mixed $type )` #### Parameters $type `mixed` $type #### Returns `mixed`
`public `RESTian_Service`` | # `register_service( string $service_name, array|`RESTian_Service` $args )` Allow a subclass to register an API service. Allow a subclass to register an API service. #### Parameters $service_name `string` $service_name $args `array|`RESTian_Service`` $args #### Returns ``RESTian_Service``
`public `RESTian_Service`` | # `register_action( string $resource_name, array|`RESTian_Service` $args )` Allow a subclass to register an API action. Allow a subclass to register an API action. #### Parameters $resource_name `string` $resource_name $args `array|`RESTian_Service`` $args #### Returns ``RESTian_Service``
`public `RESTian_Service`` | # `register_resource( string $resource_name, array|`RESTian_Service` $args = array() )` Allow a subclass to register an API resource. Allow a subclass to register an API resource. #### Parameters $resource_name `string` $resource_name $args `array|`RESTian_Service`` $args #### Returns ``RESTian_Service``
`public` | # `register_var( string $var_name, array $args = array() )` #### Parameters $var_name `string` $var_name $args `array` $args #### Throws ``Exception``
`public `RESTian_Var`` | # `get_var( string $var_name )` #### Parameters $var_name `string` $var_name #### Returns ``RESTian_Var``
`public` | # `register_var_set( string $var_set_name, array $vars = array() )` #### Parameters $var_set_name `string` $var_set_name $vars `array` $vars
`public` | # `get_var_set( string $var_set_name )` #### Parameters $var_set_name `string` $var_set_name
`public array` | # `get_new_credentials( )` Returns empty object of created credentials information. Returns empty object of created credentials information. Can be overridden by subclass is credentials requirements are custom. #### Returns `array`
`public `RESTian_Response`` | # `authenticate( boolean|array $credentials = false )` Authenticate against the API. Authenticate against the API. #### Parameters $credentials `boolean|array` $credentials #### Returns ``RESTian_Response``
`public object|`RESTian_Response`` | # `get_resource( string|`RESTian_Service` $resource_name, array $vars = null, array|object $args = null )` #### Parameters $resource_name `string|`RESTian_Service`` $resource_name $vars `array` $vars $args `array|object` $args #### Returns `object|`RESTian_Response`` #### Throws ``Exception``
`public object|`RESTian_Response`` | # `post_resource( string|`RESTian_Service` $resource_name, array $body = null, array|object $args = null )` #### Parameters $resource_name `string|`RESTian_Service`` $resource_name $body `array` $body $args `array|object` $args #### Returns `object|`RESTian_Response`` #### Throws ``Exception``
`public object|`RESTian_Response`` | # `invoke_action( string|`RESTian_Service` $action_name, array $vars = null, array|object $args = null )` #### Parameters $action_name `string|`RESTian_Service`` $action_name $vars `array` $vars $args `array|object` $args #### Returns `object|`RESTian_Response`` #### Throws ``Exception``
`public object|`RESTian_Response`` | # `call_service( string|`RESTian_Service` $service, string $method = 'GET', null|array $vars = null, null|array|object $args = null )` #### Parameters $service `string|`RESTian_Service`` $service $method `string` $method HTTP methods 'GET', 'POST', 'PUT', 'DELETE', 'PATCH', 'HEAD' and RESTian method 'DO' $vars `null|array` $vars $args `null|array|object` $args #### Returns `object|`RESTian_Response`` #### Throws ``Exception``
`public `RESTian_Response`` | # `make_request( `RESTian_Request` $request )` #### Parameters $request ``RESTian_Request`` $request #### Returns ``RESTian_Response`` $response
`public `RESTian_Response`` | # `process_response( `RESTian_Response` $response, null|array $vars = array(), null|array $args = array() )` Stub that allows subclass to process request, if needed. Stub that allows subclass to process request, if needed. #### Parameters $response ``RESTian_Response`` $response $vars `null|array` $vars $args `null|array` $args #### Returns ``RESTian_Response`` $response
`public` | # `initialize( )` Call subclass to register all the services and params. Call subclass to register all the services and params. Must subclass.
`public` | # `initialize_client( )` Subclass if needed. Subclass if needed.
`public` | # `get_cached( )` Override in subclass in the case caching of client serialization is wanted Override in subclass in the case caching of client serialization is wanted
`public` | # `cache( mixed $cachable )` Override in subclass in the case caching of client serialization is wanted Override in subclass in the case caching of client serialization is wanted
`public boolean|`RESTian_Service`` | # `get_service( string|`RESTian_Service` $service )` Get the service object based on its name Get the service object based on its name #### Parameters $service `string|`RESTian_Service`` $service #### Returns `boolean|`RESTian_Service`` #### Throws ``Exception``
`public string` | # `get_error_message( mixed $error_code )` Subclass if needed. Subclass if needed. #### Parameters $error_code `mixed` $error_code #### Returns `string`
`public boolean|string` | # `get_service_url( `RESTian_Service` $service )` Returns the URL for a given service. Returns the URL for a given service. Subclass if needed. #### Parameters $service ``RESTian_Service`` $service #### Returns `boolean|string`
`protected` | # `_subclass_exception( mixed $message )` Used to throw an exception when not properly subclassed. Used to throw an exception when not properly subclassed. #### Parameters $message `mixed` $message #### Throws ``Exception``
`public boolean` | # `needs_credentials( `RESTian_Service` $service )` Returns true if a service needs credentials, false if not. Useful for Registration methods that do not require any sort of Returns true if a service needs credentials, false if not. Useful for Registration methods that do not require any sort of #### Parameters $service ``RESTian_Service`` $service #### Returns `boolean`
`public` | # `register_settings( string $settings_name, array|string $args )` Register a settings Register a settings #### Parameters $settings_name `string` $settings_name $args `array|string` $args
`public boolean` | # `get_settings( string $settings_name )` #### Parameters $settings_name `string` $settings_name #### Returns `boolean`
`public boolean` | # `has_settings( string $settings_name )` #### Parameters $settings_name `string` $settings_name #### Returns `boolean`
`public boolean` | # `has_resource( mixed $resource_name )` Checks to see if a names resource has been registered. Checks to see if a names resource has been registered. #### Parameters $resource_name `mixed` $resource_name #### Returns `boolean`
`public boolean|object|`RESTian_Response`` | # `__call( string $method_name, array $args )` #### Parameters $method_name `string` $method_name $args `array` $args #### Returns `boolean|object|`RESTian_Response``
`public boolean` | # `validate_email( string $email )` #### Parameters $email `string` $email #### Returns `boolean`
`public string` | # `sanitize_email( string $email )` #### Parameters $email `string` $email #### Returns `string`
`public string` | # `sanitize_string( string $string, boolean $flags = false )` #### Parameters $string `string` $string $flags `boolean` $flags #### Returns `string`

Methods inherited from RESTian_Base
`add_action(), add_filter(), apply_filters(), do_action()`

Properties summary
`public object` | $caller | `` | # Enables the caller to attach itself so subclasses can access the caller. Our use case was for the WordPress plugin class. Enables the caller to attach itself so subclasses can access the caller. Our use case was for the WordPress plugin class.
`protected array` | $_services | `array()` | # Of RESTian_Services; provides API service specific functionality Of RESTian_Services; provides API service specific functionality
`protected array` | $_vars | `array()` | # Of name value pairs that can be used to query an API Of name value pairs that can be used to query an API
`protected array` | $_var_sets | `array()` | # Of named var sets Of named var sets
`protected array` | $_settings | `array()` | # Of service/request/response settings Of service/request/response settings
`protected array` | $_defaults | `array( 'var' => array(), 'services' => array(), )` | # - -
`protected boolean` | $_intialized | `false` | # Set to true once API is initialized. Set to true once API is initialized.
`protected boolean|array` | $_credentials | `false` | # Properties needed for credentials Properties needed for credentials
`protected boolean|array` | $_grant | `false` | # Properties needed for grant Properties needed for grant
`protected boolean|`RESTian_Service`` | $_auth_service | `false` | #
`protected string` | $_user_agent | `` | # Description of the client used to make the request. Will default unless set. Description of the client used to make the request. Will default unless set.
`public string` | $auth_type | `'basic_http'` | # The type of authorization, as defined by RESTian. In future might be RESTian-specific 'oauth2_auth_code', 'oauth2_password', 'oauth_1a', etc. The type of authorization, as defined by RESTian. In future might be RESTian-specific 'oauth2_auth_code', 'oauth2_password', 'oauth_1a', etc.
`public string` | $api_name | `` | # Human readable name of the API - to be set by subclass. Human readable name of the API - to be set by subclass.
`public string` | $base_url | `` | # The API's base URL - to be set by the subclass calling this classes constructor. The API's base URL - to be set by the subclass calling this classes constructor.
`public string` | $api_version | `` | # The version of the API used - to be set by the subclass calling this classes constructor. The version of the API used - to be set by the subclass calling this classes constructor.
`public string` | $http_agent | `` | #
`public boolean|callable` | $cache_callback | `false` | #
`public boolean` | $use_cache | `false` | #
`public `RESTian_Request`` | $request | `` | #
`public `RESTian_Response`` | $response | `` | #