diff --git a/wp-deploybot-api.php b/wp-deploybot-api.php index e619c04..82c4245 100644 --- a/wp-deploybot-api.php +++ b/wp-deploybot-api.php @@ -21,6 +21,7 @@ exit; } +/* Add base class if needed. */ if ( ! class_exists( 'WpDeployBotBase' ) ) { include_once( 'wp-api-libraries-base.php' ); } @@ -47,21 +48,54 @@ class DeployBotAPI extends WpDeployBotBase { */ protected $base_uri; + /** + * Arguments to populate. + * + * @var array + */ protected $args; - public function __construct( $subdomain, $api_key ) { + /** + * Constructiroy. + * + * @access public + * @param string $subdomain The organization's subdomain. + * @param string $api_key The auth API key. + * @return void + */ + public function __construct( string $subdomain, string $api_key ) { $this->set_api_key( $api_key ); $this->set_subdomain( $subdomain ); } - public function set_api_key( $api_key ) { + /** + * Set the API key. + * + * @access public + * @param string $api_key The API key. + * @return void + */ + public function set_api_key( string $api_key ) { $this->api_key = $api_key; } - public function set_subdomain( $subdomain ) { + /** + * Set the subdomian. + * + * @access public + * @param string $subdomain The subdomain. + * @return void + */ + public function set_subdomain( string $subdomain ) { $this->base_uri = 'https://' . $subdomain . '.deploybot.com/api/v1/'; } + /** + * Set headers. + * + * @access protected + * @return void + */ protected function set_headers() { $this->args['headers'] = array( 'X-Api-Token' => $this->api_key, @@ -69,19 +103,42 @@ protected function set_headers() { ); } + /** + * Clear arguments. + * + * @access protected + * @return void + */ protected function clear() { $this->args = array(); } - protected function run( $route, $body = array(), $method = 'GET' ) { + /** + * Execute call. Is a wrapper for $this->build_request( $route, $body, $method )->fetch + * + * @access protected + * @param string $route The URI extension to send the request to. + * @param array $body Additional arguments to pass. + * @param string $method The method to call (get, delete, post, etc). + * @return mixed The response. + */ + protected function run( string $route, array $body = array(), string $method = 'GET' ) { return $this->build_request( $route, $body, $method )->fetch(); } + /** + * Parse an array of arguments for nullity, and keep non-null ones. + * + * @access private + * @param array $args Array/key arguments to parse. + * @param array $merge (Default: array()) An array of additional arguments to merge. + * @return array The cleansed/merged array. + */ private function parse_args( $args, $merge = array() ) { $results = array(); foreach ( $args as $key => $val ) { - if ( $val !== null ) { + if ( null !== $val ) { $results[ $key ] = $val; } else if ( is_array( $val ) && ! empty( $val ) ) { $results[ $key ] = $val; @@ -92,10 +149,12 @@ private function parse_args( $args, $merge = array() ) { } /** - * get_users function. + * Get users. * * @access public - * @return void + * @param int $limit (Default: 50) The number of posts to limit the result to. + * @param mixed $after (Default: null) The post to display results following. + * @return object */ function get_users( $limit = 50, $after = null ) { $args = $this->parse_args( array( @@ -108,11 +167,11 @@ function get_users( $limit = 50, $after = null ) { /** - * get_user function. + * Get a single user. * * @access public - * @param mixed $user_id - * @return void + * @param mixed $user_id The user to grab. + * @return object The user. */ function get_user( $user_id ) { return $this->run( 'users/' . $user_id ); @@ -122,13 +181,13 @@ function get_user( $user_id ) { * List deployments. * * @access public - * @param mixed $repository_id - * @param mixed $environment_id - * @param mixed $limit - * @param mixed $after - * @return void + * @param mixed $repository_id The repository to display from. + * @param mixed $environment_id The environment to display from. + * @param int $limit (Default: 50) The number of results to list. + * @param mixed $after (Default: null) The environment to display results after. + * @return object An object containing the entries, and some pagination properties. */ - function list_deployments( $repository_id, $environment_id, $limit = 50, $after = null ) { + function list_deployments( $repository_id, $environment_id, int $limit = 50, $after = null ) { $args = $this->parse_args( array( 'repository_id' => $repository_id, 'environment_id' => $environment_id, @@ -141,11 +200,11 @@ function list_deployments( $repository_id, $environment_id, $limit = 50, $after /** - * Get a deployment + * Get a deployment. * * @access public - * @param mixed $deployment_id - * @return void + * @param mixed $deployment_id The deployment ID to get. + * @return object The deployment */ function get_deployment( $deployment_id ) { return $this->run( 'deployments/'.$deployment_id ); @@ -153,17 +212,17 @@ function get_deployment( $deployment_id ) { /** - * trigger_deployment function. + * Trigger a deployment. * * @access public - * @param mixed $environment_id + * @param mixed $environment_id The ID of the environment to trigger. * @param array $args Additional arguments, supports: * user_id (default -> account owner) * deployed_version (git commit) * deploy_from_scratch (default false) * trigger_notifications (default true) - * comment - * @return void + * comment. + * @return object The result of the deployment. */ function trigger_deployment( $environment_id, $args = array() ) { $args['environment_id'] = $environment_id; @@ -171,24 +230,25 @@ function trigger_deployment( $environment_id, $args = array() ) { } /** - * Get Repository. + * Get repository. * * @access public - * @return void + * @param mixed $repository_id The ID of a repository to grab. + * @return object The repository. */ function get_repository( $repository_id ) { return $this->run( 'repositories/'.$repository_id ); } /** - * List Repositories + * List repositories. * * @access public - * @param string $limit (default: '') - * @param string $after (default: '') - * @return void + * @param int $limit (default: 50) The number of results to grab. + * @param mixed $after (default: null) The result to display results following. + * @return object An object containing the entries, and some pagination properties. */ - function list_repositories( $limit = 50, $after = null ) { + function list_repositories( int $limit = 50, $after = null ) { $args = $this->parse_args( array( 'limit' => $limit, 'after' => $after, @@ -198,24 +258,26 @@ function list_repositories( $limit = 50, $after = null ) { } /** - * get_environment function. + * Get an environment. * * @access public - * @return void + * @param mixed $environment_id The ID of the environment to get. + * @return object The environment. */ function get_environment( $environment_id ) { return $this->run( 'environment/'.$environment_id ); } /** - * List Environments. + * List environments. * * @access public - * @param mixed $limit - * @param mixed $after - * @return void + * @param mixed $repository_id (Default: null) The ID of the repository to limit results by. + * @param int $limit (Default: 50) The number of environments to display. + * @param mixed $after (Default: null) The post to list following. + * @return object An object containing the entries, and some pagination properties. */ - function list_environments( $repository_id = null, $limit = 50, $after = null ) { + function list_environments( $repository_id = null, int $limit = 50, $after = null ) { $args = $this->parse_args( array( 'repository_id' => $repository_id, 'limit' => 50, @@ -226,10 +288,11 @@ function list_environments( $repository_id = null, $limit = 50, $after = null ) } /** - * Get Server Details. + * Get server details. * * @access public - * @return void + * @param mixed $server_id The ID of the server. + * @return object The server */ function get_server( $server_id ) { return $this->run( 'server/'.$server_id ); @@ -237,14 +300,16 @@ function get_server( $server_id ) { /** - * List Servers. + * List servers. * * @access public - * @param mixed $limit Limit. - * @param mixed $after After. - * @return void + * @param mixed $repository_id (Default: null) The repository to limit results to. + * @param mixed $environment_id (Default: null) The environment to limit results to. + * @param int $limit (Default: 50) The number of environments to display. + * @param mixed $after (Default: null) The post to list following. + * @return object An object containing the entries, and some pagination properties. */ - function list_servers( $repository_id = null, $environment_id = null, $limit = 50, $after = null ) { + function list_servers( $repository_id = null, $environment_id = null, int $limit = 50, $after = null ) { $args = $this->parse_args(array( 'repository_id' => $repository_id, 'environment_id' => $environment_id, @@ -258,31 +323,32 @@ function list_servers( $repository_id = null, $environment_id = null, $limit = 5 /** * HTTP response code messages. * - * @param [String] $code : Response code to get message from. - * @return [String] : Message corresponding to response code sent in. + * @access public + * @param mixed $code Response code to get message from. + * @return string Message corresponding to response code sent in. */ public function response_code_msg( $code = '' ) { switch ( $code ) { case 200: - $msg = __( 'Success.', 'text-domain' ); + $msg = __( 'Success.', 'wp-deploy-bot' ); break; case 400: - $msg = __( 'Bad Request: Malformed JSON payload.', 'text-domain' ); + $msg = __( 'Bad Request: Malformed JSON payload.', 'wp-deploy-bot' ); break; case 401: - $msg = __( 'Authentication Required: Missing or invalid API token.', 'text-domain' ); + $msg = __( 'Authentication Required: Missing or invalid API token.', 'wp-deploy-bot' ); break; case 403: - $msg = __( 'Forbidden: Attempting to perform a restricted action.', 'text-domain' ); + $msg = __( 'Forbidden: Attempting to perform a restricted action.', 'wp-deploy-bot' ); break; case 422: - $msg = __( 'Unprocessable Entity: Something is not right with the request data.', 'text-domain' ); + $msg = __( 'Unprocessable Entity: Something is not right with the request data.', 'wp-deploy-bot' ); break; case 500: - $msg = __( 'Internal Server Error: An error on our deploybot side. Please contact support if the error persists.', 'text-domain' ); + $msg = __( 'Internal Server Error: An error on our deploybot side. Please contact support if the error persists.', 'wp-deploy-bot' ); break; default: - $msg = __( 'Response code unknown.', 'text-domain' ); + $msg = __( 'Response code unknown.', 'wp-deploy-bot' ); break; } return $msg;