benecaster_donor_wall_item

Fires once per rendered row inside DonorWallShortcode::render(), wrapping the built-in card markup. Receives the complete HTML string for a single donor card, the raw donation row object, and the show ID.

Return the $html unchanged to pass through, return a replacement string to swap the card wholesale, or return '' to suppress the row entirely. Suppressing a row leaves the outer .benecaster-donor-wall wrapper in place — downstream CSS that targets the wrapper class keeps working even when all rows are suppressed.

Additive decoration is safer than wholesale replacement. Using str_replace to inject markup into specific BEM elements keeps the card functional if the default markup evolves — wholesale replacement means your override must track every upstream card change manually.

Composable with other _item callbacks. Multiple callbacks on this filter run in WordPress priority order. The donor-wall-highlight-top-supporters (badge) and donor-wall-per-tier-message (tier label) recipes both use this filter and compose cleanly — each receives the HTML as the previous callback left it.

<?php
add_filter( 'benecaster_donor_wall_item', function ( string $html, object $donation, int $show_id ): string {
    $threshold = 100.00; // major-currency units — e.g. $100 USD, ¥100 JPY.
    $amount    = isset( $donation->amount ) ? (float) $donation->amount : 0.0;

    if ( $amount < $threshold ) {
        return $html;
    }

    $badge = '<span class="my-theme-top-supporter-badge" aria-label="' . esc_attr__( 'Top supporter', 'my-theme' ) . '">★</span>';

    // Inject the badge inside the header div so it sits alongside the name.
    return str_replace(
        '<div class="benecaster-donor-wall__header">',
        '<div class="benecaster-donor-wall__header">' . $badge,
        $html
    );
}, 10, 3 );

<?php
add_filter( 'benecaster_donor_wall_item', function ( string $html, object $donation, int $show_id ): string {
    $amount = isset( $donation->amount ) ? (float) $donation->amount : 0.0;
    if ( $amount <= 0 ) {
        return $html;
    }

    // Amount thresholds are in major-currency units — adjust or branch on
    // $donation->currency for multi-currency shows.
    if ( $amount >= 100 ) {
        $tier    = 'gold';
        $message = __( 'Legendary tip — thank you!', 'my-theme' );
    } elseif ( $amount >= 25 ) {
        $tier    = 'silver';
        $message = __( 'Amazing support — thank you!', 'my-theme' );
    } elseif ( $amount >= 5 ) {
        $tier    = 'bronze';
        $message = __( 'Thanks for the boost!', 'my-theme' );
    } else {
        return $html;
    }

    $badge = sprintf(
        '<div class="my-theme-donor-wall__tier my-theme-donor-wall__tier--%s">%s</div>',
        esc_attr( $tier ),
        esc_html( $message )
    );

    // Append the tier message inside the item wrapper. The card's built-in
    // markup ends with `</div></div>` (outer div closes the item; inner one
    // closes the header). Anchor on end-of-string so we insert just before
    // the item wrapper's closing tag.
    return (string) preg_replace(
        '#</div>\s*$#',
        $badge . '</div>',
        $html,
        1
    );
}, 10, 3 );