Skip to content

Commit e21093f

Browse files
gzioloaaronjorbin
gziolo
and
aaronjorbin
committed
Apply suggestions from code review
Co-authored-by: Aaron Jorbin <[email protected]>
1 parent ea27a6a commit e21093f

File tree

8 files changed

+113
-133
lines changed

8 files changed

+113
-133
lines changed

‎src/wp-includes/abilities-api.php‎

Lines changed: 8 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -14,7 +14,7 @@
1414
/**
1515
* Registers a new ability using Abilities API.
1616
*
17-
* Note: Do not use before the {@see 'abilities_api_init'} hook.
17+
* Note: Should only be used on the {@see 'abilities_api_init'} hook.
1818
*
1919
* @since 6.9.0
2020
*
@@ -26,7 +26,7 @@
2626
* @param array<string,mixed> $args An associative array of arguments for the ability. This should include
2727
* `label`, `description`, `category`, `input_schema`, `output_schema`, `execute_callback`,
2828
* `permission_callback`, `meta`, and `ability_class`.
29-
* @return ?\WP_Ability An instance of registered ability on success, null on failure.
29+
* @return WP_Ability|null An instance of registered ability on success, null on failure.
3030
*
3131
* @phpstan-param array{
3232
* label?: string,
@@ -64,14 +64,14 @@ function wp_register_ability( string $name, array $args ): ?WP_Ability {
6464
}
6565

6666
/**
67-
* Unregisters an ability using Abilities API.
67+
* Unregisters an ability from the Abilities API.
6868
*
6969
* @since 6.9.0
7070
*
7171
* @see WP_Abilities_Registry::unregister()
7272
*
7373
* @param string $name The name of the registered ability, with its namespace.
74-
* @return ?\WP_Ability The unregistered ability instance on success, null on failure.
74+
* @return WP_Ability|null The unregistered ability instance on success, null on failure.
7575
*/
7676
function wp_unregister_ability( string $name ): ?WP_Ability {
7777
return WP_Abilities_Registry::get_instance()->unregister( $name );
@@ -85,7 +85,7 @@ function wp_unregister_ability( string $name ): ?WP_Ability {
8585
* @see WP_Abilities_Registry::get_registered()
8686
*
8787
* @param string $name The name of the registered ability, with its namespace.
88-
* @return ?\WP_Ability The registered ability instance, or null if it is not registered.
88+
* @return WP_Ability|null The registered ability instance, or null if it is not registered.
8989
*/
9090
function wp_get_ability( string $name ): ?WP_Ability {
9191
return WP_Abilities_Registry::get_instance()->get_registered( $name );
@@ -115,7 +115,7 @@ function wp_get_abilities(): array {
115115
* alphanumeric characters and dashes.
116116
* @param array<string,mixed> $args An associative array of arguments for the category. This should
117117
* include `label`, `description`, and optionally `meta`.
118-
* @return ?\WP_Ability_Category The registered category instance on success, null on failure.
118+
* @return WP_Ability_Category|null The registered category instance on success, null on failure.
119119
*
120120
* @phpstan-param array{
121121
* label: string,
@@ -136,7 +136,7 @@ function wp_register_ability_category( string $slug, array $args ): ?WP_Ability_
136136
* @see WP_Abilities_Category_Registry::unregister()
137137
*
138138
* @param string $slug The slug of the registered category.
139-
* @return ?\WP_Ability_Category The unregistered category instance on success, null on failure.
139+
* @return WP_Ability_Category|null The unregistered category instance on success, null on failure.
140140
*/
141141
function wp_unregister_ability_category( string $slug ): ?WP_Ability_Category {
142142
return WP_Abilities_Category_Registry::get_instance()->unregister( $slug );
@@ -150,7 +150,7 @@ function wp_unregister_ability_category( string $slug ): ?WP_Ability_Category {
150150
* @see WP_Abilities_Category_Registry::get_registered()
151151
*
152152
* @param string $slug The slug of the registered category.
153-
* @return ?\WP_Ability_Category The registered category instance, or null if it is not registered.
153+
* @return WP_Ability_Category|null The registered category instance, or null if it is not registered.
154154
*/
155155
function wp_get_ability_category( string $slug ): ?WP_Ability_Category {
156156
return WP_Abilities_Category_Registry::get_instance()->get_registered( $slug );

‎src/wp-includes/abilities-api/class-wp-abilities-category-registry.php‎

Lines changed: 12 additions & 12 deletions
Original file line numberDiff line numberDiff line change
@@ -22,7 +22,7 @@ final class WP_Abilities_Category_Registry {
2222
* The singleton instance of the registry.
2323
*
2424
* @since 6.9.0
25-
* @var ?self
25+
* @var self|null
2626
*/
2727
private static $instance = null;
2828

@@ -47,7 +47,7 @@ final class WP_Abilities_Category_Registry {
4747
* alphanumeric characters and dashes.
4848
* @param array<string,mixed> $args An associative array of arguments for the category. See wp_register_ability_category() for
4949
* details.
50-
* @return ?\WP_Ability_Category The registered category instance on success, null on failure.
50+
* @return WP_Ability_Category|null The registered category instance on success, null on failure.
5151
*
5252
* @phpstan-param array{
5353
* label: string,
@@ -62,7 +62,7 @@ public function register( string $slug, array $args ): ?WP_Ability_Category {
6262
__METHOD__,
6363
sprintf(
6464
/* translators: 1: abilities_api_categories_init, 2: category slug. */
65-
esc_html__( 'Categories must be registered during the %1$s action. The category %2$s was not registered.' ),
65+
__( 'Categories must be registered during the %1$s action. The category %2$s was not registered.' ),
6666
'<code>abilities_api_categories_init</code>',
6767
'<code>' . esc_html( $slug ) . '</code>'
6868
),
@@ -75,7 +75,7 @@ public function register( string $slug, array $args ): ?WP_Ability_Category {
7575
_doing_it_wrong(
7676
__METHOD__,
7777
/* translators: %s: Category slug. */
78-
esc_html( sprintf( __( 'Category "%s" is already registered.' ), $slug ) ),
78+
sprintf( __( 'Category "%s" is already registered.' ), esc_html( $slug ) ),
7979
'6.9.0'
8080
);
8181
return null;
@@ -84,7 +84,7 @@ public function register( string $slug, array $args ): ?WP_Ability_Category {
8484
if ( ! preg_match( '/^[a-z0-9]+(?:-[a-z0-9]+)*$/', $slug ) ) {
8585
_doing_it_wrong(
8686
__METHOD__,
87-
esc_html__( 'Category slug must contain only lowercase alphanumeric characters and dashes.' ),
87+
__( 'Category slug must contain only lowercase alphanumeric characters and dashes.' ),
8888
'6.9.0'
8989
);
9090
return null;
@@ -106,7 +106,7 @@ public function register( string $slug, array $args ): ?WP_Ability_Category {
106106
} catch ( \InvalidArgumentException $e ) {
107107
_doing_it_wrong(
108108
__METHOD__,
109-
esc_html( $e->getMessage() ),
109+
$e->getMessage(),
110110
'6.9.0'
111111
);
112112
return null;
@@ -126,14 +126,14 @@ public function register( string $slug, array $args ): ?WP_Ability_Category {
126126
* @see wp_unregister_ability_category()
127127
*
128128
* @param string $slug The slug of the registered category.
129-
* @return ?\WP_Ability_Category The unregistered category instance on success, null on failure.
129+
* @return WP_Ability_Category|null The unregistered category instance on success, null on failure.
130130
*/
131131
public function unregister( string $slug ): ?WP_Ability_Category {
132132
if ( ! $this->is_registered( $slug ) ) {
133133
_doing_it_wrong(
134134
__METHOD__,
135135
/* translators: %s: Ability category slug. */
136-
sprintf( esc_html__( 'Ability category "%s" not found.' ), esc_attr( $slug ) ),
136+
sprintf( __( 'Ability category "%s" not found.' ), esc_html( $slug ) ),
137137
'6.9.0'
138138
);
139139
return null;
@@ -182,14 +182,14 @@ public function is_registered( string $slug ): bool {
182182
* @see wp_get_ability_category()
183183
*
184184
* @param string $slug The slug of the registered category.
185-
* @return ?\WP_Ability_Category The registered category instance, or null if it is not registered.
185+
* @return WP_Ability_Category|null The registered category instance, or null if it is not registered.
186186
*/
187187
public function get_registered( string $slug ): ?WP_Ability_Category {
188188
if ( ! $this->is_registered( $slug ) ) {
189189
_doing_it_wrong(
190190
__METHOD__,
191191
/* translators: %s: Ability category slug. */
192-
sprintf( esc_html__( 'Ability category "%s" not found.' ), esc_attr( $slug ) ),
192+
sprintf( __( 'Ability category "%s" not found.' ), esc_html( $slug ) ),
193193
'6.9.0'
194194
);
195195
return null;
@@ -232,7 +232,7 @@ public static function get_instance(): self {
232232
* @throws \LogicException If the registry is unserialized. This is a security hardening measure to prevent unserialization of the registry.
233233
*/
234234
public function __wakeup(): void {
235-
throw new \LogicException( self::class . ' must not be unserialized.' );
235+
throw new \LogicException( __CLASS__ . ' should never be unserialized.' );
236236
}
237237

238238
/**
@@ -242,6 +242,6 @@ public function __wakeup(): void {
242242
* @throws \LogicException If the registry is serialized. This is a security hardening measure to prevent serialization of the registry.
243243
*/
244244
public function __sleep(): array {
245-
throw new \LogicException( self::class . ' must not be serialized.' );
245+
throw new \LogicException( __CLASS__ . ' should never be serialized' );
246246
}
247247
}

‎src/wp-includes/abilities-api/class-wp-abilities-registry.php‎

Lines changed: 11 additions & 11 deletions
Original file line numberDiff line numberDiff line change
@@ -22,7 +22,7 @@ final class WP_Abilities_Registry {
2222
* The singleton instance of the registry.
2323
*
2424
* @since 6.9.0
25-
* @var ?self
25+
* @var self|null
2626
*/
2727
private static $instance = null;
2828

@@ -48,7 +48,7 @@ final class WP_Abilities_Registry {
4848
* alphanumeric characters, dashes and the forward slash.
4949
* @param array<string,mixed> $args An associative array of arguments for the ability. See wp_register_ability() for
5050
* details.
51-
* @return ?\WP_Ability The registered ability instance on success, null on failure.
51+
* @return WP_Ability|null The registered ability instance on success, null on failure.
5252
*
5353
* @phpstan-param array{
5454
* label?: string,
@@ -71,7 +71,7 @@ public function register( string $name, array $args ): ?WP_Ability {
7171
if ( ! preg_match( '/^[a-z0-9-]+\/[a-z0-9-]+$/', $name ) ) {
7272
_doing_it_wrong(
7373
__METHOD__,
74-
esc_html__(
74+
__(
7575
'Ability name must be a string containing a namespace prefix, i.e. "my-plugin/my-ability". It can only contain lowercase alphanumeric characters, dashes and the forward slash.'
7676
),
7777
'6.9.0'
@@ -83,7 +83,7 @@ public function register( string $name, array $args ): ?WP_Ability {
8383
_doing_it_wrong(
8484
__METHOD__,
8585
/* translators: %s: Ability name. */
86-
esc_html( sprintf( __( 'Ability "%s" is already registered.' ), $name ) ),
86+
sprintf( __( 'Ability "%s" is already registered.' ), esc_html( $name ) ),
8787
'6.9.0'
8888
);
8989
return null;
@@ -107,9 +107,9 @@ public function register( string $name, array $args ): ?WP_Ability {
107107
__METHOD__,
108108
sprintf(
109109
/* translators: %1$s: ability category slug, %2$s: ability name */
110-
esc_html__( 'Ability category "%1$s" is not registered. Please register the category before assigning it to ability "%2$s".' ),
111-
esc_attr( $args['category'] ),
112-
esc_attr( $name )
110+
__( 'Ability category "%1$s" is not registered. Please register the category before assigning it to ability "%2$s".' ),
111+
esc_html( $args['category'] ),
112+
esc_html( $name )
113113
),
114114
'6.9.0'
115115
);
@@ -121,7 +121,7 @@ public function register( string $name, array $args ): ?WP_Ability {
121121
if ( isset( $args['ability_class'] ) && ! is_a( $args['ability_class'], WP_Ability::class, true ) ) {
122122
_doing_it_wrong(
123123
__METHOD__,
124-
esc_html__( 'The ability args should provide a valid `ability_class` that extends WP_Ability.' ),
124+
__( 'The ability args should provide a valid `ability_class` that extends WP_Ability.' ),
125125
'6.9.0'
126126
);
127127
return null;
@@ -137,7 +137,7 @@ public function register( string $name, array $args ): ?WP_Ability {
137137
} catch ( \InvalidArgumentException $e ) {
138138
_doing_it_wrong(
139139
__METHOD__,
140-
esc_html( $e->getMessage() ),
140+
$e->getMessage(),
141141
'6.9.0'
142142
);
143143
return null;
@@ -157,14 +157,14 @@ public function register( string $name, array $args ): ?WP_Ability {
157157
* @see wp_unregister_ability()
158158
*
159159
* @param string $name The name of the registered ability, with its namespace.
160-
* @return ?\WP_Ability The unregistered ability instance on success, null on failure.
160+
* @return WP_Ability|null The unregistered ability instance on success, null on failure.
161161
*/
162162
public function unregister( string $name ): ?WP_Ability {
163163
if ( ! $this->is_registered( $name ) ) {
164164
_doing_it_wrong(
165165
__METHOD__,
166166
/* translators: %s: Ability name. */
167-
sprintf( esc_html__( 'Ability "%s" not found.' ), esc_attr( $name ) ),
167+
sprintf( __( 'Ability "%s" not found.' ), esc_html( $name ) ),
168168
'6.9.0'
169169
);
170170
return null;

‎src/wp-includes/abilities-api/class-wp-ability-category.php‎

Lines changed: 7 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -83,10 +83,10 @@ public function __construct( string $slug, array $args ) {
8383
__METHOD__,
8484
sprintf(
8585
/* translators: %s: Property name. */
86-
esc_html__( 'Property "%1$s" is not a valid property for category "%2$s". Please check the %3$s class for allowed properties.' ),
86+
__( 'Property "%1$s" is not a valid property for category "%2$s". Please check the %3$s class for allowed properties.' ),
8787
'<code>' . esc_html( $property_name ) . '</code>',
8888
'<code>' . esc_html( $this->slug ) . '</code>',
89-
'<code>' . esc_html( self::class ) . '</code>'
89+
'<code>' . __CLASS__ . '</code>'
9090
),
9191
'6.9.0'
9292
);
@@ -117,20 +117,20 @@ protected function prepare_properties( array $args ): array {
117117
// Required args must be present and of the correct type.
118118
if ( empty( $args['label'] ) || ! is_string( $args['label'] ) ) {
119119
throw new \InvalidArgumentException(
120-
esc_html__( 'The category properties must contain a `label` string.' )
120+
__( 'The category properties must contain a `label` string.' )
121121
);
122122
}
123123

124124
if ( empty( $args['description'] ) || ! is_string( $args['description'] ) ) {
125125
throw new \InvalidArgumentException(
126-
esc_html__( 'The category properties must contain a `description` string.' )
126+
__( 'The category properties must contain a `description` string.' )
127127
);
128128
}
129129

130130
// Optional args only need to be of the correct type if they are present.
131131
if ( isset( $args['meta'] ) && ! is_array( $args['meta'] ) ) {
132132
throw new \InvalidArgumentException(
133-
esc_html__( 'The category properties should provide a valid `meta` array.' )
133+
__( 'The category properties should provide a valid `meta` array.' )
134134
);
135135
}
136136

@@ -188,7 +188,7 @@ public function get_meta(): array {
188188
* @throws \LogicException If the category is unserialized. This is a security hardening measure to prevent unserialization of the category.
189189
*/
190190
public function __wakeup(): void {
191-
throw new \LogicException( self::class . ' must not be unserialized.' );
191+
throw new \LogicException( __CLASS__ . ' should never be unserialized.' );
192192
}
193193

194194
/**
@@ -198,6 +198,6 @@ public function __wakeup(): void {
198198
* @throws \LogicException If the category is serialized. This is a security hardening measure to prevent serialization of the category.
199199
*/
200200
public function __sleep(): array {
201-
throw new \LogicException( self::class . ' must not be serialized.' );
201+
throw new \LogicException( __CLASS__ . ' should never be serialized' );
202202
}
203203
}

0 commit comments

Comments
 (0)