This content originally appeared on DEV Community and was authored by Pranto Mollick
Learn to fetch upcoming WordPress events with WP_Query: numeric date sorting, meta_query filters, and a bilingual walkthrough (EN + BN).
Introduction
If you’re building a WordPress site that needs to show upcoming events—like a school’s “Science Fair” or a community “Sports Day”—you’ll often reach for WP_Query. In this post, we’ll walk through a practical snippet that fetches the next two upcoming events, explain exactly how it works, why it’s written this way, and how to extend it. You’ll see the English explanation side-by-side with Bengali to make the concepts stick.
Step 1 — What this code does (Context)
English:
We’re querying the WordPress database to get the next two upcoming “event” posts, sorted by a custom field called event_date so the soonest events appear first.
Bengali:
আমরা ওয়ার্ডপ্রেস ডাটাবেসে কোয়েরি চালিয়ে ‘event’ টাইপের পরবর্তী দুইটি ইভেন্ট আনছি। এগুলোকে event_date নামের কাস্টম ফিল্ড দিয়ে সাজানো হচ্ছে, যাতে দ্রুত আসছে এমন ইভেন্টগুলো আগে দেখা যায়।
Step 2 — The core snippet
$events = new WP_Query(array(
'posts_per_page' => 2,
'post_type' => 'event',
'meta_key' => 'event_date',
'orderby' => 'meta_value_num',
'order' => 'ASC'
));
Looping through results:
if ($events->have_posts()) {
while ($events->have_posts()) {
$events->the_post();
// Example output:
// the_title();
// echo get_post_meta(get_the_ID(), 'event_date', true);
}
wp_reset_postdata();
}
English:
- posts_per_page limits results to two.
- post_type ensures we’re only looking at events.
- meta_key tells WP_Query which custom field controls sorting.
- orderby => meta_value_num sorts numerically (ideal for YYYYMMDD or timestamps).
- order => ASC means earliest dates appear first.
Bengali:
- posts_per_page মানে আমরা ২টি রেজাল্ট চাই।
- post_type => event মানে কেবল ইভেন্ট পোস্টই আনবো।
- meta_key দিয়ে কোন কাস্টম ফিল্ডে সাজাবো তা বলা হয়েছে।
- orderby => meta_value_num সংখ্যাগতভাবে সাজায় (YYYYMMDD বা timestamp আদর্শ)।
- order => ASC মানে আগের তারিখ আগে দেখাবে।
Step 3 — How the data flows
English:
- Input: An array of arguments (post_type, meta_key, orderby, etc.).
- Processing: WP_Query translates this into SQL for MySQL.
- Database: Filters to event posts, looks at event_date, sorts ascending, returns top 2.
- Output: A WP_Query object in $events you can loop through.
Bengali:
- ইনপুট: আর্গুমেন্টের অ্যারে (post_type, meta_key, orderby, ইত্যাদি)।
- প্রসেসিং: WP_Query এটিকে SQL-এ রূপান্তর করে।
- ডাটাবেস: event পোস্ট ফিল্টার, event_date দেখে সাজানো, শীর্ষ ২ ফেরত।
- আউটপুট: $events অবজেক্ট, যেটি লুপ করে দেখানো যায়।
Step 4 — Why this approach is best practice
English:
Let the database do the heavy lifting. Sorting/filtering in MySQL via WP_Query is faster and more memory-efficient than fetching everything and sorting in PHP. Using orderby => meta_value_num ensures dates stored as numbers (e.g., 20251107 or Unix timestamps) sort correctly.
Bengali:
ফিল্টারিং/সোর্টিং ডাটাবেসেই করাই শ্রেয়। WP_Query MySQL-এ কাজ করায় দ্রুত ও কম মেমরি লাগে। meta_value_num ব্যবহার করলে সংখ্যায়িত তারিখ (যেমন 20251107 বা timestamp) ঠিকভাবে সাজে।
Step 5 — Common pitfalls and fixes
1) Dates sorting wrong (e.g., “December” before “November”)
- Cause: Dates stored as strings (“December 1, 2025”).
- Fix: Store event_date as numeric (YYYYMMDD or Unix timestamp). Keep orderby => meta_value_num.
2) Getting posts from other types
- Cause: Missing post_type => event.
- Fix: Ensure post_type is set to event.
3) Showing past events before upcoming
- Cause: ASC is fine, but you also need to filter out past dates.
- Fix: Add a meta_query to only include today or future.
Example: only today/future
$today = date('Ymd');
$events = new WP_Query(array(
'posts_per_page' => 2,
'post_type' => 'event',
'meta_key' => 'event_date',
'orderby' => 'meta_value_num',
'order' => 'ASC',
'meta_query' => array(
array(
'key' => 'event_date',
'value' => $today,
'compare' => '>=',
'type' => 'NUMERIC'
)
)
));
Step 6 — Excluding cancelled events (extension)
English:
If you store an event_status custom field and want to exclude “Cancelled” events:
Bengali:
event_status নামে কাস্টম ফিল্ড থাকলে “Cancelled” বাদ দিতে:
$events = new WP_Query(array(
'posts_per_page' => 2,
'post_type' => 'event',
'meta_key' => 'event_date',
'orderby' => 'meta_value_num',
'order' => 'ASC',
'meta_query' => array(
'relation' => 'AND',
array(
'key' => 'event_status',
'value' => 'Cancelled',
'compare' => '!='
),
array(
'key' => 'event_date',
'value' => date('Ymd'),
'compare' => '>=',
'type' => 'NUMERIC'
)
)
));
Step 7 — Quick analogy
English:
Think of WP_Query as asking a librarian: “Please find books from the ‘events’ shelf, sort them by date from soonest to latest, and give me just the top two.” The librarian searches the stacks (database), sorts properly, and returns exactly what you asked for.
Bengali:
WP_Query হল লাইব্রেরিয়ানকে বলা: “events শেলফ থেকে বই নিন, তারিখ অনুযায়ী (নিকটতম আগে) সাজান, আর শীর্ষ দুইটি দিন।” লাইব্রেরিয়ান (ডাটাবেস) ঠিক সেভাবেই ফলাফল দেয়।
Bonus — Display template idea
<?php if ($events->have_posts()): ?>
<section class="upcoming-events">
<h2>Upcoming Events</h2>
<ul>
<?php while ($events->have_posts()): $events->the_post(); ?>
<li>
<a href="<?php the_permalink(); ?>"><?php the_title(); ?></a>
<?php
$date = get_post_meta(get_the_ID(), 'event_date', true);
if ($date) {
// Format YYYYMMDD to Y-m-d for readability
echo ' — ' . DateTime::createFromFormat('Ymd', $date)->format('M j, Y');
}
?>
</li>
<?php endwhile; wp_reset_postdata(); ?>
</ul>
</section>
<?php endif; ?>
Mini Quiz
1) Easy: How would you change the code to fetch the next 5 events?
- Answer: Change posts_per_page => 2 to posts_per_page => 5.
2) Medium: Dates look out of order—what’s a likely cause?
- Answer: event_date stored as human text (e.g., “December 1, 2025”) instead of numeric (YYYYMMDD). Store numeric and use meta_value_num.
3) Hard: How do you exclude events with event_status = “Cancelled”?
- Answer: Add a meta_query with compare => ‘!=’ on key event_status, plus your date constraint.
Takeaways
- Store dates numerically (YYYYMMDD or Unix timestamps) for reliable sorting.
- Use meta_value_num for numeric meta sorting.
- Filter out past events with a meta_query against today’s date.
- Extend with additional conditions (status, venue, capacity) via meta_query.
This content originally appeared on DEV Community and was authored by Pranto Mollick