WordPress 7.2 muda a forma como a Abilities API lida com capacidades e dados
A nota de desenvolvimento do Make WordPress Core detalha como a Abilities API passa a tratar permissões, conversão de tipos e saída JSON a partir do WordPress 7.2. Quem registra abilities para REST ou integrações de IA tem código para revisar.
A nota de desenvolvimento do Make WordPress Core detalha como a Abilities API passa a tratar permissões, conversão de tipos e saída JSON a partir do WordPress 7.2. Quem registra abilities para REST ou integrações de IA tem código para revisar.
Esta nota de desenvolvimento foi publicada pelo time do Make WordPress Core em 19 de novembro de 2026 e descreve mudanças na Abilities API que chegam no WordPress 7.2. Ao final, você sabe o que revisar em qualquer plugin que registre wp_register_ability(), seja para expor dados via REST, seja para alimentar um agente de IA através do WordPress AI Client.
O que é a Abilities API, rapidamente
A Abilities API deixa um plugin declarar "capacidades" (abilities) que podem ser descobertas e executadas por três vias: chamada direta em PHP, requisição REST em /wp-json/wp-abilities/v1/abilities e, mais recentemente, por integrações de IA que precisam saber o que um site WordPress pode fazer antes de acionar uma ação. Cada ability declara um input_schema, um output_schema e uma função de execução. O WordPress 7.2 não muda esse modelo básico, mas aperta três pontos: quem pode chamar a ability, como o dado de entrada é preparado e como o resultado vira JSON.
required_capabilities: a checagem obrigatória antes do callback
Antes do 7.2, toda a responsabilidade de checar permissão ficava em permission_callback. Agora existe o argumento required_capabilities, uma lista de strings não vazias checadas uma a uma com current_user_can() antes mesmo do permission_callback rodar. Se qualquer capability da lista falhar, a ability nem chega a avaliar o callback.
<?php
add_action(
'wp_abilities_api_init',
static function (): void {
wp_register_ability(
'my-plugin/get-post-title',
array(
'label' => __( 'Get post title', 'my-plugin' ),
'description' => __( 'Read the title of a post you can edit.', 'my-plugin' ),
'category' => 'my-plugin',
'required_capabilities' => array( 'edit_posts' ),
'input_schema' => array(
'type' => 'integer',
'minimum' => 1,
),
'output_schema' => array( 'type' => 'string' ),
'permission_callback' => static function ( int $post_id ): bool {
return current_user_can( 'edit_post', $post_id );
},
'execute_callback' => static function ( int $post_id ): string {
return get_post_field( 'post_title', $post_id, 'raw' );
},
'meta' => array(
'show_in_rest' => true,
'annotations' => array( 'readonly' => true ),
),
)
);
}
);Nesse exemplo, edit_posts é exigido para toda chamada; o permission_callback entra depois só para checar se o usuário pode editar aquele post específico. Quando a capability já cobre 100% dos casos, o manual cita core/settings-get, que exige apenas manage_options e omite permission_callback por completo. A regra prática: use required_capabilities sozinho quando a checagem não depende do input; combine com permission_callback quando depender; e só use __return_true quando a ability deve mesmo ser executável por qualquer pessoa.
Um efeito colateral útil: com $ability->get_required_capabilities() e o filtro de descoberta has_required_capabilities, dá para listar só as abilities cujas capabilities declaradas o usuário atual possui, tanto em PHP (wp_get_abilities( array( 'has_required_capabilities' => true ) )) quanto via REST (GET /wp-json/wp-abilities/v1/abilities?has_required_capabilities=true).
Mas esse filtro não roda permission_callback nem o filtro wp_ability_permission_result — uma ability pode aparecer na descoberta e ainda assim negar a execução para um input específico, caso um autor tente usá-la no rascunho de outro autor, por exemplo. Por isso a nota recomenda declarar em required_capabilities só o que vale para toda chamada: colocar ali uma exigência que depende do input esconde a ability de quem teria permissão de executá-la com outro valor.
prepare_input() centraliza normalização, validação e sanitização
O método WP_Ability::prepare_input() agora concentra o que execute() sempre fez por baixo dos panos: normaliza o input (aplicando o default do schema quando ele é null), valida contra o input_schema e só então sanitiza o valor já validado. Os callbacks de permissão e execução recebem esse valor pronto — inclusive a conversão de tipo, como '123' virando o inteiro 123.
Isso importa para quem chama check_permissions() fora do ciclo normal de execute(), porque esse método não prepara o input sozinho:
<?php
$ability = wp_get_ability( 'my-plugin/get-post-title' );
if ( null === $ability ) {
return new WP_Error( 'example_missing_ability', 'The ability is not registered.' );
}
$input = $ability->prepare_input( '123' );
if ( is_wp_error( $input ) ) {
return $input;
}
// $input agora é o inteiro 123.
$permission = $ability->check_permissions( $input );
if ( is_wp_error( $permission ) ) {
return $permission;
}
if ( true !== $permission ) {
return new WP_Error( 'example_forbidden', 'You cannot edit this post.' );
}
// Isso só checa permissão. Para executar de verdade, use execute().Se o seu código tinha um caminho próprio que chamava normalize_input() seguido de validate_input(), troque pelos dois por prepare_input(): normalize_input() sozinho não valida nem sanitiza, e validate_input() devolve um resultado de validação, não o valor pronto. O método sanitize_input_for_ability() do controlador REST foi descontinuado nesta versão e sua implementação de compatibilidade agora só devolve o input sem alterar nada — não conte com ele para sanitização de verdade.
Números passam a chegar como float, não como int
Um schema type: number agora converte um inteiro como 10 para o float 10.0 em chamadas diretas de PHP, igualando o comportamento que o REST já tinha. Isso quebra silenciosamente qualquer callback que faça is_int( $input ) ou $input === 10:
<?php
// Antes, dependendo do caminho, o valor podia chegar como int.
'execute_callback' => static function ( $price ) {
if ( is_int( $price ) ) { // não confie mais nisso
// ...
}
},
// A partir do WordPress 7.2, assuma float e tipe o parâmetro:
'execute_callback' => static function ( float $price ): string {
return number_format( $price, 2 );
},Use um schema integer quando o callback precisar mesmo de um inteiro. A mesma lógica de conversão vale para outros formatos: a string "false" vira o booleano false, e "1,2" vira array( 1, 2 ) num schema de array de inteiros.
Falha de sanitização agora interrompe a execução
Um input pode passar na validação e falhar na sanitização. O exemplo da nota é direto: array( '1', '01' ) são duas strings distintas, mas ambas viram o inteiro 1 depois de sanitizadas — o que quebra um schema de array de inteiros com uniqueItems: true.
No WordPress 7.2, essa falha retorna o erro ability_invalid_input (inclusive quando acontece num campo aninhado) antes de permission_callback ou execute_callback rodarem, e o endpoint REST responde HTTP 400. Antes, um campo que falhava podia cair de volta no input original não sanitizado — e deixar, por exemplo, a string "false" chegando num permission_callback que avalia isso como truthy em PHP. Esse fallback perigoso foi removido.
JSON preserva objeto vazio em vez de virar array
Um array PHP vazio sempre virou [] na codificação JSON, mesmo quando o schema descrevia um objeto — e um cliente esperando {} recebia []. As novas funções wp_prepare_json_schema_for_client() e wp_prepare_json_value_for_client() resolvem isso respeitando o tipo declarado no schema:
<?php
$schema = array(
'type' => 'object',
'default' => array(),
);
echo wp_json_encode( wp_prepare_json_schema_for_client( $schema ) );
// {"type":"object","default":{}}A mesma regra vale para valores de resultado, inclusive em propriedades aninhadas e itens de array. Se você mantém um transporte próprio (fora do controlador REST padrão), prepare o resultado com o output_schema da ability antes de serializar:
<?php
$result = $ability->execute( $raw_input );
if ( is_wp_error( $result ) ) {
return $result;
}
return wp_json_encode(
wp_prepare_json_value_for_client(
$result,
$ability->get_output_schema()
)
);Uma chamada direta a $ability->execute() continua devolvendo o retorno cru do callback, sem passar por essa etapa de representação JSON — a preparação só entra na hora de serializar. Ability authors devem declarar type: object ou type: array de forma explícita no output_schema, inclusive em propriedades aninhadas cujo valor vazio importa para quem consome.
Como pegar essas quebras antes do usuário
Nada disso dispara erro de sintaxe: são mudanças de comportamento em runtime, do tipo que só aparece quando is_int() retorna false de repente ou quando um teste de integração falha com HTTP 400. Rodar análise estática com os stubs do WordPress ajuda a flagrar parâmetros tipados incorretamente antes do deploy:
composer require --dev phpstan/phpstan szepeviktor/phpstan-wordpressCom um phpstan.neon apontando para o bootstrap dos stubs:
parameters:
level: 6
bootstrapFiles:
- vendor/szepeviktor/phpstan-wordpress/bootstrap.phpvendor/bin/phpstan analyse src --level=6Se um execute_callback ainda espera int $price onde o schema é number, atualizar a assinatura para float tende a expor essa incompatibilidade de tipo numa análise estática antes mesmo de rodar o código em produção. Não substitui testar contra um WordPress 7.2 de verdade, mas encurta o ciclo de descoberta do problema.
Próximo passo
Se o plugin precisa continuar funcionando em versões anteriores ao 7.2, trate required_capabilities como opt-in condicional: omitir permission_callback em favor dele só é seguro a partir do 7.2, então mantenha o callback antigo como fallback com version_compare( $GLOBALS['wp_version'], '7.2', '>=' ) ou checagem equivalente. Vale revisar cada callback que dependia do tipo original do PHP ou de input não sanitizado, e qualquer caminho de permissão customizado que pulava a preparação do input.
As três tickets do Trac ligadas à mudança — #66325 (capabilities), #66383 (preparação de input) e #66267 (objetos vazios em JSON) — têm o histórico de discussão técnica caso um comportamento específico não fique claro. Dúvida de implementação tem lugar certo: o canal #core no Slack do WordPress, no mesmo horário das reuniões semanais de desenvolvimento, às quartas-feiras.
Fonte: Make WordPress Core
Este artigo foi escrito por Thiago Vilela. Conteúdo produzido por agente de IA da redação Linha de Código. Saiba como produzimos no expediente.
Editor virtual de PHP do Linha de Código. Escreve o PHP moderno — tipos, enums, readonly, match — com Laravel, Symfony, Composer e PHPStan, e o WordPress do lado de quem programa plugin e tema. Fala com quem herdou um sistema PHP 5 e precisa levá-lo para a versão com suporte sem parar a empresa.