Merge pull request #22 from ConvertKit/add-get-by-method

Add `get_by` method

src/class-convertkit-resource.php

@@ -146,26 +146,8 @@ public function get() {
 			return $resources;
 		}
 
-		// Don't attempt sorting if the order_by property doesn't exist as a key
-		// in the API response.
-		if ( ! array_key_exists( $this->order_by, reset( $resources ) ) ) {
-			return $resources;
-		}
-
-		// Sort resources ascending by the order_by property.
-		uasort(
-			$resources,
-			function( $a, $b ) {
-				return strcmp( $a[ $this->order_by ], $b[ $this->order_by ] );
-			}
-		);
-
-		// Reverse the array if the results should be returned in descending order.
-		if ( $this->order === 'desc' ) {
-			$resources = array_reverse( $resources, true );
-		}
-
-		return $resources;
+		// Return resources sorted by order_by and order.
+		return $this->sort( $resources );
 
 	}
 
@@ -190,6 +172,88 @@ public function get_by_id( $id ) {
 
 	}
 
+	/**
+	 * Returns resources where the resource's key matches the given value.
+	 *
+	 * @since   1.3.6
+	 *
+	 * @param   string       $key    Resource Key.
+	 * @param   string|array $value  Value(s).
+	 * @return  bool|array
+	 */
+	public function get_by( $key, $value ) {
+
+		// Don't mutate the underlying resources, so multiple calls to get()
+		// with different order_by and order properties are supported.
+		$resources = $this->resources;
+
+		// Don't attempt sorting if no resources exist.
+		if ( ! $this->exist() ) {
+			return $resources;
+		}
+
+		foreach ( $resources as $id => $resource ) {
+			// Remove this resource if it doesn't have the array key.
+			if ( ! array_key_exists( $key, $resource ) ) {
+				unset( $resources[ $id ] );
+				continue;
+			}
+
+			// Remove this resource if the value is an array and none of the array values match.
+			if ( is_array( $value ) && ! in_array( $resource[ $key ], $value, true ) ) {
+				unset( $resources[ $id ] );
+				continue;
+			}
+
+			// Remove this resource if the value doesn't match.
+			if ( ! is_array( $value ) && $resource[ $key ] !== $value ) {
+				unset( $resources[ $id ] );
+				continue;
+			}
+		}
+
+		// If the array is empty, return false.
+		if ( empty( $resources ) ) {
+			return false;
+		}
+
+		// Return resources sorted by order_by and order.
+		return $this->sort( $resources );
+
+	}
+
+	/**
+	 * Sorts the given array of resources by the class' order_by and order properties.
+	 *
+	 * @since   1.3.6
+	 *
+	 * @param   array $resources  Resources.
+	 * @return  array               Resources
+	 */
+	public function sort( $resources ) {
+
+		// Don't attempt sorting if the order_by property doesn't exist as a key
+		// in the API response.
+		if ( ! array_key_exists( $this->order_by, reset( $resources ) ) ) {
+			return $resources;
+		}
+
+		// Sort resources ascending by the order_by property.
+		uasort(
+			$resources,
+			function( $a, $b ) {
+				return strcmp( $a[ $this->order_by ], $b[ $this->order_by ] );
+			}
+		);
+
+		// Reverse the array if the results should be returned in descending order.
+		if ( $this->order === 'desc' ) {
+			$resources = array_reverse( $resources, true );
+		}
+
+		return $resources;
+
+	}
 
 	/**
 	 * Returns a paginated subset of resources, including whether

tests/wpunit/ResourceTest.php

@@ -197,4 +197,55 @@ public function testGetWithValidOrderByAndOrder()
 		$this->assertEquals('2022-05-03T14:51:50.000Z', reset($result)['published_at']);
 		$this->assertEquals('2022-01-24T00:00:00.000Z', end($result)['published_at']);
 	}
+
+	/**
+	 * Tests that the get_by() function returns the matching resource when queried
+	 * by name.
+	 *
+	 * @since   1.3.6
+	 */
+	public function testGetBy()
+	{
+		// Call resource class' get_by() function.
+		$result = $this->resource->get_by('name', 'Z Name');
+
+		// Assert result is an array.
+		$this->assertIsArray($result);
+
+		// Assert one item was returned.
+		$this->assertCount(1, $result);
+
+		// Assert array keys are preserved.
+		$this->assertArrayHasKey(array_key_first($this->resource->resources), $result);
+
+		// Assert resource is the one we requested.
+		$this->assertEquals('Z Name', reset($result)[ $this->resource->order_by ]);
+	}
+
+	/**
+	 * Tests that the get_by() function returns the matching resources when queried
+	 * by multiple values.
+	 *
+	 * @since   1.3.6
+	 */
+	public function testGetByMultipleValues()
+	{
+		// Call resource class' get_by() function.
+		$result = $this->resource->get_by('name', [ 'A Name', 'Z Name' ]);
+
+		// Assert result is an array.
+		$this->assertIsArray($result);
+
+		// Assert two items were returned.
+		$this->assertCount(2, $result);
+
+		// Assert array keys are preserved.
+		$this->assertArrayHasKey(array_key_first($this->resource->resources), $result);
+		$this->assertArrayHasKey(array_key_last($this->resource->resources), $result);
+
+		// Assert order of data is in ascending alphabetical order.
+		$this->assertEquals('A Name', reset($result)[ $this->resource->order_by ]);
+		$this->assertEquals('Z Name', end($result)[ $this->resource->order_by ]);
+	}
+
 }