Personalizações para devs

Esta página reúne hooks, snippets e personalizações para desenvolvedores que querem ajustar o comportamento do plugin sem editar o core.

Filtro: woocommerce_shortcode_products_query

Esse é o filtro nativo do WooCommerce, usado pelo WC_Shortcode_Products na renderização final da vitrine. O plugin já se engata nele pra forçar orderby = post__in e preservar a ordem de ranking de vendas.

Quando o filtro é útil pra você: ajustar outros aspectos da query (campos extras, taxonomias, meta queries, paginação) sem perder o ordenamento por vendas.

add_filter( 'woocommerce_shortcode_products_query', 'meu_ajuste_query_mais_vendidos', 20 );

function meu_ajuste_query_mais_vendidos( $query_args ) {
    // Exemplo: incluir só produtos de uma categoria específica
    $query_args['tax_query'] = array(
        array(
            'taxonomy' => 'product_cat',
            'field'    => 'slug',
            'terms'    => array( 'eletronicos' ),
        ),
    );

    return $query_args;
}

Alterar a duração do cache

O cache padrão de 24h vive na constante DAY_IN_SECONDS dentro do método get_product_ids(). Pra trocar por outro intervalo sem editar o plugin, a forma mais limpa é forçar uma invalidação periódica via cron.

Snippet pra limpar o cache a cada hora (cuidado — derruba todo o ganho de performance):

add_action( 'init', function () {
    if ( ! wp_next_scheduled( 'limpar_cache_mais_vendidos' ) ) {
        wp_schedule_event( time(), 'hourly', 'limpar_cache_mais_vendidos' );
    }
} );

add_action( 'limpar_cache_mais_vendidos', function () {
    global $wpdb;

    $wpdb->query(
        "DELETE FROM {$wpdb->options}
         WHERE option_name LIKE '\_transient\_best\_selling\_by\_period\_%'
            OR option_name LIKE '\_transient\_timeout\_best\_selling\_by\_period\_%'"
    );
} );

Limpeza programática pontual

Pra invalidar o cache sob demanda — depois de uma reposição grande de estoque, ao final de uma campanha — chame a mesma rotina manualmente em qualquer hook:

function refresh_mais_vendidos() {
    global $wpdb;

    $wpdb->query(
        "DELETE FROM {$wpdb->options}
         WHERE option_name LIKE '\_transient\_best\_selling\_by\_period\_%'
            OR option_name LIKE '\_transient\_timeout\_best\_selling\_by\_period\_%'"
    );
}

// Exemplo: invalidar quando um produto volta ao estoque
add_action( 'woocommerce_product_set_stock_status', function ( $product_id, $stock_status ) {
    if ( 'instock' === $stock_status ) {
        refresh_mais_vendidos();
    }
}, 10, 2 );

Considerar mais statuses de pedido

Por padrão, apenas pedidos completed e processing entram no cálculo. Pra incluir outros (por exemplo, on-hold em lojas que mandam pedido pra produção antes da confirmação), seria preciso editar o array order_status no método get_product_ids(). Não há filtro pra modificar isso externamente — abra um issue ou ajuste no fork se for um caso de uso recorrente.

Renderizar via PHP

Quando precisar do shortcode dentro de um template do tema:

echo do_shortcode( '[best_selling_by_period limit="12" period="month"]' );

Ou montando os atributos dinamicamente:

$atts = sprintf(
    '[best_selling_by_period limit="%d" period="%s"]',
    20,
    'last_month'
);

echo do_shortcode( $atts );

Próximos passos

• Cache e atualização — comportamento default do cache que esses snippets contornam.
• Estoque e status de pedido — entender o filtro padrão antes de modificar.