chore: add traversable type hints (first pass) (#410)

* chore: add traverable typehints

* tests: lint tests

* chore: second pass

Author: justlevine

CHANGELOG.md

@@ -6,6 +6,8 @@
 - chore: Update Composer deps and lint.
 - chore: Lock WPBrowser to <3.5.0 to prevent conflicts with Codeception.
 - chore: Implement strict PHPStan rules and fix resulting issues.
+- chore: Add traversable type hints throughout the codebase.
+- tests: Lint tests.
 - ci: Update GitHub Actions to latest versions.
 - ci: Test plugin compatibility with WordPress 6.5.0.
 - ci: Test plugin compatibility with PHP 8.2.

src/CoreSchemaFilters.php

@@ -35,8 +35,10 @@ public static function register_hooks(): void {
 	/**
 	 * Strip `Connection` interface from form fields.
 	 *
-	 * @param array $interfaces Array of interfaces.
-	 * @param array $config  The type config.
+	 * @param string[]            $interfaces Array of interfaces.
+	 * @param array<string,mixed> $config     The type config.
+	 *
+	 * @return string[]
 	 */
 	public static function strip_connection_interface_from_gf_fields( array $interfaces, array $config ): array {
 		// Bail early if Connection, 'Edge, or 'OneToOneConnection' arent in the interfaces.

src/Data/Connection/EntriesConnectionResolver.php

@@ -53,7 +53,7 @@ public function __construct( $source, array $args, AppContext $context, ResolveI
 	}
 
 	/**
-	 * Return the name of the loader to be used with the connection resolver
+	 * {@inheritDoc}
 	 */
 	public function get_loader_name(): string {
 		return EntriesLoader::$name;
@@ -220,6 +220,8 @@ public function get_query_offset_index(): int {
 	 * Gets index (array offset) and offset (entry id) from decoded cursor.
 	 *
 	 * @param string $cursor .
+	 *
+	 * @return array{index:int,offset:int}
 	 */
 	protected function parse_cursor( string $cursor ): array {
 		$decoded     = base64_decode( $cursor );
@@ -234,7 +236,7 @@ protected function parse_cursor( string $cursor ): array {
 	/**
 	 * Returns form ids.
 	 *
-	 * @return array|int
+	 * @return int[]|int
 	 */
 	private function get_form_ids() {
 		if ( empty( $this->args['where']['formIds'] ) ) {
@@ -250,6 +252,8 @@ private function get_form_ids() {
 
 	/**
 	 * Gets search criteria for entry Ids.
+	 *
+	 * @return array<string,mixed>
 	 */
 	private function get_search_criteria(): array {
 		$search_criteria = $this->apply_status_to_search_criteria( [] );
@@ -275,7 +279,9 @@ private function get_search_criteria(): array {
 	/**
 	 * Adds 'status' value to search criteria.
 	 *
-	 * @param array $search_criteria The search criteria for the entry Ids.
+	 * @param array<string,mixed> $search_criteria The search criteria for the entry Ids.
+	 *
+	 * @return array<string,mixed>
 	 */
 	private function apply_status_to_search_criteria( array $search_criteria ): array {
 		$status = $this->args['where']['status'] ?? EntryStatusEnum::ACTIVE; // Default to active entries.
@@ -372,6 +378,8 @@ static function ( $value_field ) use ( $field_filter ): bool {
 
 	/**
 	 * Get sort argument for entry ID query.
+	 *
+	 * @return array<string,mixed>
 	 */
 	private function get_sort(): array {
 		// Set default sort direction.
@@ -398,6 +406,8 @@ private function get_sort(): array {
 	/**
 	 * Get paging arguments for entry ID query.
 	 *
+	 * @return array{offset:int,page_size:int}
+	 *
 	 * @throws \GraphQL\Error\UserError When using unsupported pagination.
 	 */
 	private function get_paging(): array {

src/Data/Connection/FormFieldsConnectionResolver.php

@@ -33,7 +33,9 @@ class FormFieldsConnectionResolver {
 	 *
 	 * Instead of a Model.
 	 *
-	 * @param array $data array of form fields.
+	 * @param \GF_Field[] $data array of form fields.
+	 *
+	 * @return \GF_Field[]
 	 */
 	public static function prepare_data( array $data ): array {
 		foreach ( $data as &$field ) {
@@ -73,11 +75,11 @@ public static function prepare_data( array $data ): array {
 	 * The connection resolve method.
 	 *
 	 * @param mixed                                $source  The object the connection is coming from.
-	 * @param array                                $args    Array of args to be passed down to the resolve method.
+	 * @param array<string,mixed>                  $args    Array of args to be passed down to the resolve method.
 	 * @param \WPGraphQL\AppContext                $context The AppContext object to be passed down.
 	 * @param \GraphQL\Type\Definition\ResolveInfo $info The ResolveInfo object.
 	 *
-	 * @return mixed|array|\WPGraphQL\GF\Data\Connection\Deferred
+	 * @return ?array<string,mixed>
 	 */
 	public static function resolve( $source, array $args, AppContext $context, ResolveInfo $info ) { // phpcs:ignore Generic.CodeAnalysis.UnusedFunctionParameter.FoundAfterLastUsed
 		if ( ! is_array( $source ) || empty( $source ) ) {
@@ -104,6 +106,8 @@ public static function resolve( $source, array $args, AppContext $context, Resol
 
 	/**
 	 * Returns input keys for Address field.
+	 *
+	 * @return string[]
 	 */
 	private static function get_address_input_keys(): array {
 		return [
@@ -118,6 +122,8 @@ private static function get_address_input_keys(): array {
 
 	/**
 	 * Returns input keys for Name field.
+	 *
+	 * @return string[]
 	 */
 	private static function get_name_input_keys(): array {
 		return [
@@ -132,8 +138,10 @@ private static function get_name_input_keys(): array {
 		/**
 		 * Filters the form fields by the connection's where args.
 		 *
-		 * @param array $fields .
-		 * @param array $args .
+		 * @param \GF_Field[]         $fields .
+		 * @param array<string,mixed> $args .
+		 *
+		 * @return \GF_Field[]
 		 */
 	private static function filter_form_fields_by_connection_args( $fields, $args ): array {
 		if ( isset( $args['where']['ids'] ) ) {

src/Data/Connection/FormsConnectionResolver.php

@@ -93,7 +93,7 @@ public function get_query_args(): array {
 	/**
 	 * {@inheritDoc}
 	 *
-	 * @return array
+	 * @return array<int|string,array<string,mixed>>
 	 */
 	public function get_query(): array {
 		$form_ids    = $this->query_args['form_ids'];
@@ -118,7 +118,7 @@ public function get_query(): array {
 			 * client. This hook is somewhat similar to Gravity Forms' gform_pre_render hook
 			 * and can be used for dynamic field input population, among other things.
 			 *
-			 * @param array $form Form meta array.
+			 * @param array<string,mixed> $form Form meta array.
 			 */
 			$modified_form = apply_filters( 'graphql_gf_form_object', $form );
 
@@ -147,6 +147,8 @@ public function get_ids_from_query() {
 
 	/**
 	 * Returns form ids.
+	 *
+	 * @return int[]
 	 */
 	private function get_form_ids(): array {
 		if ( empty( $this->args['where']['formIds'] ) ) {
@@ -162,6 +164,8 @@ private function get_form_ids(): array {
 
 	/**
 	 * Gets form status from query.
+	 *
+	 * @return array{active:bool,trash:bool}
 	 */
 	private function get_form_status(): array {
 		$status = $this->args['where']['status'] ?? FormStatusEnum::ACTIVE;
@@ -196,6 +200,8 @@ private function get_form_status(): array {
 	/**
 	 * Get sort argument for forms ID query.
 	 *
+	 * @return array{key:string,direction:string}
+	 *
 	 * @throws \GraphQL\Error\UserError .
 	 */
 	private function get_sort(): array {

src/Data/EntryObjectMutation.php

@@ -21,10 +21,10 @@ class EntryObjectMutation {
 	/**
 	 * Returns the FieldValueInput object relative to the field type.
 	 *
-	 * @param array $args The GraphQL mutation input args for the field.
-	 * @param array $form The GF form object.
-	 * @param bool  $is_draft If the mutation is for a draft entry.
-	 * @param array $entry The GF entry object. Used when updating.
+	 * @param array<string,mixed>     $args     The GraphQL mutation input args for the field.
+	 * @param array<string,mixed>     $form     The GF form object.
+	 * @param bool                    $is_draft If the mutation is for a draft entry.
+	 * @param array<int|string,mixed> $entry    The GF entry object. Used when updating.
 	 *
 	 * @throws \Exception .
 	 */
@@ -92,12 +92,12 @@ public static function get_field_value_input( array $args, array $form, bool $is
 		 *
 		 * Useful for adding mutation support for custom fields.
 		 *
-		 * @param string $field_value_input_class  The FieldValueInput class to use. The referenced class must extend AbstractFieldValueInput.
-		 * @param array    $args The GraphQL input args for the form field.
-		 * @param \GF_Field $field The current Gravity Forms field object.
-		 * @param array $form The current Gravity Forms form object.
-		 * @param array|null $entry The current Gravity Forms entry object. Only available when using update (`gfUpdateEntry`, `gfUpdateDraftEntry`) mutations.
-		 * @param bool $is_draft_mutation Whether the mutation is handling a Draft Entry (`gfUpdateDraftEntry`, or `gfSubmitForm` when `saveAsDraft` is `true`).
+		 * @param string              $field_value_input_class  The FieldValueInput class to use. The referenced class must extend AbstractFieldValueInput.
+		 * @param array               $args The GraphQL input args for the form field.
+		 * @param \GF_Field           $field The current Gravity Forms field object.
+		 * @param array<string,mixed> $form The current Gravity Forms form object.
+		 * @param array|null          $entry The current Gravity Forms entry object. Only available when using update (`gfUpdateEntry`, `gfUpdateDraftEntry`) mutations.
+		 * @param bool                $is_draft_mutation Whether the mutation is handling a Draft Entry (`gfUpdateDraftEntry`, or `gfSubmitForm` when `saveAsDraft` is `true`).
 		 */
 		$field_value_input = apply_filters( 'graphql_gf_field_value_input_class', $field_value_input, $args, $field, $form, $entry, $is_draft );
 
@@ -111,7 +111,9 @@ public static function get_field_value_input( array $args, array $form, bool $is
 	/**
 	 * Generates array of field errors from the submission.
 	 *
-	 * @param array $messages The Gravity Forms submission validation messages.
+	 * @param array<int|string,string> $messages The Gravity Forms submission validation messages.
+	 *
+	 * @return array{message:string,id:int|string}[]
 	 */
 	public static function get_submission_errors( array $messages ): array {
 		return array_map(
@@ -129,7 +131,9 @@ static function ( $id, $message ): array {
 	/**
 	 * Gets the submission confirmation information in an array formated for WPGraphQL.
 	 *
-	 * @param array $payload the submission response.
+	 * @param array<string,mixed> $payload the submission response.
+	 *
+	 * @return ?array{type:string,message:?string,url:?string}
 	 */
 	public static function get_submission_confirmation( array $payload ): ?array {
 		if ( empty( $payload['confirmation_type'] ) ) {
@@ -146,13 +150,15 @@ public static function get_submission_confirmation( array $payload ): ?array {
 	/**
 	 * Renames $field_value keys to input_{id}_{sub_id}, so Gravity Forms can read them.
 	 *
-	 * @param array $field_values .
+	 * @param array<int|string,mixed> $field_values .
+	 *
+	 * @return array<string,mixed> $formatted .
 	 * */
 	public static function rename_field_names_for_submission( array $field_values ): array {
 		$formatted = [];
 
 		foreach ( $field_values as $key => $value ) {
-			$formatted[ 'input_' . str_replace( '.', '_', $key ) ] = $value;
+			$formatted[ 'input_' . str_replace( '.', '_', (string) $key ) ] = $value;
 		}
 
 		return $formatted;
@@ -162,9 +168,11 @@ public static function rename_field_names_for_submission( array $field_values ):
 	 * Initializes the globals needed for file uploads to work.
 	 * This prevents any notices about missing array keys.
 	 *
-	 * @param \GF_Field[] $form_fields .
-	 * @param array       $input_field_values .
-	 * @param bool        $save_as_draft .
+	 * @param \GF_Field[]           $form_fields .
+	 * @param array<string,mixed>[] $input_field_values .
+	 * @param bool                  $save_as_draft .
+	 *
+	 * @return array<string,array<string,mixed>[]>
 	 *
 	 * @throws \GraphQL\Error\UserError .
 	 */

src/Data/Factory.php

@@ -27,10 +27,10 @@ class Factory {
 	/**
 	 * Registers loaders to AppContext.
 	 *
-	 * @param array                 $loaders Data loaders.
-	 * @param \WPGraphQL\AppContext $context App context.
+	 * @param array<string,\WPGraphQL\Data\Loader\AbstractDataLoader> $loaders Data loaders.
+	 * @param \WPGraphQL\AppContext                                   $context App context.
 	 *
-	 * @return array Data loaders, with new ones added.
+	 * @return array<string,\WPGraphQL\Data\Loader\AbstractDataLoader> Data loaders.
 	 */
 	public static function register_loaders( array $loaders, AppContext $context ): array {
 		$loaders[ DraftEntriesLoader::$name ] = new DraftEntriesLoader( $context );
@@ -69,7 +69,7 @@ public static function resolve_node_type( $type, $node ) {
 	 *
 	 * @param int                                  $max_query_amount Max query amount.
 	 * @param mixed                                $source     source passed down from the resolve tree.
-	 * @param array                                $args       array of arguments input in the field as part of the GraphQL query.
+	 * @param array<string,mixed>                  $args       array of arguments input in the field as part of the GraphQL query.
 	 * @param \WPGraphQL\AppContext                $context Object containing app context that gets passed down the resolve tree.
 	 * @param \GraphQL\Type\Definition\ResolveInfo $info Info about fields passed down the resolve tree.
 	 *
@@ -97,11 +97,11 @@ public static function resolve_form( $id, AppContext $context ): ?Deferred {
 	 * Wrapper for the FormsConnectionResolver::resolve method.
 	 *
 	 * @param mixed                                $source  The object the connection is coming from.
-	 * @param array                                $args    Array of args to be passed down to the resolve method.
+	 * @param array<string,mixed>                  $args    Array of args to be passed down to the resolve method.
 	 * @param \WPGraphQL\AppContext                $context The AppContext object to be passed down.
 	 * @param \GraphQL\Type\Definition\ResolveInfo $info The ResolveInfo object.
 	 *
-	 * @return mixed|array|\GraphQL\Deferred
+	 * @return \GraphQL\Deferred
 	 */
 	public static function resolve_forms_connection( $source, array $args, AppContext $context, ResolveInfo $info ) {
 		$resolver = new FormsConnectionResolver( $source, $args, $context, $info );
@@ -133,11 +133,11 @@ public static function resolve_entry( $id, AppContext $context ): ?Deferred {
 	 * Wrapper for the EntriesConnectionResolver::resolve method.
 	 *
 	 * @param mixed                                $source  The object the connection is coming from.
-	 * @param array                                $args    Array of args to be passed down to the resolve method.
+	 * @param array<string,mixed>                  $args    Array of args to be passed down to the resolve method.
 	 * @param \WPGraphQL\AppContext                $context The AppContext object to be passed down.
 	 * @param \GraphQL\Type\Definition\ResolveInfo $info The ResolveInfo object.
 	 *
-	 * @return mixed|array|\GraphQL\Deferred
+	 * @return \GraphQL\Deferred
 	 */
 	public static function resolve_entries_connection( $source, array $args, AppContext $context, ResolveInfo $info ) {
 		$resolver = new EntriesConnectionResolver( $source, $args, $context, $info );

src/Data/FieldValueInput/AbstractFieldValueInput.php

@@ -54,7 +54,7 @@ abstract class AbstractFieldValueInput {
 	/**
 	 * The GraphQL input args passed to `fieldValues`.
 	 *
-	 * @var array
+	 * @var array<string,mixed>
 	 */
 	protected array $input_args;
 
@@ -75,11 +75,11 @@ abstract class AbstractFieldValueInput {
 	/**
 	 * The class constructor.
 	 *
-	 * @param array                        $input_args The GraphQL input args for the form field.
-	 * @param array<string,mixed>          $form The current Gravity Forms form object.
-	 * @param bool                         $is_draft Whether the mutation is handling a Draft Entry.
-	 * @param \GF_Field                    $field The current Gravity Forms field object.
-	 * @param array<int|string,mixed>|null $entry The current Gravity Forms entry object.
+	 * @param array<string,mixed>          $input_args The GraphQL input args for the form field.
+	 * @param array<string,mixed>          $form       The current Gravity Forms form object.
+	 * @param bool                         $is_draft   Whether the mutation is handling a Draft Entry.
+	 * @param \GF_Field                    $field      The current Gravity Forms field object.
+	 * @param array<int|string,mixed>|null $entry      The current Gravity Forms entry object.
 	 *
 	 * @throws \GraphQL\Error\UserError .
 	 */
@@ -122,12 +122,12 @@ public function __construct( array $input_args, array $form, bool $is_draft, ?GF
 		/**
 		 * Filters the GraphQL input args for the field value input.
 		 *
-		 * @param array|string $args field value input args.
-		 * @param \GF_Field $field The current Gravity Forms field object.
-		 * @param array $form The current Gravity Forms form object.
-		 * @param array|null $entry The current Gravity Forms entry object. Only available when using update (`gfUpdateEntry`, `gfUpdateDraftEntry`) mutations.
-		 * @param bool $is_draft_mutation Whether the mutation is handling a Draft Entry (`gfUpdateDraftEntry`, or `gfSubmitForm` when `saveAsDraft` is `true`).
-		 * @param string $field_name The GraphQL input field name. E.g. `nameValues`.
+		 * @param array|string        $args              Field value input args.
+		 * @param \GF_Field           $field The current Gravity Forms field object.
+		 * @param array<string,mixed> $form The current  Gravity Forms form object.
+		 * @param array|null          $entry The current Gravity Forms entry object. Only available when using update (`gfUpdateEntry`, `gfUpdateDraftEntry`) mutations.
+		 * @param bool                $is_draft_mutation Whether the mutation is handling a Draft Entry (`gfUpdateDraftEntry`, or `gfSubmitForm` when `saveAsDraft` is `true`).
+		 * @param string              $field_name        The GraphQL input field name. E.g. `nameValues`.
 		 */
 		$this->args = apply_filters(
 			'graphql_gf_field_value_input_args',
@@ -142,13 +142,13 @@ public function __construct( array $input_args, array $form, bool $is_draft, ?GF
 		/**
 		 * Filters the prepared field value to be submitted to Gravity Forms.
 		 *
-		 * @param array|string $prepared_field_value The field value formatted in a way Gravity Forms can understand.
-		 * @param array|string $args field value input args.
-		 * @param \GF_Field $field The current Gravity Forms field object.
-		 * @param array $form The current Gravity Forms form object.
-		 * @param array|null $entry The current Gravity Forms entry object. Only available when using update (`gfUpdateEntry`, `gfUpdateDraftEntry`) mutations.
-		 * @param bool $is_draft_mutation Whether the mutation is handling a Draft Entry (`gfUpdateDraftEntry`, or `gfSubmitForm` when `saveAsDraft` is `true`).
-		 * @param string $field_name The GraphQL input field name. E.g. `nameValues`.
+		 * @param array|string        $prepared_field_value The field value formatted in a way Gravity Forms can understand.
+		 * @param array|string        $args                 Field value input args.
+		 * @param \GF_Field           $field                The current Gravity Forms field object.
+		 * @param array<string,mixed> $form                 The current Gravity Forms form object.
+		 * @param array|null          $entry                The current Gravity Forms entry object. Only available when using update (`gfUpdateEntry`, `gfUpdateDraftEntry`) mutations.
+		 * @param bool                $is_draft_mutation    Whether the mutation is handling a Draft Entry (`gfUpdateDraftEntry`, or `gfSubmitForm` when `saveAsDraft` is `true`).
+		 * @param string              $field_name           The GraphQL input field name. E.g. `nameValues`.
 		 */
 		$this->value = apply_filters(
 			'graphql_gf_field_value_input_prepared_value',