Fully tested for Nimbus (#8)

* feature: implement addTagToCustomer for #2

* feature: implement removeTagFromCustomer for #5

* wip: create customer if it doesn't already exist

* wip: static analysis improvements

* feature: create customer
closes #7

* test: manually calculate auth signature

* test: create customer

* test: get customer by id or email

* test: tags

* tweak: typehint loop

example/04-assign-tag-to-customer.php

@@ -53,4 +53,16 @@
 	exit(4);
 }
 
-$client->addTagToCustomer($tag, $customer);
+echo "Customer's tags before addition:\n";
+foreach($client->getTagsForCustomer($customer) as $customerTag) {
+	echo "- $customerTag->name ($customerTag->id)\n";
+}
+
+$addedTag = $client->addTagToCustomer($tag, $customer);
+
+echo "\nAdded tag \"$addedTag->name\" to customer $customer->email\n\n";
+
+echo "All customer's tags after addition:\n";
+foreach($client->getTagsForCustomer($customer) as $customerTag) {
+	echo "- $customerTag->name ($customerTag->id)\n";
+}

example/05-remove-tag-from-customer.php

@@ -0,0 +1,67 @@
+<?php
+/**
+ * This example removes a tag from a customer. The tag ID must
+ * be the first argument to the script, the customer ID must be the second
+ * argument to the script.
+ *
+ * For any example to work, you must supply your own secrets in config.ini:
+ * - username
+ * - client
+ * - secret_key
+ */
+
+use BrightFlair\SpektrixAPI\CustomerNotFoundException;
+use BrightFlair\SpektrixAPI\TagNotFoundException;
+
+chdir(dirname(__DIR__));
+require "vendor/autoload.php";
+
+$config = parse_ini_file("config.ini");
+$client = new BrightFlair\SpektrixAPI\Client(
+	$config["username"],
+	$config["client"],
+	$config["secret_key"],
+);
+
+$tagId = $argv[1] ?? null;
+if(!$tagId) {
+	fwrite(STDERR, "No tag ID supplied\n");
+	exit(1);
+}
+
+$customerId = $argv[2] ?? null;
+if(!$customerId) {
+	fwrite(STDERR, "No customer ID supplied\n");
+	exit(2);
+}
+
+$tag = null;
+try {
+	$tag = $client->getTag(id: $tagId);
+}
+catch(TagNotFoundException) {
+	fwrite(STDERR, "No tag found with ID $tagId\n");
+	exit(3);
+}
+
+$customer = null;
+try {
+	$customer = $client->getCustomer(id: $customerId);
+}
+catch(CustomerNotFoundException) {
+	fwrite(STDERR, "No customer found with ID $customerId\n");
+	exit(4);
+}
+
+echo "Customer's tags before removal:\n";
+foreach($client->getTagsForCustomer($customer) as $customerTag) {
+	echo "- $customerTag->name ($customerTag->id)\n";
+}
+
+$client->removeTagFromCustomer($tag, $customer);
+echo "\nRemoved tag from customer!\n\n";
+
+echo "All customer's tags after removal:\n";
+foreach($client->getTagsForCustomer($customer) as $customerTag) {
+	echo "- $customerTag->name ($customerTag->id)\n";
+}

example/06-create-customer-if-no-match.php

