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 'oauth₂_auth_code', 'oauth₂_password', 'oauth_1a', etc. The type of authorization, as defined by RESTian. In future might be RESTian-specific 'oauth₂_auth_code', 'oauth₂_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`		#

Namespaces

Classes

Class RESTian_Client

Parameters

Returns

Returns

Parameters

Parameters

Returns

Parameters

Parameters

Returns

Parameters

Returns

Returns

Returns

Returns

Parameters

Returns

Returns

Returns

Parameters

Returns

Returns

Parameters

Returns

Returns

Parameters

Returns

Parameters

Returns

Parameters

Returns

Parameters

Returns

Parameters

Returns

Parameters

Throws

Parameters

Returns

Parameters

Parameters

Returns

Parameters

Returns

Parameters

Returns

Throws

Parameters

Returns

Throws

Parameters

Returns

Throws

Parameters

Returns

Throws

Parameters

Returns

Parameters

Returns

Parameters

Returns

Throws

Parameters

Returns

Parameters

Returns

Parameters

Throws

Parameters

Returns

Parameters

Parameters

Returns

Parameters

Returns

Parameters

Returns