← Technical blog

WordPress · PHP · Functional tests

A bounded WordPress shortcode with escaped output

A short walkthrough of the Reference Cards portfolio lab, from query limits to real WordPress integration checks.

Keep the feature small

A recent portfolio extension is Reference Cards, a small WordPress plugin that displays published articles through a shortcode. The goal is a reviewable feature: a title, a date, a short excerpt and a link. No external API, page builder or JavaScript is needed. Keeping this scope small makes its behavior easier to explain and test.

The shortcode accepts a card count and a category slug. The default is three cards. Integer input is limited to one through twelve, and non-integer input uses the default. A nonempty category that becomes an empty slug returns an empty state instead of selecting every category. This is a personal lab with synthetic content, separate from the private client plugin summarized in the portfolio.

[reference_cards count="3" category="guides"]

Select public content explicitly

The query specifies the post type, publication status and password rule. That matters even when the visitor is a signed-in administrator. It should still render the same public selection. The lab also disables sticky-post promotion and pagination totals, because a small card list does not need either behavior.

$args = array(
    'post_type'           => 'post',
    'post_status'         => 'publish',
    'has_password'        => false,
    'posts_per_page'      => card_limit( $attributes['count'] ),
    'no_found_rows'       => true,
    'ignore_sticky_posts' => true,
    'orderby'             => array( 'date' => 'DESC', 'ID' => 'DESC' ),
);

The renderer iterates over the returned post objects and passes each object to template functions. It never calls the_post(). This avoids changing the surrounding main or nested Loop. A conventional secondary Loop that calls the_post() needs the appropriate reset afterward, as the WordPress reference explains.

Escape at the output boundary

Content remains untrusted when it comes from the database. A title can contain markup, and a filter can change a permalink. The renderer uses esc_html() for text, esc_url() for links and esc_attr() for date attributes. These functions address different output contexts. Category normalization does not replace output escaping.

$html .= '<a href="' . esc_url( get_permalink( $article ) ) . '">'
    . esc_html( $title ) . '</a>';

Excerpts are stripped to plain text, shortened and then escaped. Missing titles receive a descriptive fallback. If the query raises a controlled error, the visitor gets a generic unavailable message. Paths, SQL and exception details stay out of the page.

Test through real WordPress

The verified run completed 29 functional checks on 12 October 2026 using WordPress 7.1.3, PHP 8.3.35 and MySQL 8.4.11. These are the recorded versions for that run, not a claim about every supported installation. The workflow installs disposable WordPress, activates the plugin and runs a fresh PHP process against real database fixtures.

Fixtures include published posts, drafts, private content, a password-protected post, a future post and another category. Assertions check visibility, ordering, count limits, Loop preservation, empty states and adversarial output. The exact report lists every result. The completed CI run retains the installable ZIP and actual rendered HTML.

Reproduce and inspect

Clone the portfolio repository and build the plugin archive with the command below. Install it in a disposable WordPress site, publish sample articles in a guides category and add the shortcode to a page. The lab README includes the full isolated database setup for the integration suite.

python3 wordpress-lab/scripts/package.py --output /tmp/reference-cards-1.0.0.zip

Do not run the fixture installer against an existing site. It creates and removes sample content in the isolated database. Automated HTML checks also do not establish visual accessibility or every theme combination. Keyboard use, narrow layouts and assistive technology need their separate manual checklist.

Source and references

About these notes

More technical notes ↗Discuss a scoped task ↗