Update to version 1.2.0

Version 1.2.0:
- Added custom exceptions per class, with multiple specific exception codes per exception. All exceptions are extended from LEException, which is extended from RuntimeException, and therefore backwards compatible. Response data (request, header, status, body) is added when LEConnectorException::InvalidResponseException is thrown.
- All GET requests, except from the initial /directory request, are changed to POST-as-GET requests to comply with ACME changes. This also resolves current related issues when using the staging endpoint.
- Bugfix in LEAccount->updateAccount(), implemented isset check for $post['body']['id'] similair to LEAccount->getLEAccountData().
- Bugfix in LEAccount->deactivateAccount(), now returns true after deactivation.
- Change in LEOrder setup parameter check (notBefore and notAfter).
- Example code endpoint changed to staging endpoint.
- All code has been extensively tested again.

README.md

@@ -3,11 +3,7 @@ PHP LetsEncrypt client library for ACME v2. The aim of this client is to make an
 
 ## Current version
 
-The current version is 1.1.11
-
-The example codes below are to be updated.
-
-This client was developed with the use of the LetsEncrypt staging server for version 2. While version 2 is still being developed and implemented by LetsEncrypt at this moment, the project might be subject to change.
+The current version is 1.2.0
 
 ## Getting Started
 
@@ -17,7 +13,9 @@ Also have a look at the [LetsEncrypt documentation](https://letsencrypt.org/docs
 
 ### Prerequisites
 
-The minimum required PHP version is 5.2.0. Version 7.1.0 is required for EC keys. The function generating EC keys will throw an exception when trying to generate EC keys with a PHP version below 7.1.0. Version 1.0.0 will be kept available, but will not be maintained.
+The minimum required PHP version is 5.2.0. Version 7.1.0 is required for EC keys. The function generating EC keys will throw an exception when trying to generate EC keys with a PHP version below 7.1.0.
+
+Version 1.0.0 will be kept available, but will not be maintained.
 
 This client also depends on cURL and OpenSSL.
 
@@ -28,9 +26,7 @@ Using composer:
 composer require yourivw/leclient
 ```
 
-Although it is possible to add this to your own autoloader, it's not recommended as you'll have no control of the dependencies. If you haven't used composer before, I strongly recommend you check it out at [https://getcomposer.org](https://getcomposer.org).
-
-It is advisable to cut the script some slack regarding execution time by setting a higher maximum time. There are several ways to do so. One it to add the following to the top of the page:
+It is advisable to cut the script some slack regarding execution time by setting a higher maximum time. There are several ways to do so. One is to add the following to the top of the page:
 ```php
 ini_set('max_execution_time', 120); // Maximum execution time in seconds.
 ```
@@ -47,11 +43,13 @@ Initiating the client:
 ```php
 use LEClient\LEClient;
 
-$client = new LEClient($email);                               				// Initiating a basic LEClient with an array of string e-mail address(es).
-$client = new LEClient($email, true);                         				// Initiating a LECLient and use the LetsEncrypt staging URL.
-$client = new LEClient($email, true, $logger);   					// Initiating a LEClient and use a PSR-3 logger (\Psr\Log\LoggerInterface).
-$client = new LEClient($email, true, LEClient::LOG_STATUS);   				// Initiating a LEClient and log status messages (LOG_DEBUG for full debugging).
-$client = new LEClient($email, true, LEClient::LOG_STATUS, 'keys/');   			// Initiating a LEClient and select custom certificate keys directory (string or array)
+$client = new LEClient($email);														// Initiating a basic LEClient with an array of string e-mail address(es).
+$client = new LEClient($email, LEClient::LE_STAGING);								// Initiating a LECLient and use the LetsEncrypt staging URL.
+$client = new LEClient($email, LEClient::LE_PRODUCTION);							// Initiating a LECLient and use the LetsEncrypt production URL.
+$client = new LEClient($email, true);												// Initiating a LECLient and use the LetsEncrypt staging URL.
+$client = new LEClient($email, true, $logger);										// Initiating a LEClient and use a PSR-3 logger (\Psr\Log\LoggerInterface).
+$client = new LEClient($email, true, LEClient::LOG_STATUS);							// Initiating a LEClient and log status messages (LOG_DEBUG for full debugging).
+$client = new LEClient($email, true, LEClient::LOG_STATUS, 'keys/');				// Initiating a LEClient and select custom certificate keys directory (string or array)
 $client = new LEClient($email, true, LEClient::LOG_STATUS, 'keys/', '__account/');	// Initiating a LEClient and select custom account keys directory (string or array)
 ```
 The client will automatically create a new account if there isn't one found. It will forward the e-mail address(es) supplied during initiation, as shown above.
@@ -78,6 +76,8 @@ $order = $client->getOrCreateOrder($basename, $domains, $keyType, $notBefore, $n
 
 Using the order functions:
 ```php
+use LEClient\LEOrder;
+
 $valid      = $order->allAuthorizationsValid();                             // Check whether all authorizations in this order instance are valid.
 $pending    = $order->getPendingAuthorizations($type);                      // Get an array of pending authorizations. Performing authorizations is described further on. Type is LEOrder::CHALLENGE_TYPE_HTTP or LEOrder::CHALLENGE_TYPE_DNS.
 $verify     = $order->verifyPendingOrderAuthorization($identifier, $type);  // Verify a pending order. The identifier is a string domain name. Type is LEOrder::CHALLENGE_TYPE_HTTP or LEOrder::CHALLENGE_TYPE_DNS.
@@ -176,7 +176,7 @@ The DNS record name also depends on your provider, therefore getPendingAuthoriza
 
 For both HTTP and DNS authorizations, a full example is available in the project's main code directory. The HTTP authorization example is contained in one file. As described above, the DNS authorization example is split into two parts, to allow for the DNS record to update in the meantime. While the TTL of the record might be low, it can sometimes take some time for your provider to update your DNS records after an amendment.
 
-If you can't get these examples, or the client library to work, try and have a look at the LetsEncrypt documentation mentioned above as well.
+If you can't get these examples, or the client library to work, try and have a look at the LetsEncrypt documentation mentioned above as well. In order for the example code to work, make sure to replace all 'example.org' information with your own information. The examples will fail when you run them using the preset example data.
 
 ## Security
 

examples/dns_finish.php

@@ -16,7 +16,7 @@
 $domains = array('example.org', 'test.example.org');
 
 // Initiating the client instance. In this case using the staging server (argument 2) and outputting all status and debug information (argument 3).
-$client = new LEClient($email, true, LECLient::LOG_STATUS);
+$client = new LEClient($email, LEClient::LE_STAGING, LECLient::LOG_STATUS);
 // Initiating the order instance. The keys and certificate will be stored in /example.org/ (argument 1) and the domains in the array (argument 2) will be on the certificate.
 $order = $client->getOrCreateOrder($basename, $domains);
 // Check whether there are any authorizations pending. If that is the case, try to verify the pending authorizations.

examples/dns_init.php

@@ -16,7 +16,7 @@
 $domains = array('example.org', 'test.example.org');
 
 // Initiating the client instance. In this case using the staging server (argument 2) and outputting all status and debug information (argument 3).
-$client = new LEClient($email, true, LECLient::LOG_STATUS);
+$client = new LEClient($email, LEClient::LE_STAGING, LECLient::LOG_STATUS);
 // Initiating the order instance. The keys and certificate will be stored in /example.org/ (argument 1) and the domains in the array (argument 2) will be on the certificate.
 $order = $client->getOrCreateOrder($basename, $domains);
 // Check whether there are any authorizations pending. If that is the case, try to verify the pending authorizations.

examples/http.php

@@ -16,7 +16,7 @@
 $domains = array('example.org', 'test.example.org');
 
 // Initiating the client instance. In this case using the staging server (argument 2) and outputting all status and debug information (argument 3).
-$client = new LEClient($email, true, LECLient::LOG_STATUS);
+$client = new LEClient($email, LEClient::LE_STAGING, LECLient::LOG_STATUS);
 // Initiating the order instance. The keys and certificate will be stored in /example.org/ (argument 1) and the domains in the array (argument 2) will be on the certificate.
 $order = $client->getOrCreateOrder($basename, $domains);
 // Check whether there are any authorizations pending. If that is the case, try to verify the pending authorizations.

src/Exceptions/LEAccountException.php

@@ -0,0 +1,46 @@
+<?php
+
+namespace LEClient\Exceptions;
+
+/**
+ * LetsEncrypt Client Account exception, extends LEException
+ *
+ * PHP version 5.2.0
+ *
+ * MIT License
+ *
+ * Copyright (c) 2020 Youri van Weegberg
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy
+ * of this software and associated documentation files (the "Software"), to deal
+ * in the Software without restriction, including without limitation the rights
+ * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+ * copies of the Software, and to permit persons to whom the Software is
+ * furnished to do so, subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in all
+ * copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+ * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+ * SOFTWARE.
+ *
+ * @author     Youri van Weegberg <[email protected]>
+ * @copyright  2020 Youri van Weegberg
+ * @license    https://opensource.org/licenses/mit-license.php  MIT License
+ * @link       https://github.com/yourivw/LEClient
+ * @since      Class available since Release 1.2.0
+ */
+class LEAccountException extends LEException
+{
+	public const ACCOUNTNOTFOUNDEEXCEPTION 	= 0x21;
+
+	public static function AccountNotFoundException()
+	{
+		return new static('Account not found or deactivated.', self::ACCOUNTNOTFOUNDEEXCEPTION);
+	}
+}

src/Exceptions/LEAuthorizationException.php

@@ -0,0 +1,46 @@
+<?php
+
+namespace LEClient\Exceptions;
+
+/**
+ * LetsEncrypt Client Authorization exception, extends LEException
+ *
+ * PHP version 5.2.0
+ *
+ * MIT License
+ *
+ * Copyright (c) 2020 Youri van Weegberg
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy
+ * of this software and associated documentation files (the "Software"), to deal
+ * in the Software without restriction, including without limitation the rights
+ * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+ * copies of the Software, and to permit persons to whom the Software is
+ * furnished to do so, subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in all
+ * copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+ * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+ * SOFTWARE.
+ *
+ * @author     Youri van Weegberg <[email protected]>
+ * @copyright  2020 Youri van Weegberg
+ * @license    https://opensource.org/licenses/mit-license.php  MIT License
+ * @link       https://github.com/yourivw/LEClient
+ * @since      Class available since Release 1.2.0
+ */
+class LEAuthorizationException extends LEException
+{
+	public const NOCHALLENGEFOUNDEEXCEPTION	= 0x41;
+
+	public static function NoChallengeFoundException($type, $identifier)
+	{
+		return new static(sprintf('No challenge found for type \'%s\' and identifier \'%s\'.', $type, $identifier), self::NOCHALLENGEFOUNDEEXCEPTION);
+	}
+}

src/Exceptions/LEClientException.php

@@ -0,0 +1,52 @@
+<?php
+
+namespace LEClient\Exceptions;
+
+/**
+ * LetsEncrypt Client exception, extends LEException
+ *
+ * PHP version 5.2.0
+ *
+ * MIT License
+ *
+ * Copyright (c) 2020 Youri van Weegberg
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy
+ * of this software and associated documentation files (the "Software"), to deal
+ * in the Software without restriction, including without limitation the rights
+ * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+ * copies of the Software, and to permit persons to whom the Software is
+ * furnished to do so, subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in all
+ * copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+ * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+ * SOFTWARE.
+ *
+ * @author     Youri van Weegberg <[email protected]>
+ * @copyright  2020 Youri van Weegberg
+ * @license    https://opensource.org/licenses/mit-license.php  MIT License
+ * @link       https://github.com/yourivw/LEClient
+ * @since      Class available since Release 1.2.0
+ */
+class LEClientException extends LEException
+{
+	public const INVALIDARGUMENTEXCEPTION 	= 0x01;
+	public const INVALIDDIRECTORYEXCEPTION 	= 0x02;
+
+	public static function InvalidArgumentException(string $message)
+	{
+		return new static($message, self::INVALIDARGUMENTEXCEPTION);
+	}
+
+	public static function InvalidDirectoryException(string $directory)
+	{
+		return new static(sprintf('%s directory not found.', $directory), self::INVALIDDIRECTORYEXCEPTION);
+	}
+}

src/Exceptions/LEConnectorException.php

@@ -0,0 +1,71 @@
+<?php
+
+namespace LEClient\Exceptions;
+
+/**
+ * LetsEncrypt Client Connector exception, extends LEException
+ *
+ * PHP version 5.2.0
+ *
+ * MIT License
+ *
+ * Copyright (c) 2020 Youri van Weegberg
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy
+ * of this software and associated documentation files (the "Software"), to deal
+ * in the Software without restriction, including without limitation the rights
+ * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+ * copies of the Software, and to permit persons to whom the Software is
+ * furnished to do so, subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in all
+ * copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+ * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+ * SOFTWARE.
+ *
+ * @author     Youri van Weegberg <[email protected]>
+ * @copyright  2020 Youri van Weegberg
+ * @license    https://opensource.org/licenses/mit-license.php  MIT License
+ * @link       https://github.com/yourivw/LEClient
+ * @since      Class available since Release 1.2.0
+ */
+class LEConnectorException extends LEException
+{
+	public const NONEWNONCEEXCEPTION 			= 0x11;
+	public const ACCOUNTDEACTIVATEDEXCEPTION 	= 0x12;
+	public const METHODNOTSUPPORTEDEXCEPTION 	= 0x13;
+	public const CURLERROREXCEPTION 			= 0x14;
+	public const INVALIDRESPONSEEXCEPTION 		= 0x15;
+
+	public static function NoNewNonceException()
+	{
+		return new static('No new nonce.', self::NONEWNONCEEXCEPTION);
+	}
+
+	public static function AccountDeactivatedException()
+	{
+		return new static('The account was deactivated. No further requests can be made.', self::ACCOUNTDEACTIVATEDEXCEPTION);
+	}
+
+	public static function MethodNotSupportedException(string $method)
+	{
+		return new static(sprintf('HTTP request %s not supported.', $method), self::METHODNOTSUPPORTEDEXCEPTION);
+	}
+
+	public static function CurlErrorException(string $error)
+	{
+		return new static(sprintf('Curl error: %s', $error), self::CURLERROREXCEPTION);
+	}
+
+	public static function InvalidResponseException(array $response)
+	{
+		$statusCode = array_key_exists('status', $response) ? $response['status'] : 'unknown';
+		return new static(sprintf('Invalid response: %s', $statusCode), self::INVALIDRESPONSEEXCEPTION, null, $response);
+	}
+}

src/Exceptions/LEException.php

@@ -0,0 +1,52 @@
+<?php
+
+namespace LEClient\Exceptions;
+
+/**
+ * LetsEncrypt Client base exception, extends PHP's RuntimeException.
+ *
+ * PHP version 5.2.0
+ *
+ * MIT License
+ *
+ * Copyright (c) 2020 Youri van Weegberg
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy
+ * of this software and associated documentation files (the "Software"), to deal
+ * in the Software without restriction, including without limitation the rights
+ * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+ * copies of the Software, and to permit persons to whom the Software is
+ * furnished to do so, subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in all
+ * copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+ * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+ * SOFTWARE.
+ *
+ * @author     Youri van Weegberg <[email protected]>
+ * @copyright  2020 Youri van Weegberg
+ * @license    https://opensource.org/licenses/mit-license.php  MIT License
+ * @link       https://github.com/yourivw/LEClient
+ * @since      Class available since Release 1.2.0
+ */
+class LEException extends \RuntimeException
+{
+	protected $responsedata;
+
+	public function __construct(string $message = "", int $code = 0, Throwable $previous = NULL, array $responsedata = NULL)
+	{
+		parent::__construct($message, $code, $previous);
+		$this->responsedata = $responsedata;
+	}
+
+	public function getResponseData(): ?array
+	{
+		return $this->responsedata;
+	}
+}