diff --git a/src/AWS/AWS.php b/src/AWS/AWS.php index 92ffeda..d890598 100644 --- a/src/AWS/AWS.php +++ b/src/AWS/AWS.php @@ -12,26 +12,40 @@ use gullevek\AmazonIncentives\Response\CreateResponse; class AWS { + /** @var string What AWS Service to use: Gift Card on Demand (GCOD) */ public const SERVICE_NAME = 'AGCODService'; + /** @var string */ public const ACCEPT_HEADER = 'accept'; + /** @var string content-type */ public const CONTENT_HEADER = 'content-type'; + /** @var string */ public const HOST_HEADER = 'host'; + /** @var string */ public const X_AMZ_DATE_HEADER = 'x-amz-date'; + /** @var string */ public const X_AMZ_TARGET_HEADER = 'x-amz-target'; + /** @var string */ public const AUTHORIZATION_HEADER = 'Authorization'; + /** @var string type of encryption type */ public const AWS_SHA256_ALGORITHM = 'AWS4-HMAC-SHA256'; + /** @var string key type to use */ public const KEY_QUALIFIER = 'AWS4'; + /** @var string */ public const TERMINATION_STRING = 'aws4_request'; + /** @var string Service to use: Create Gift Card */ public const CREATE_GIFT_CARD_SERVICE = 'CreateGiftCard'; + /** @var string Service to use: Cancle Gift Card */ public const CANCEL_GIFT_CARD_SERVICE = 'CancelGiftCard'; + /** @var string Service to use: Get Available Funds */ public const GET_AVAILABLE_FUNDS_SERVICE = 'GetAvailableFunds'; - /** - * @var Config - */ + /** @var Config Configuration class with all settings */ private $config; /** + * Initialize the main AWS class. This class prepares and sends all the actions + * and returns reponses as defined in in the CreateResponse class + * * @param Config $config */ public function __construct(Config $config) @@ -41,9 +55,13 @@ class AWS } /** - * @param float $amount - * @param string|null $creation_id - * @return CreateResponse + * Bug a gift card + * + * @param float $amount Amount to buy a gifr card in set currencty + * @param string|null $creation_id Override creation id, if not set will + * be created automatically. If not valid error + * will be thrown + * @return CreateResponse Object with AWS response data * * @throws AmazonErrors */ @@ -64,9 +82,11 @@ class AWS } /** - * @param string $creation_request_id - * @param string $gift_card_id - * @return CancelResponse + * Cancle an ordered gift card, only possible within the the time limit + * + * @param string $creation_request_id Previously created creation request id + * @param string $gift_card_id Previously created gift card id + * @return CancelResponse Object with AWS response data * * @throws AmazonErrors */ @@ -87,7 +107,9 @@ class AWS } /** - * @return CreateBalanceResponse + * Get current account funds + * + * @return CreateBalanceResponse Object with AWS response data * * @throws AmazonErrors */ @@ -108,11 +130,17 @@ class AWS } /** - * @param string $payload - * @param string $canonical_request - * @param string $service_operation - * @param string $date_time_string - * @return string + * General request method for all actions + * Calls the Client class that actually runs the json request + * For service_operation valid data see AWS GCOD documentation + * + * @param string $payload The data needed for this request + * @param string $canonical_request Header data to send for this request + * @param string $service_operation Service operation. CREATE_GIFT_CARD_SERVICE, + * CANCEL_GIFT_CARD_SERVICE or + * GET_AVAILABLE_FUNDS_SERVICE constant values + * @param string $date_time_string Ymd\THis\Z encoded timestamp, getTimestamp() + * @return string Request result as string, json data */ public function makeRequest( string $payload, @@ -156,16 +184,25 @@ class AWS ]]); $url = 'https://' . $endpoint . '/' . $service_operation; - $headers = $this->buildHeaders($payload, $authorization_value, $date_time_string, $service_target); + $headers = $this->buildHeaders( + $payload, + $authorization_value, + $date_time_string, + $service_target + ); return (new Client())->request($url, $headers, $payload); } /** - * @param string $payload - * @param string $authorization_value - * @param string $date_time_string - * @param string $service_target - * @return array + * Build the headers used in the makeRequest method. + * These are the HTML headers used with curl + * + * @param string $payload Paylout to create this header for + * @param string $authorization_value Auth string + * @param string $date_time_string Ymd\THis\Z encoded timestamp, getTimestamp() + * @param string $service_target Target service in the agcod string: + * Value like com.amazonaws.agcod.. + * @return array Header data as array for curl request */ public function buildHeaders( string $payload, @@ -188,8 +225,33 @@ class AWS } /** - * @param string $string_to_sign - * @return string + * The request string build with the actauly request data created by + * getCanonicalRequest(). This string is used in the auth signature call + * + * @param string $canonical_request_hash sha256 hash to build from + * @return string String to send to buildAuthSignature() + */ + public function buildStringToSign($canonical_request_hash): string + { + $AWS_SHA256_ALGORITHM = self::AWS_SHA256_ALGORITHM; + $TERMINATION_STRING = self::TERMINATION_STRING; + $SERVICE_NAME = self::SERVICE_NAME; + $region_name = $this->getRegion(); + $date_time_string = $this->getTimestamp(); + $date_string = $this->getDateString(); + $string_to_sign = "$AWS_SHA256_ALGORITHM\n" + . "$date_time_string\n" + . "$date_string/$region_name/$SERVICE_NAME/$TERMINATION_STRING\n" + . "$canonical_request_hash"; + + return $string_to_sign; + } + + /** + * Build the authentication signature used in the buildHeaders method + * + * @param string $string_to_sign Data to sign, buildStringToSign() + * @return string Authorized value as string */ public function buildAuthSignature(string $string_to_sign): string { @@ -224,28 +286,12 @@ class AWS } /** - * @param string $canonical_request_hash - * @return string - */ - public function buildStringToSign($canonical_request_hash): string - { - $AWS_SHA256_ALGORITHM = self::AWS_SHA256_ALGORITHM; - $TERMINATION_STRING = self::TERMINATION_STRING; - $SERVICE_NAME = self::SERVICE_NAME; - $region_name = $this->getRegion(); - $date_time_string = $this->getTimestamp(); - $date_string = $this->getDateString(); - $string_to_sign = "$AWS_SHA256_ALGORITHM\n" - . "$date_time_string\n" - . "$date_string/$region_name/$SERVICE_NAME/$TERMINATION_STRING\n" - . "$canonical_request_hash"; - - return $string_to_sign; - } - - /** - * @param bool $rawOutput - * @return string + * Build the derived key to build the final hmac signature string + * + * @param bool $rawOutput Set to true to create the hash based message + * authenticator string as normal text string or + * lowercase hexbits + * @return string Derived key (hmac type) */ public function buildDerivedKey(bool $rawOutput = true): string { @@ -293,7 +339,7 @@ class AWS * MXN for MX * GBP for UK * - * @return string + * @return string Region string depending on given endpoint url */ public function getRegion(): string { @@ -320,9 +366,15 @@ class AWS /** - * @param float $amount - * @param string|null $creation_id - * @return string + * The actual data to send as json encoded string for creating a gift card. + * The creation request id must be in the format: + * _ + * + * @param float $amount Amount of currencty to create the gift card + * request for + * @param string|null $creation_id The creation id, if not set will be created here + * @return string JSON encoded array to be used as payload + * in get gift card call */ public function getGiftCardPayload(float $amount, ?string $creation_id = null): string { @@ -339,9 +391,12 @@ class AWS } /** - * @param string $creation_request_id - * @param string $gift_card_id - * @return string + * The actual data to send as json encoded string to cancel a created gift card + * + * @param string $creation_request_id Creation request id from previous get gift card + * @param string $gift_card_id Gift card id from previous get gift card + * @return string JSON encoded array to be used as payload + * in cancle gift card call */ public function getCancelGiftCardPayload(string $creation_request_id, string $gift_card_id): string { @@ -354,7 +409,10 @@ class AWS } /** - * @return string + * The actualy data to send as json encoded string for getting the current + * account funds + * + * @return string JSON encoded array to be used as payload in funds call */ public function getAvailableFundsPayload(): string { @@ -365,9 +423,34 @@ class AWS } /** - * @param string $service_operation - * @param string $payload - * @return string + * Heeders used in the getCanonicalRequest() + * + * @param string $service_operation Service operation code in the service string request + * Value is: com.amazonaws.agcod.AGCODService. + * @return string Header string to be used + */ + public function buildCanonicalHeaders(string $service_operation): string + { + $ACCEPT_HEADER = self::ACCEPT_HEADER; + $HOST_HEADER = self::HOST_HEADER; + $X_AMZ_DATE_HEADER = self::X_AMZ_DATE_HEADER; + $X_AMZ_TARGET_HEADER = self::X_AMZ_TARGET_HEADER; + $date_time_string = $this->getTimestamp(); + $endpoint = $this->config->getEndpoint(); + $content_type = $this->getContentType(); + return "$ACCEPT_HEADER:$content_type\n" + . "$HOST_HEADER:$endpoint\n" + . "$X_AMZ_DATE_HEADER:$date_time_string\n" + . "$X_AMZ_TARGET_HEADER:com.amazonaws.agcod.AGCODService.$service_operation"; + } + + /** + * Headers used in the get/cancel/funds requests + * + * @param string $service_operation Service operation code to be used in header request + * and main request call + * @param string $payload Payload from get/cancle Code or funds call + * @return string Full POST service request code */ public function getCanonicalRequest(string $service_operation, string $payload): string { @@ -386,8 +469,10 @@ class AWS } /** - * @param string $data - * @return string + * Build sha256 hash from given data + * + * @param string $data Data to be hashed with sha256 + * @return string sha256 hash */ public function buildHash(string $data): string { @@ -395,18 +480,13 @@ class AWS } /** - * @return string - */ - public function getTimestamp() - { - return gmdate('Ymd\THis\Z'); - } - - /** - * @param string $data - * @param string $key - * @param bool $raw - * @return string + * Create a sha256 based Hash-Based Message Authentication Code + * with the given key and data + * + * @param string $data Data to be hashed with key below + * @param string $key Key to be used for creating the hash + * @param bool $raw Returning data as ascii string or hexibits + * @return string Hash-Based Message Authentication Code */ public function hmac(string $data, string $key, bool $raw = true): string { @@ -414,7 +494,21 @@ class AWS } /** - * @return string + * Build timestamp in the format used by AWS services + * eg 20211009\T102030\Z + * + * @return string date string based on current time. Ymd\THis\Z + */ + public function getTimestamp() + { + return gmdate('Ymd\THis\Z'); + } + + /** + * Get only the date string from the getTimestamp + * eg 20211009 + * + * @return string Date string YYYYmmdd extracted from getTimestamp() */ public function getDateString() { @@ -422,31 +516,14 @@ class AWS } /** - * @return string + * Fixed content type for submission, is json + * + * @return string 'application/json' string */ public function getContentType(): string { return 'application/json'; } - - /** - * @param string $service_operation - * @return string - */ - public function buildCanonicalHeaders(string $service_operation): string - { - $ACCEPT_HEADER = self::ACCEPT_HEADER; - $HOST_HEADER = self::HOST_HEADER; - $X_AMZ_DATE_HEADER = self::X_AMZ_DATE_HEADER; - $X_AMZ_TARGET_HEADER = self::X_AMZ_TARGET_HEADER; - $date_time_string = $this->getTimestamp(); - $endpoint = $this->config->getEndpoint(); - $content_type = $this->getContentType(); - return "$ACCEPT_HEADER:$content_type\n" - . "$HOST_HEADER:$endpoint\n" - . "$X_AMZ_DATE_HEADER:$date_time_string\n" - . "$X_AMZ_TARGET_HEADER:com.amazonaws.agcod.AGCODService.$service_operation"; - } } // __END__ diff --git a/src/AmazonIncentives.php b/src/AmazonIncentives.php index 692aa5d..6345375 100644 --- a/src/AmazonIncentives.php +++ b/src/AmazonIncentives.php @@ -53,9 +53,15 @@ final class AmazonIncentives // ********************************************************************* /** - * @param float $value - * @param string|null $creation_request_id AWS creationRequestId - * @return Response\CreateResponse + * Buy a gift card + * + * @param float $value Amount to purchase a gift card + * in currency value + * @param string|null $creation_request_id Override automatically created request id + * If not set will create a new one, or + * return data for created one + * @return Response\CreateResponse Returns new created response object or + * previous created if creation_request_id was used * * @throws AmazonErrors */ @@ -66,9 +72,13 @@ final class AmazonIncentives /** - * @param string $creation_request_id AWS creationRequestId - * @param string $gift_card_id AWS gcId - * @return Response\CancelResponse + * Cancel a previous created gift card, if within the time frame + * + * @param string $creation_request_id Previous created request id from buyGiftCard + * @param string $gift_card_id Previous gift card id from buyGiftCard (gcId) + * @return Response\CancelResponse Returns the cancled request object + * + * @throws AmazonErrors */ public function cancelGiftCard(string $creation_request_id, string $gift_card_id): Response\CancelResponse { @@ -76,7 +86,9 @@ final class AmazonIncentives } /** - * @return Response\CreateBalanceResponse + * Gets the current funds in this account + * + * @return Response\CreateBalanceResponse Returns the account funds object * * @throws AmazonErrors */ @@ -86,15 +98,15 @@ final class AmazonIncentives } /** - * AmazonIncentives make own client. + * AmazonIncentives creates own client and returns it as static object * - * @param string|null $key - * @param string|null $secret - * @param string|null $partner - * @param string|null $endpoint - * @param string|null $currency - * @param bool|null $debug - * @return AmazonIncentives + * @param string|null $key Account key + * @param string|null $secret Secret key + * @param string|null $partner Partner ID + * @param string|null $endpoint Endpoint URL including https:// + * @param string|null $currency Currency type. Eg USD, JPY, etc + * @param bool|null $debug Debug flag + * @return AmazonIncentives self class */ public static function make( string $key = null, diff --git a/src/Client/Client.php b/src/Client/Client.php index c4281b1..049ebc8 100644 --- a/src/Client/Client.php +++ b/src/Client/Client.php @@ -7,17 +7,18 @@ use gullevek\AmazonIncentives\Debug\AmazonDebug; class Client implements ClientInterface { - // instead of JsonResponse::HTTP_OK + /** @var int instead of JsonResponse::HTTP_OK */ private const HTTP_OK = 200; /** + * Makes an request to the target url via curl + * Returns result as string (json) * - * @param string $url The URL being requested, including domain and protocol - * @param array $headers Headers to be used in the request - * @param array|string $params Can be nested for arrays and hashes - * - * - * @return string + * @param string $url The URL being requested, + * including domain and protocol + * @param array $headers Headers to be used in the request + * @param array|string $params Can be nested for arrays and hashes + * @return string Result as json string */ public function request(string $url, array $headers, $params): string { @@ -76,11 +77,12 @@ class Client implements ClientInterface } /** - * Undocumented function + * handles any CURL errors and throws an error with the correct + * error message * - * @param string $url - * @param int $errno - * @param string $message + * @param string $url The url that was originaly used + * @param int $errno Error number from curl handler + * @param string $message The error message string from curl * @return void */ private function handleCurlError(string $url, int $errno, string $message): void diff --git a/src/Config/Config.php b/src/Config/Config.php index 78f11ab..2ac53c3 100644 --- a/src/Config/Config.php +++ b/src/Config/Config.php @@ -4,37 +4,26 @@ namespace gullevek\AmazonIncentives\Config; class Config implements ConfigInterface { - /** - * @var string - */ + /** @var string Endpoint URL without https:// */ private $endpoint = ''; - /** - * @var string - */ + /** @var string Access Key */ private $access_key = ''; - /** - * @var string - */ + /** @var string Secret Key */ private $secret_key = ''; - /** - * @var string - */ + /** @var string Partner ID */ private $partner_id = ''; - /** - * @var string - */ + /** @var string Currency type as USD, JPY, etc */ private $currency = ''; - /** - * @var bool - */ + /** @var bool Debug flag on or off */ private $debug = false; /** - * @param string|null $key - * @param string|null $secret - * @param string|null $partner - * @param string|null $endpoint - * @param string|null $currency + * @param string|null $key Access key + * @param string|null $secret Secret Key + * @param string|null $partner Partner ID + * @param string|null $endpoint Endpoing URL including https:// + * @param string|null $currency Currency to use, see valid list on AWS documentation. + * valid names are like USD, JPY, etc */ public function __construct( ?string $key, @@ -80,8 +69,8 @@ class Config implements ConfigInterface * string key to search, returns entry from _ENV * if not matchin key, returns empty * - * @param string $key To search in _ENV array - * @return string|bool Returns either string or true/false (DEBUG flag) + * @param string $key To search in _ENV array + * @return string|bool Returns either string or true/false (DEBUG flag) */ private function parseEnv(string $key) { @@ -104,7 +93,7 @@ class Config implements ConfigInterface } /** - * @return string + * @return string Returns current set endpoint, without https:// */ public function getEndpoint(): string { @@ -112,8 +101,8 @@ class Config implements ConfigInterface } /** - * @param string $endpoint - * @return ConfigInterface + * @param string $endpoint Full endpoint url with https:// + * @return ConfigInterface Class interface (self) */ public function setEndpoint(string $endpoint): ConfigInterface { @@ -124,7 +113,7 @@ class Config implements ConfigInterface } /** - * @return string + * @return string Current access key */ public function getAccessKey(): string { @@ -132,8 +121,8 @@ class Config implements ConfigInterface } /** - * @param string $key - * @return ConfigInterface + * @param string $key Access Key to set + * @return ConfigInterface Class interface (self) */ public function setAccessKey(string $key): ConfigInterface { @@ -143,7 +132,7 @@ class Config implements ConfigInterface } /** - * @return string + * @return string Current secret key */ public function getSecret(): string { @@ -151,8 +140,8 @@ class Config implements ConfigInterface } /** - * @param string $secret - * @return ConfigInterface + * @param string $secret Secret key to set + * @return ConfigInterface Class interface (self) */ public function setSecret(string $secret): ConfigInterface { @@ -162,7 +151,7 @@ class Config implements ConfigInterface } /** - * @return string + * @return string Current set currency */ public function getCurrency(): string { @@ -170,8 +159,8 @@ class Config implements ConfigInterface } /** - * @param string $currency - * @return ConfigInterface + * @param string $currency Currency to set (eg USD, JPY, etc) + * @return ConfigInterface Class interface (self) */ public function setCurrency(string $currency): ConfigInterface { @@ -182,7 +171,7 @@ class Config implements ConfigInterface } /** - * @return string + * @return string Current set partner id */ public function getPartner(): string { @@ -190,8 +179,8 @@ class Config implements ConfigInterface } /** - * @param string $partner - * @return ConfigInterface + * @param string $partner Partner id to set + * @return ConfigInterface Class interface (self) */ public function setPartner(string $partner): ConfigInterface { @@ -201,7 +190,7 @@ class Config implements ConfigInterface } /** - * @return bool + * @return bool Current set debug flag as bool */ public function getDebug(): bool { @@ -209,8 +198,8 @@ class Config implements ConfigInterface } /** - * @param bool $debug - * @return ConfigInterface + * @param bool $debug Set debug flag as bool + * @return ConfigInterface Class interface (self) */ public function setDebug(bool $debug): ConfigInterface { diff --git a/src/Config/ConfigInterface.php b/src/Config/ConfigInterface.php index 2acc93a..534bffa 100644 --- a/src/Config/ConfigInterface.php +++ b/src/Config/ConfigInterface.php @@ -5,68 +5,68 @@ namespace gullevek\AmazonIncentives\Config; interface ConfigInterface { /** - * @return string + * @return string Returns current set endpoint, without https:// */ public function getEndpoint(): string; /** - * @param string $endpoint - * @return ConfigInterface + * @param string $endpoint Full endpoint url with https:// + * @return ConfigInterface Class interface (self) */ public function setEndpoint(string $endpoint): ConfigInterface; /** - * @return string + * @return string Current access key */ public function getAccessKey(): string; /** - * @param string $key - * @return ConfigInterface + * @param string $key Access Key to set + * @return ConfigInterface Class interface (self) */ public function setAccessKey(string $key): ConfigInterface; /** - * @return string + * @return string Current secret key */ public function getSecret(): string; /** - * @param string $secret - * @return ConfigInterface + * @param string $secret Secret key to set + * @return ConfigInterface Class interface (self) */ public function setSecret(string $secret): ConfigInterface; /** - * @return string + * @return string Current set currency */ public function getCurrency(): string; /** - * @param string $currency - * @return ConfigInterface + * @param string $currency Currency to set (eg USD, JPY, etc) + * @return ConfigInterface Class interface (self) */ public function setCurrency(string $currency): ConfigInterface; /** - * @return string + * @return string Current set partner id */ public function getPartner(): string; /** - * @param string $partner - * @return ConfigInterface + * @param string $partner Partner id to set + * @return ConfigInterface Class interface (self) */ public function setPartner(string $partner): ConfigInterface; /** - * @return bool + * @return bool Current set debug flag as bool */ public function getDebug(): bool; /** - * @param bool $debug - * @return ConfigInterface + * @param bool $debug Set debug flag as bool + * @return ConfigInterface Class interface (self) */ public function setDebug(bool $debug): ConfigInterface; } diff --git a/src/Debug/AmazonDebug.php b/src/Debug/AmazonDebug.php index cdc5914..b09e20c 100644 --- a/src/Debug/AmazonDebug.php +++ b/src/Debug/AmazonDebug.php @@ -7,17 +7,11 @@ namespace gullevek\AmazonIncentives\Debug; class AmazonDebug { - /** - * @var array - */ + /** @var array Log data array log id -> array of log entries */ private static $log = []; - /** - * @var bool - */ + /** @var bool debug flag */ private static $debug = false; - /** - * @var string|null - */ + /** @var string|null Last set internal log array id */ private static $id = null; /** diff --git a/src/Exceptions/AmazonErrors.php b/src/Exceptions/AmazonErrors.php index d09e0f2..67031db 100644 --- a/src/Exceptions/AmazonErrors.php +++ b/src/Exceptions/AmazonErrors.php @@ -8,12 +8,15 @@ use gullevek\AmazonIncentives\Debug\AmazonDebug; final class AmazonErrors extends RuntimeException { /** - * @param string $error_status agcodResponse->status from Amazon - * @param string $error_code errorCode from Amazon - * @param string $error_type errorType from Amazon - * @param string $message - * @param int $_error_code - * @return AmazonErrors + * Returns an Runtime exception including a json encoded string with all + * parameters including last log id and log + * + * @param string $error_status agcodResponse->status from Amazon + * @param string $error_code errorCode from Amazon + * @param string $error_type errorType from Amazon + * @param string $message Message string to ad + * @param int $_error_code Error code to set + * @return AmazonErrors Exception Class */ public static function getError( string $error_status, diff --git a/src/Response/CancelResponse.php b/src/Response/CancelResponse.php index bce6dae..bcf7ac4 100644 --- a/src/Response/CancelResponse.php +++ b/src/Response/CancelResponse.php @@ -6,34 +6,19 @@ use gullevek\AmazonIncentives\Debug\AmazonDebug; class CancelResponse { - /** - * Amazon Gift Card gcId. - * - * @var string - */ + /** @var string Amazon Gift Card gcId (gift card id). */ protected $id = ''; - /** - * Amazon Gift Card creationRequestId - * - * @var string - */ + /** @var string Amazon Gift Card creationRequestId (creation request id) */ protected $creation_request_id = ''; - /** - * Amazon Gift Card status - * - * @var string - */ + /** @var string Amazon Gift Card status */ protected $status = ''; - /** - * Amazon Gift Card Raw JSON - * - * @var array - */ + /** @var array Amazon Gift Card Raw JSON */ protected $raw_json = []; /** - * Response constructor. - * @param array $json_response + * Response constructor for canceling gitf cards + * + * @param array $json_response JSON response from web request to AWS */ public function __construct(array $json_response) { @@ -42,7 +27,9 @@ class CancelResponse } /** - * @return array + * Get log entry with current set log id + * + * @return array Log array */ public function getLog(): array { @@ -50,7 +37,9 @@ class CancelResponse } /** - * @return string + * The gift card id as created by the previous get code call + * + * @return string Gift card id */ public function getId(): string { @@ -58,7 +47,9 @@ class CancelResponse } /** - * @return string + * Creation Request id from original get code call + * + * @return string Creation request id */ public function getCreationRequestId(): string { @@ -66,7 +57,9 @@ class CancelResponse } /** - * @return string + * Request status + * + * @return string Request status as string: SUCCESS, FAILURE, RESEND */ public function getStatus(): string { @@ -74,7 +67,10 @@ class CancelResponse } /** - * @return string + * Returns the request data as json string. This is a re-encode from decoded + * makeRequest call + * + * @return string JSON encoded string from the return values */ public function getRawJson(): string { @@ -82,8 +78,10 @@ class CancelResponse } /** - * @param array $json_response - * @return CancelResponse + * Set class variables with response data from makeRequest and return self + * + * @param array $json_response JSON response as array + * @return CancelResponse Return self object */ public function parseJsonResponse(array $json_response): self { diff --git a/src/Response/CreateBalanceResponse.php b/src/Response/CreateBalanceResponse.php index d7509e4..577faba 100644 --- a/src/Response/CreateBalanceResponse.php +++ b/src/Response/CreateBalanceResponse.php @@ -6,41 +6,21 @@ use gullevek\AmazonIncentives\Debug\AmazonDebug; class CreateBalanceResponse { - /** - * Amazon Gift Card Balance Amount - * - * @var string - */ + /** @var string Amazon Gift Card Balance Amount */ protected $amount = ''; - /** - * Amazon Gift Card Balance Currency - * - * @var string - */ + /** @var string Amazon Gift Card Balance Currency */ protected $currency = ''; - /** - * Amazon Gift Card Balance Status - * - * @var string - */ + /** @var string Amazon Gift Card Balance Status */ protected $status = ''; - /** - * Amazon Gift Card Balance Timestamp - * - * @var string - */ + /** @var string Amazon Gift Card Balance Timestamp */ protected $timestamp = ''; - /** - * Amazon Gift Card Raw JSON - * - * @var array - */ + /** @var array Amazon Gift Card Raw JSON */ protected $raw_json = []; /** - * Response constructor. + * Response constructor for requesting account funds status * - * @param array $json_response + * @param array $json_response JSON response from web request to AWS */ public function __construct(array $json_response) { @@ -49,7 +29,9 @@ class CreateBalanceResponse } /** - * @return array + * Get log entry with current set log id + * + * @return array Log array */ public function getLog(): array { @@ -57,7 +39,9 @@ class CreateBalanceResponse } /** - * @return string + * Return the current available funds amount + * + * @return string Funds amount in set currency */ public function getAmount(): string { @@ -65,7 +49,9 @@ class CreateBalanceResponse } /** - * @return string + * Get the set currency type + * + * @return string Currency type. Eg USD, JPY, etc */ public function getCurrency(): string { @@ -73,15 +59,10 @@ class CreateBalanceResponse } /** - * @return string - */ - public function getStatus(): string - { - return $this->status; - } - - /** - * @return string + * Get timestamp as set. + * eg 20220609T061446Z + * + * @return string Timestamp string. Ymd\THis\Z */ public function getTimestamp(): string { @@ -89,7 +70,20 @@ class CreateBalanceResponse } /** - * @return string + * Request status + * + * @return string Request status as string: SUCCESS, FAILURE, RESEND + */ + public function getStatus(): string + { + return $this->status; + } + + /** + * Returns the request data as json string. This is a re-encode from decoded + * makeRequest call + * + * @return string JSON encoded string from the return values */ public function getRawJson(): string { @@ -97,10 +91,10 @@ class CreateBalanceResponse } /** - * Undocumented function + * Set class variables with response data from makeRequest and return self * - * @param array $json_response - * @return CreateBalanceResponse + * @param array $json_response JSON response as array + * @return CreateBalanceResponse Return self object */ public function parseJsonResponse(array $json_response): self { diff --git a/src/Response/CreateResponse.php b/src/Response/CreateResponse.php index 8624d3d..cb57453 100644 --- a/src/Response/CreateResponse.php +++ b/src/Response/CreateResponse.php @@ -6,68 +6,29 @@ use gullevek\AmazonIncentives\Debug\AmazonDebug; class CreateResponse { - /** - * Amazon Gift Card gcId. - * - * @var string - */ + /** @var string Amazon Gift Card gcId */ protected $id = ''; - - /** - * Amazon Gift Card creationRequestId - * - * @var string - */ + /** @var string Amazon Gift Card creationRequestId */ protected $creation_request_id = ''; - - /** - * Amazon Gift Card gcClaimCode - * - * @var string - */ + /** @var string Amazon Gift Card gcClaimCode */ protected $claim_code = ''; - - /** - * Amazon Gift Card amount - * - * @var float - */ + /** @var float Amazon Gift Card amount */ protected $value = 0; - - /** - * Amazon Gift Card currency - * - * @var string - */ + /** @var string Amazon Gift Card currency */ protected $currency = ''; - /** - * Amazon Gift Card status - * - * @var string - */ + /** @var string Amazon Gift Card status */ protected $status = ''; - /** - * Amazon Gift Card Expiration Date - * - * @var string - */ + /** @var string Amazon Gift Card Expiration Date */ protected $expiration_date = ''; - /** - * Amazon Gift Card Expiration Date - * - * @var string - */ + /** @var string Amazon Gift Card Expiration Date */ protected $card_status = ''; - /** - * Amazon Gift Card Raw JSON - * - * @var array - */ + /** @var array Amazon Gift Card Raw JSON as array */ protected $raw_json = []; /** - * Response constructor. - * @param array $json_response + * Response constructor for creating gift cards + * + * @param array $json_response JSON response from web request to AWS */ public function __construct(array $json_response) { @@ -76,7 +37,9 @@ class CreateResponse } /** - * @return array + * Get log entry with current set log id + * + * @return array Log array */ public function getLog(): array { @@ -84,7 +47,9 @@ class CreateResponse } /** - * @return string + * Gift Card ID returned from AWS. Can be used in the cancel request + * + * @return string Gift card id */ public function getId(): string { @@ -92,7 +57,10 @@ class CreateResponse } /** - * @return string + * Either the one set with the method parameter, or automatically created + * during get code request + * + * @return string Creation request id */ public function getCreationRequestId(): string { @@ -100,7 +68,10 @@ class CreateResponse } /** - * @return string + * The actual gift code, recommended not to be stored anywhere and only shown + * to user + * + * @return string Gift order claim code on AWS */ public function getClaimCode(): string { @@ -108,7 +79,9 @@ class CreateResponse } /** - * @return float + * The ordered gift code value in given currency + * + * @return float Gift order value in currency */ public function getValue(): float { @@ -116,7 +89,9 @@ class CreateResponse } /** - * @return string + * The currently set currency + * + * @return string Currency type. Eg USD, JPY, etc */ public function getCurrency(): string { @@ -124,15 +99,10 @@ class CreateResponse } /** - * @return string - */ - public function getStatus(): string - { - return $this->status; - } - - /** - * @return string + * Expiration date for the ordered gift code. + * eg 20220609T061446Z + * + * @return string Timestamp until when the gift code is valid. Ymd\THis\Z */ public function getExpirationDate(): string { @@ -140,16 +110,31 @@ class CreateResponse } /** - * @return string + * Gift card status. If the same creation request id is sent again and the + * gift card got cancled, this is reflected here + * + * @return string Gift card status */ public function getCardStatus(): string { return $this->card_status; } + /** + * Request status + * + * @return string Request status as string: SUCCESS, FAILURE, RESEND + */ + public function getStatus(): string + { + return $this->status; + } /** - * @return string + * @Returns the request data as json string. This is a re-encode from decoded + * makeRequest call + * + * @return string JSON encoded string from the return values */ public function getRawJson(): string { @@ -157,8 +142,10 @@ class CreateResponse } /** - * @param array $json_response - * @return CreateResponse + * Set class variables with response data from makeRequest and return self + * + * @param array $json_response JSON response as array + * @return CreateResponse Return self object */ public function parseJsonResponse(array $json_response): self {