Skip to content

Commit b2ccef5

Browse files
gzioloclaude
gziolo
and
claude
committed
Connectors: Improve PHPDoc and PHPStan types for connector data shape.
- Expand @return shape for wp_get_connector() to match wp_get_connectors() - Use non-empty-string and literal types in @phpstan-return annotations - Remove |null from optional fields (logo_url, credentials_url); store them only when non-empty, consistent with the existing logo_url pattern - Fix PHPDoc alignment across modified blocks - Update test to reflect credentials_url being truly optional Co-Authored-By: Claude Sonnet 4.6 <[email protected]>
1 parent e26123c commit b2ccef5

3 files changed

Lines changed: 53 additions & 32 deletions

File tree

‎src/wp-includes/class-wp-connector-registry.php‎

Lines changed: 17 additions & 15 deletions
Original file line numberDiff line numberDiff line change
@@ -18,11 +18,11 @@
1818
* @phpstan-type Connector array{
1919
* name: string,
2020
* description: string,
21-
* logo_url?: string|null,
21+
* logo_url?: string,
2222
* type: string,
2323
* authentication: array{
2424
* method: string,
25-
* credentials_url?: string|null,
25+
* credentials_url?: string,
2626
* setting_name?: string
2727
* },
2828
* plugin?: array{
@@ -62,13 +62,13 @@ final class WP_Connector_Registry {
6262
*
6363
* @type string $name Required. The connector's display name.
6464
* @type string $description Optional. The connector's description. Default empty string.
65-
* @type string|null $logo_url Optional. URL to the connector's logo image. Default null.
65+
* @type string $logo_url Optional. URL to the connector's logo image.
6666
* @type string $type Required. The connector type. Currently, only 'ai_provider' is supported.
6767
* @type array $authentication {
6868
* Required. Authentication configuration.
6969
*
70-
* @type string $method Required. The authentication method: 'api_key' or 'none'.
71-
* @type string|null $credentials_url Optional. URL where users can obtain API credentials.
70+
* @type string $method Required. The authentication method: 'api_key' or 'none'.
71+
* @type string $credentials_url Optional. URL where users can obtain API credentials.
7272
* }
7373
* @type array $plugin {
7474
* Optional. Plugin data for install/activate UI.
@@ -158,8 +158,10 @@ public function register( string $id, array $args ): ?array {
158158
}
159159

160160
if ( 'api_key' === $args['authentication']['method'] ) {
161-
$connector['authentication']['credentials_url'] = $args['authentication']['credentials_url'] ?? null;
162-
$connector['authentication']['setting_name'] = "connectors_ai_{$id}_api_key";
161+
if ( ! empty( $args['authentication']['credentials_url'] ) && is_string( $args['authentication']['credentials_url'] ) ) {
162+
$connector['authentication']['credentials_url'] = $args['authentication']['credentials_url'];
163+
}
164+
$connector['authentication']['setting_name'] = "connectors_ai_{$id}_api_key";
163165
}
164166

165167
if ( ! empty( $args['plugin'] ) && is_array( $args['plugin'] ) ) {
@@ -212,11 +214,11 @@ public function unregister( string $id ): ?array {
212214
* @type array ...$0 {
213215
* Data for a single connector.
214216
*
215-
* @type string $name The connector's display name.
216-
* @type string $description The connector's description.
217-
* @type string|null $logo_url Optional. URL to the connector's logo image.
218-
* @type string $type The connector type. Currently, only 'ai_provider' is supported.
219-
* @type array $plugin {
217+
* @type string $name The connector's display name.
218+
* @type string $description The connector's description.
219+
* @type string $logo_url Optional. URL to the connector's logo image.
220+
* @type string $type The connector type. Currently, only 'ai_provider' is supported.
221+
* @type array $plugin {
220222
* Optional. Plugin data for install/activate UI.
221223
*
222224
* @type string $slug The WordPress.org plugin slug.
@@ -225,9 +227,9 @@ public function unregister( string $id ): ?array {
225227
* Authentication configuration. When method is 'api_key', includes
226228
* credentials_url and setting_name. When 'none', only method is present.
227229
*
228-
* @type string $method The authentication method: 'api_key' or 'none'.
229-
* @type string|null $credentials_url Optional. URL where users can obtain API credentials.
230-
* @type string $setting_name Optional. The setting name for the API key.
230+
* @type string $method The authentication method: 'api_key' or 'none'.
231+
* @type string $credentials_url Optional. URL where users can obtain API credentials.
232+
* @type string $setting_name Optional. The setting name for the API key.
231233
* }
232234
* }
233235
* }

‎src/wp-includes/connectors.php‎

Lines changed: 36 additions & 16 deletions
Original file line numberDiff line numberDiff line change
@@ -37,15 +37,35 @@ function wp_is_connector_registered( string $id ): bool {
3737
* @see WP_Connector_Registry::get_registered()
3838
*
3939
* @param string $id The connector identifier.
40-
* @return array|null The registered connector data, or null if not registered.
40+
* @return array|null {
41+
* Connector data, or null if not registered.
42+
*
43+
* @type string $name The connector's display name.
44+
* @type string $description The connector's description.
45+
* @type string $logo_url Optional. URL to the connector's logo image.
46+
* @type string $type The connector type. Currently, only 'ai_provider' is supported.
47+
* @type array $plugin {
48+
* Optional. Plugin data for install/activate UI.
49+
*
50+
* @type string $slug The WordPress.org plugin slug.
51+
* }
52+
* @type array $authentication {
53+
* Authentication configuration. When method is 'api_key', includes
54+
* credentials_url and setting_name. When 'none', only method is present.
55+
*
56+
* @type string $method The authentication method: 'api_key' or 'none'.
57+
* @type string $credentials_url Optional. URL where users can obtain API credentials.
58+
* @type string $setting_name Optional. The setting name for the API key.
59+
* }
60+
* }
4161
* @phpstan-return ?array{
4262
* name: non-empty-string,
4363
* description: non-empty-string,
44-
* logo_url?: non-empty-string|null,
64+
* logo_url?: non-empty-string,
4565
* type: 'ai_provider',
4666
* authentication: array{
4767
* method: 'api_key'|'none',
48-
* credentials_url?: non-empty-string|null,
68+
* credentials_url?: non-empty-string,
4969
* setting_name?: non-empty-string
5070
* },
5171
* plugin?: array{
@@ -77,35 +97,35 @@ function wp_get_connector( string $id ): ?array {
7797
*
7898
* @type string $name The connector's display name.
7999
* @type string $description The connector's description.
80-
* @type string|null $logo_url Optional. URL to the connector's logo image.
100+
* @type string $logo_url Optional. URL to the connector's logo image.
81101
* @type string $type The connector type. Currently, only 'ai_provider' is supported.
82102
* @type array $plugin {
83103
* Optional. Plugin data for install/activate UI.
84104
*
85105
* @type string $slug The WordPress.org plugin slug.
86106
* }
87-
* @type array $authentication {
107+
* @type array $authentication {
88108
* Authentication configuration. When method is 'api_key', includes
89109
* credentials_url and setting_name. When 'none', only method is present.
90110
*
91-
* @type string $method The authentication method: 'api_key' or 'none'.
92-
* @type string|null $credentials_url Optional. URL where users can obtain API credentials.
93-
* @type string $setting_name Optional. The setting name for the API key.
111+
* @type string $method The authentication method: 'api_key' or 'none'.
112+
* @type string $credentials_url Optional. URL where users can obtain API credentials.
113+
* @type string $setting_name Optional. The setting name for the API key.
94114
* }
95115
* }
96116
* }
97117
* @phpstan-return array<string, array{
98-
* name: string,
99-
* description: string,
100-
* logo_url?: string|null,
101-
* type: string,
118+
* name: non-empty-string,
119+
* description: non-empty-string,
120+
* logo_url?: non-empty-string,
121+
* type: 'ai_provider',
102122
* authentication: array{
103-
* method: string,
104-
* credentials_url?: string|null,
105-
* setting_name?: string
123+
* method: 'api_key'|'none',
124+
* credentials_url?: non-empty-string,
125+
* setting_name?: non-empty-string
106126
* },
107127
* plugin?: array{
108-
* slug: string
128+
* slug: non-empty-string
109129
* }
110130
* }>
111131
*/

‎tests/phpunit/tests/connectors/wpGetConnectors.php‎

Lines changed: 0 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -84,7 +84,6 @@ public function test_api_key_connectors_have_setting_name_and_credentials_url():
8484
$connector_data['authentication']['setting_name'] ?? null,
8585
"Connector '{$connector_id}' setting_name does not match expected format."
8686
);
87-
$this->assertArrayHasKey( 'credentials_url', $connector_data['authentication'], "Connector '{$connector_id}' authentication is missing 'credentials_url'." );
8887
}
8988

9089
$this->assertGreaterThan( 0, $api_key_count, 'At least one connector should use api_key authentication.' );

0 commit comments

Comments
 (0)