@@ -0,0 +1,71 @@
+<?php
+/**
+ * This example attempts to find a customer by the email address, supplied as
+ * the first argument to the script. If there is no match, it will create a new
+ * customer.
+ *
+ * The script requires the following arguments, in order:
+ * 1. email address
+ * 2. first name
+ * 3. last name
+ * 4. mobile number
+ *
+ * For any example to work, you must supply your own secrets in config.ini:
+ * - username
+ * - client
+ * - secret_key
+ */
+
+use BrightFlair\SpektrixAPI\CustomerNotFoundException;
+
+chdir(dirname(__DIR__));
+require "vendor/autoload.php";
+
+$config = parse_ini_file("config.ini");
+$client = new BrightFlair\SpektrixAPI\Client(
+	$config["username"],
+	$config["client"],
+	$config["secret_key"],
+);
+
+$email = $argv[1] ?? null;
+if(!$email) {
+	fwrite(STDERR, "No email address supplied\n");
+	exit(1);
+}
+$firstName = $argv[2] ?? null;
+if(!$firstName) {
+	fwrite(STDERR, "No first name supplied\n");
+	exit(1);
+}
+$lastName = $argv[3] ?? null;
+if(!$lastName) {
+	fwrite(STDERR, "No last name supplied\n");
+	exit(1);
+}
+$mobileNumber = $argv[4] ?? null;
+if(!$mobileNumber) {
+	fwrite(STDERR, "No mobile number supplied\n");
+	exit(1);
+}
+
+try {
+	$customer = $client->getCustomer(email: $email);
+	echo "Customer found!\n";
+	echo "ID: $customer->id\n";
+	echo "Email: $customer->email\n";
+	echo "First name: $customer->firstName\n";
+	echo "Last name: $customer->lastName\n";
+}
+catch(CustomerNotFoundException) {
+	echo "No customer was found with the email address $email\n";
+	echo "Creating new customer...\n";
+
+	$customer = $client->createCustomer($email, $firstName, $lastName, $mobileNumber);
+	echo "New customer created successfully:\n";
+	echo "ID: $customer->id\n";
+	echo "Email: $customer->email\n";
+	echo "First name: $customer->firstName\n";
+	echo "Last name: $customer->lastName\n";
+	echo "Mobile: $customer->mobile\n";
+}

phpcs.xml

@@ -19,7 +19,6 @@
 	<rule ref="Generic.Files.EndFileNewline" />
 	<rule ref="Generic.Files.InlineHTML" />
 	<rule ref="Generic.Files.LineEndings" />
-	<rule ref="Generic.Files.LineLength" />
 	<rule ref="Generic.Files.OneClassPerFile" />
 	<rule ref="Generic.Files.OneInterfacePerFile" />
 	<rule ref="Generic.Files.OneObjectStructurePerFile" />

src/AuthenticatedRequest.php

@@ -5,6 +5,7 @@ class AuthenticatedRequest {
 	public string $httpMethod;
 	public readonly string $uri;
 	public readonly Signature $signature;
+	public readonly ?string $body;
 
 	/** @param array<string, string> $kvp */
 	public function __construct(
@@ -18,9 +19,9 @@ public function __construct(
 			$endpoint->value,
 			2,
 		);
-		$bodyString = null;
+		$httpBodyString = null;
 		if(str_contains($endpointPath, " ")) {
-			[$endpointPath, $bodyString] = explode(
+			[$endpointPath, $httpBodyString] = explode(
 				" ",
 				$endpointPath,
 			);
@@ -31,21 +32,41 @@ public function __construct(
 			$endpointPath,
 		]);
 		$uri = str_replace("{client}", $client, $uri);
+		/**
+		 * @var string $key
+		 * @var ?string $value
+		 */
 		foreach($kvp as $key => $value) {
 			$uri = str_replace(
 				"{" . $key . "}",
-				$value,
+				$value ?? "",
 				$uri,
 			);
+
+			if($httpBodyString) {
+				$httpBodyString = str_replace(
+					"{" . $key . "}",
+					$value,
+					$httpBodyString,
+				);
+			}
 		}
 
 		$this->httpMethod = $httpMethod;
 		$this->uri = $uri;
+
+		$jsonBodyString = null;
+		if($httpBodyString) {
+			parse_str($httpBodyString, $bodyKvp);
+			$jsonBodyString = json_encode($bodyKvp);
+		}
+
+		$this->body = $jsonBodyString;
 		$this->signature = new Signature(
 			$secretKey,
 			$httpMethod,
 			$this->uri,
-			$bodyString,
+			$this->body,
 		);
 	}
 }