chore: better type hints and backfill missing descriptions (#433)

justlevine · web-flow · commit 8d8d94d45742 · 2024-06-15T22:17:03.000+03:00
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -9,7 +9,8 @@
 - fix!: Keep `PageField` with previous page data when filtering `formFields` by `pageNumber`. H/t @SamuelHadsall .
 - fix: Handle RadioField submission values when using a custom "other" choice. H/t @Gytjarek .
 - fix: Check for Submission Confirmation url before attempting to get the associated post ID.
-- fix: Flush static Gravity Forms state between multiple calls to `GFUtils::submit_form()`. 
+- fix: Flush static Gravity Forms state between multiple calls to `GFUtils::submit_form()`.
+- fix: Add missing descriptions to types.
 - feat: Add `FieldError.connectedFormField` connection to `FieldError` type.
 - feat: Add support for WPGraphQL Content Blocks.
 - dev: Remove `vendor` directory from the GitHub repository.
@@ -21,6 +22,7 @@
 - chore!: Bump minimum WPGraphQL version to v1.26.0.
 - chore!: Bump minimum WordPress version to v6.0.0.
 - chore!: Bump minimum Gravity Forms version to v2.7.0.
+- chore: Update PHP interfaces and Abstract classes with better type hints.
 - chore: Declare `strict_types` in all PHP files.
 - chore: Update Composer dev-dependencies and fix test compatibility with `wp-graphql-test-case` v3.0.x.
 - docs: Add docs on using Multi-page forms.
diff --git a/src/Connection/AbstractConnection.php b/src/Connection/AbstractConnection.php
@@ -15,6 +15,29 @@
 
 /**
  * Class - AbstractConnection
+ *
+ * @phpstan-type ConnectionConfig array{fromType:string,
+ *   fromFieldName: string,
+ *   resolve: callable,
+ *   oneToOne?: bool,
+ *   toType?: string,
+ *   connectionArgs?: array<string,array{
+ *     type: string|array<string,string | array<string,string>>,
+ *     description: string,
+ *     defaultValue?: mixed
+ *   }>,
+ *   connectionFields?: array<string,array{
+ *     type: string|array<string,string | array<string,string>>,
+ *     description: string,
+ *     args?: array<string,array{
+ *       type: string|array<string,string | array<string,string>>,
+ *       description: string,
+ *       defaultValue?: mixed,
+ *     }>,
+ *     resolve?: callable,
+ *     deprecationReason?: string,
+ *   }>,
+ * }
  */
 abstract class AbstractConnection implements Hookable, Registrable {
 	/**
@@ -34,7 +57,7 @@ public static function register_hooks(): void {
 	/**
 	 * Gets custom connection configuration arguments, such as the resolver, edgeFields, connectionArgs, etc.
 	 *
-	 * @return array<string,array<string,mixed>>
+	 * @return array<string,array{type:string|array<string,string|array<string,string>>,description:string,defaultValue?:mixed}>
 	 */
 	public static function get_connection_args(): array {
 		return [];
@@ -43,9 +66,9 @@ public static function get_connection_args(): array {
 	/**
 	 * Returns a filtered array of connection args.
 	 *
-	 * @param string[] $filter_by .
+	 * @param ?string[] $filter_by an array of specific connections to return.
 	 *
-	 * @return array<string,array<string,mixed>>
+	 * @return array<string,array{type:string|array<string,string|array<string,string>>,description:string,defaultValue?:mixed}>
 	 */
 	public static function get_filtered_connection_args( ?array $filter_by = null ): array {
 		$connection_args = static::get_connection_args();
diff --git a/src/Extensions/GFQuiz/Type/WPObject/QuizResults/QuizResultsFieldCount.php b/src/Extensions/GFQuiz/Type/WPObject/QuizResults/QuizResultsFieldCount.php
@@ -41,9 +41,10 @@ public static function get_type_config(): array {
 	public static function get_connections(): array {
 		return [
 			'formField' => [
-				'toType'   => 'QuizField',
-				'oneToOne' => true,
-				'resolve'  => static function ( $source ): array {
+				'toType'      => 'QuizField',
+				'description' => __( 'The quiz field.', 'wp-graphql-gravity-forms' ),
+				'oneToOne'    => true,
+				'resolve'     => static function ( $source ): array {
 					return [ 'node' => $source['field'] ];
 				},
 			],
diff --git a/src/Interfaces/Enum.php b/src/Interfaces/Enum.php
@@ -16,9 +16,9 @@
 // phpcs:ignore PHPCompatibility.Keywords.ForbiddenNames.enumFound -- @todo Remove b/c
 interface Enum {
 	/**
-	 * Gets the Enum type values.
+	 * Gets the Enum values configuration array.
 	 *
-	 * @return array<string,array<string,mixed>>
+	 * @return array<string,array{description:string,value:mixed,deprecationReason?:string}>
 	 */
 	public static function get_values(): array;
 }
diff --git a/src/Interfaces/Mutation.php b/src/Interfaces/Mutation.php
@@ -15,20 +15,16 @@
  */
 interface Mutation {
 	/**
-	 * Defines the input field configuration.
+	 * Gets the input fields for the mutation.
 	 *
-	 * @return array<string,array<string,mixed>>
-	 *
-	 * @since 0.4.0
+	 * @return array<string,array{type:string|array<string,string|array<string,string>>,description:string,defaultValue?:string}>
 	 */
 	public static function get_input_fields(): array;
 
 	/**
-	 * Defines the output field configuration.
+	 * Gets the fields for the type.
 	 *
-	 * @return array<string,array<string,mixed>>
-	 *
-	 * @since 0.4.0
+	 * @return array<string,array{type:string|array<string,string|array<string,string>>,description:string,args?:array<string,array{type:string|array<string,string|array<string,string>>,description:string,defaultValue?:mixed}>,resolve?:callable,deprecationReason?:string}>
 	 */
 	public static function get_output_fields(): array;
 
diff --git a/src/Interfaces/TypeWithConnections.php b/src/Interfaces/TypeWithConnections.php
@@ -15,9 +15,9 @@
  */
 interface TypeWithConnections {
 	/**
-	 * Gets the the connection config for the GraphQL Type.
+	 * Gets the properties for the type.
 	 *
-	 * @return array<string,array<string,mixed>>
+	 * @return array<string,array{toType:string,description:string,args?:array<string,array{type:string|array<string,string|array<string,string>>,description:string,defaultValue?:mixed}>,connectionInterfaces?:string[],oneToOne?:bool,resolve?:callable}>
 	 */
 	public static function get_connections(): array;
 }
diff --git a/src/Interfaces/TypeWithFields.php b/src/Interfaces/TypeWithFields.php
@@ -15,9 +15,9 @@
  */
 interface TypeWithFields {
 	/**
-	 * Gets the GraphQL fields for the type.
+	 * Gets the fields for the type.
 	 *
-	 * @return array<string,array<string,mixed>> The GraphQL field configs for the type.
+	 * @return array<string,array{type:string|array<string,string|array<string,string>>,description:string,args?:array<string,array{type:string|array<string,string|array<string,string>>,description:string,defaultValue?:mixed}>,resolve?:callable,deprecationReason?:string}>
 	 */
 	public static function get_fields(): array;
 }
diff --git a/src/Interfaces/TypeWithInputFields.php b/src/Interfaces/TypeWithInputFields.php
@@ -0,0 +1,23 @@
+<?php
+/**
+ * Interface for a GraphQL TypeWithInputFields.
+ *
+ * @package WPGraphQL\GF\Interfaces
+ * @since 0.10.0
+ */
+
+declare( strict_types = 1 );
+
+namespace WPGraphQL\GF\Interfaces;
+
+/**
+ * Interface - TypeWithInputFields.
+ */
+interface TypeWithInputFields {
+	/**
+	 * Gets the input fields for the type.
+	 *
+	 * @return array<string,array{type:string|array<string,string|array<string,string>>,description:string,defaultValue?:string}>
+	 */
+	public static function get_fields(): array;
+}
diff --git a/src/Type/Enum/AbstractEnum.php b/src/Type/Enum/AbstractEnum.php
@@ -25,6 +25,13 @@ abstract class AbstractEnum extends AbstractType implements Enum, TypeWithDescri
 	 */
 	public static string $type;
 
+	/**
+	 * Gets the Enum values configuration array.
+	 *
+	 * @return array<string,array{description:string,value:mixed,deprecationReason?:string}>
+	 */
+	abstract public static function get_values(): array;
+
 	/**
 	 * {@inheritDoc}
 	 */
diff --git a/src/Type/Input/AbstractInput.php b/src/Type/Input/AbstractInput.php
@@ -11,13 +11,13 @@
 namespace WPGraphQL\GF\Type\Input;
 
 use WPGraphQL\GF\Interfaces\TypeWithDescription;
-use WPGraphQL\GF\Interfaces\TypeWithFields;
+use WPGraphQL\GF\Interfaces\TypeWithInputFields;
 use WPGraphQL\GF\Type\AbstractType;
 
 /**
  * Class - AbstractInput
  */
-abstract class AbstractInput extends AbstractType implements TypeWithDescription, TypeWithFields {
+abstract class AbstractInput extends AbstractType implements TypeWithDescription, TypeWithInputFields {
 	/**
 	 * Type registered in WPGraphQL.
 	 *
diff --git a/src/Type/WPInterface/AbstractInterface.php b/src/Type/WPInterface/AbstractInterface.php
@@ -48,8 +48,6 @@ public static function register( ?TypeRegistry $type_registry = null ): void {
 
 	/**
 	 * {@inheritDoc}
-	 *
-	 * @return array<string,mixed>
 	 */
 	public static function get_type_config( ?TypeRegistry $type_registry = null ): array {
 		return [
diff --git a/src/Type/WPInterface/Entry.php b/src/Type/WPInterface/Entry.php
@@ -83,6 +83,7 @@ public static function get_connections(): array {
 			'formFields' => [
 				'toType'         => FormField::$type,
 				'connectionArgs' => FormFieldsConnection::get_filtered_connection_args(),
+				'description'    => __( 'The form fields associated with the entry.', 'wp-graphql-gravity-forms' ),
 				'resolve'        => static function ( $source, array $args, AppContext $context, ResolveInfo $info ) {
 					$context->gfEntry = $source;
 
diff --git a/src/Type/WPObject/Form/Form.php b/src/Type/WPObject/Form/Form.php
@@ -100,6 +100,7 @@ public static function get_connections(): array {
 						},
 					],
 				],
+				'description'      => __( 'The entries submitted to the form.', 'wp-graphql-gravity-forms' ),
 				'resolve'          => static function ( $source, array $args, AppContext $context, ResolveInfo $info ) {
 					$context->gfForm = $source;
 
@@ -110,6 +111,7 @@ public static function get_connections(): array {
 			],
 			'formFields' => [
 				'toType'         => FormField::$type,
+				'description'    => __( 'The form fields associated with the form.', 'wp-graphql-gravity-forms' ),
 				'connectionArgs' => FormFieldsConnection::get_filtered_connection_args(),
 				'resolve'        => static function ( $source, array $args, AppContext $context, ResolveInfo $info ) {
 					$context->gfForm = $source;
diff --git a/src/Type/WPObject/Form/FormConfirmation.php b/src/Type/WPObject/Form/FormConfirmation.php
@@ -48,9 +48,10 @@ public static function get_type_config(): array {
 	public static function get_connections(): array {
 		return [
 			'page' => [
-				'toType'   => 'Page',
-				'oneToOne' => true,
-				'resolve'  => static function ( $source, array $args, AppContext $context, ResolveInfo $info ) {
+				'toType'      => 'Page',
+				'description' => __( 'The page that the browser will be redirected to. Only applicable when type is set to `PAGE`.', 'wp-graphql-gravity-forms' ),
+				'oneToOne'    => true,
+				'resolve'     => static function ( $source, array $args, AppContext $context, ResolveInfo $info ) {
 					$page_id = $source['pageId'];
 
 					$resolver = new PostObjectConnectionResolver( $source, $args, $context, $info, 'page' );
diff --git a/src/Type/WPObject/SubmissionConfirmation.php b/src/Type/WPObject/SubmissionConfirmation.php
@@ -47,9 +47,10 @@ public static function get_type_config(): array {
 	public static function get_connections(): array {
 		return [
 			'page' => [
-				'toType'   => 'Page',
-				'oneToOne' => true,
-				'resolve'  => static function ( $source, array $args, AppContext $context, ResolveInfo $info ) {
+				'toType'      => 'Page',
+				'description' => __( 'The page that the browser will be redirected to. Only applicable when type is set to `PAGE`.', 'wp-graphql-gravity-forms' ),
+				'oneToOne'    => true,
+				'resolve'     => static function ( $source, array $args, AppContext $context, ResolveInfo $info ) {
 					$page_id = isset( $source['url'] ) ? url_to_postid( $source['url'] ) : null; //phpcs:ignore WordPressVIPMinimum.Functions.RestrictedFunctions.url_to_postid_url_to_postid
 
 					if ( empty( $page_id ) ) {

Original file line number	Diff line number	Diff line change
`@@ -16,9 +16,9 @@`
`16`	`16`	`// phpcs:ignore PHPCompatibility.Keywords.ForbiddenNames.enumFound -- @todo Remove b/c`
`17`	`17`	`interface Enum {`
`18`	`18`	`/**`
`19`		`- * Gets the Enum type values.`
	`19`	`+ * Gets the Enum values configuration array.`
`20`	`20`	`*`
`21`		`- * @return array<string,array<string,mixed>>`
	`21`	`+ * @return array<string,array{description:string,value:mixed,deprecationReason?:string}>`
`22`	`22`	`*/`
`23`	`23`	`public static function get_values(): array;`
`24`	`24`	`}`
Original file line number	Diff line number	Diff line change
`@@ -15,9 +15,9 @@`
`15`	`15`	`*/`
`16`	`16`	`interface TypeWithConnections {`
`17`	`17`	`/**`
`18`		`- * Gets the the connection config for the GraphQL Type.`
	`18`	`+ * Gets the properties for the type.`
`19`	`19`	`*`
`20`		`- * @return array<string,array<string,mixed>>`
	`20`	`+ * @return array<string,array{toType:string,description:string,args?:array<string,array{type:string\|array<string,string\|array<string,string>>,description:string,defaultValue?:mixed}>,connectionInterfaces?:string[],oneToOne?:bool,resolve?:callable}>`
`21`	`21`	`*/`
`22`	`22`	`public static function get_connections(): array;`
`23`	`23`	`}`