`have_posts()`

توقيع: have_posts()
ترجع: bool — هل هناك منشورات متبقية في الـWP Query الحالية؟
متى نستخدمها: لبدء حلقة العرض القياسية: while ( have_posts() ) { the_post(); ... }.
ملاحظات: لا تطبع شيء، فقط تفحص الحالة.

مثال

<?php 
if ( have_posts() ) : while ( have_posts() ) : the_post(); ?>
    <h1><?php the_title(); ?></h1>
    <?php the_content(); ?>
<?php endwhile; endif; ?>

<?php 
if ( have_posts() ) : while ( have_posts() ) : the_post(); ?>
    <h1><?php the_title(); ?></h1>
    <?php the_content(); ?>
<?php endwhile; endif; ?>

PHP

`the_post()`

توقيع: the_post()
ترجع: لا شيء (تعمل تغييرات على $post العام).
وظيفة: تجهّز بيانات المنشور الحالي للاستخدام (setup_postdata).
متى: داخل كل تكرار من while ( have_posts() ).

مثال

<?php while ( have_posts() ) : the_post(); ?>
    <article id="post-<?php the_ID(); ?>" <?php post_class(); ?>>
        <?php the_title('<h1>','</h1>'); ?>
    </article>
<?php endwhile; ?>

<?php while ( have_posts() ) : the_post(); ?>
    <article id="post-<?php the_ID(); ?>" <?php post_class(); ?>>
        <?php the_title('<h1>','</h1>'); ?>
    </article>
<?php endwhile; ?>

PHP

`get_header( $name = null )`

توقيع: get_header( $name = null )
وظيفة: يضم ملف header.php أو header-$name.php.
متى: عادة في أعلى ملف القالب.
ملاحظة: لا تطبع رأس HTML قبل استدعاء دوال تعتمد على الهيدر إن لزم.

مثال

<?php
get_header(); // أو get_header('home') لتحميل header-home.php
?>

<?php
get_header(); // أو get_header('home') لتحميل header-home.php
?>

PHP

`get_footer( $name = null )`

توقيع: get_footer( $name = null )
وظيفة: يضم footer.php أو footer-$name.php في نهاية القالب.

مثال

<?php
// نهاية single.php
get_footer();
?>

<?php
// نهاية single.php
get_footer();
?>

PHP

دوال بيانات المنشور (IDs, Title, Permalink, Date)

`get_the_ID()`

توقيع: get_the_ID()
ترجع: int — معرف المنشور الحالي داخل الـLoop.
متى: عندما تحتاج الـID كقيمة (مثلاً لجلب metadata).

مثال

<?php $id = get_the_ID(); ?>
<p>Post ID: <?php echo intval( $id ); ?></p>

<?php $id = get_the_ID(); ?>
<p>Post ID: <?php echo intval( $id ); ?></p>

PHP

`the_ID()`

توقيع: the_ID()
وظيفة: تطبع معرف المنشور مباشرة (echo).
ملاحظة: لا تستخدم echo the_ID();.

مثال

<p>ID: <?php the_ID(); ?></p>

<p>ID: <?php the_ID(); ?></p>

PHP

`get_the_title( $post = 0 )`

توقيع: get_the_title( $post = 0 )
ترجع: string — عنوان المنشور (لا يطبع).
متى: عندما تريد تعديل/تعقيم العنوان قبل الطباعة.

مثال

<?php
$title = get_the_title();
echo '<h1>' . esc_html( $title ) . '</h1>';
?>

<?php
$title = get_the_title();
echo '<h1>' . esc_html( $title ) . '</h1>';
?>

PHP

`the_title( $before = '', $after = '', $echo = true )`

توقيع: the_title( $before = '', $after = '', $echo = true )
وظيفة: تُخرِج العنوان مباشرة؛ يمكن تمرير $before/$after. إذا مررت $echo = false فستُعيد العنوان بدل الطباعة.
متى: للاخراج السريع داخل القالب.

مثال

<?php the_title( '<h1 class="entry-title">', '</h1>' ); ?>

<?php the_title( '<h1 class="entry-title">', '</h1>' ); ?>

PHP

`get_permalink( $post = 0 )`

توقيع: get_permalink( $post = 0 )
ترجع: string — رابط ثابت للمنشور.
متى: عند بناء روابط (وشير على شبكات اجتماعية، أو روابط مخصصة).

مثال

<a href="<?php echo esc_url( get_permalink() ); ?>">اقرأ المزيد</a>

<a href="<?php echo esc_url( get_permalink() ); ?>">اقرأ المزيد</a>

PHP

`the_permalink()`

توقيع: the_permalink()
وظيفة: تطبع الرابط الثابت مباشرة (بديل لـ echo get_permalink()).

مثال

<a href="<?php the_permalink(); ?>">رابط المقال</a>

<a href="<?php the_permalink(); ?>">رابط المقال</a>

PHP

`get_the_date( $format = '', $post = null )`

توقيع: get_the_date( $format = '', $post = null )
ترجع: string — تاريخ المنشور بحسب التنسيق.
متى: لعرض التاريخ كسلسلة قابلة للتعديل.

مثال

<p>نشر بتاريخ: <?php echo esc_html( get_the_date( 'j F, Y' ) ); ?></p>

`the_time( $format = '' )` / `get_the_time()`

توقيع: the_time( $format = '' ) / get_the_time( $format = '' )
وظيفة: تطبع/ترجع وقت نشر المنشور (ساعة/دقيقة) حسب التنسيق.

مثال

<p>الوقت: <?php the_time( 'H:i' ); ?></p>

التصنيفات والوسوم (Taxonomies)

`get_the_terms( $post_id, $taxonomy )`

توقيع: get_the_terms( $post_id, $taxonomy )
ترجع: array(WP_Term) أو false أو WP_Error.
متى: عندما تريد تحكمًا كاملاً في النتائج (الاسم، الرابط، الوصف…).
مهم: افحص if ( $terms && ! is_wp_error( $terms ) ) قبل الضبط.

مثال

<?php
$cats = get_the_terms( get_the_ID(), 'category' );
if ( $cats && ! is_wp_error( $cats ) ) {
    foreach ( $cats as $cat ) {
        echo '<a href="' . esc_url( get_term_link( $cat ) ) . '">' . esc_html( $cat->name ) . '</a> ';
    }
}
?>

`get_term_link( $term, $taxonomy = '' )`

توقيع: get_term_link( $term, $taxonomy = '' )
ترجع: string (URL) أو WP_Error.
متى: لتحويل WP_Term أو معرف الترم إلى رابط أرشيف التصنيف.

مثال

<?php
$term_link = get_term_link( $cat );
if ( ! is_wp_error( $term_link ) ) {
    echo esc_url( $term_link );
}
?>

`the_category( $separator = ', ' )`

توقيع: the_category( $separator = ', ' )
وظيفة: تطبع روابط التصنيفات للفست المناظرة. أسهل للاستخدام السريع.

مثال

<p>التصنيفات: <?php the_category( ' • ' ); ?></p>

`the_tags( $before = '', $sep = ', ', $after = '' )`

توقيع: the_tags( $before = '', $sep = ', ', $after = '' )
وظيفة: تطبع وسوم المنشور كرابط.

مثال

<?php the_tags( '<p>Tags: ', ' | ', '</p>' ); ?>

الصور والمرفقات (Media & Attachments)

`has_post_thumbnail( $post = null )`

توقيع: has_post_thumbnail( $post = null )
ترجع: bool — هل للمقال صورة مميزة؟
متى: فحص قبل عرضها لتجنّب فراغات HTML.

مثال

<?php if ( has_post_thumbnail() ) : the_post_thumbnail( 'large' ); endif; ?>

`the_post_thumbnail( $size = 'post-thumbnail', $attr = '' )`

توقيع: the_post_thumbnail( $size = 'post-thumbnail', $attr = '' )
وظيفة: تطبع وسم <img> للصورة المميزة؛ يقبل سمات كمصفوفة أو string.

مثال

<?php the_post_thumbnail( 'medium', array( 'loading' => 'lazy', 'alt' => esc_attr( get_the_title() ) ) ); ?>

`get_the_post_thumbnail( $post = null, $size = 'post-thumbnail', $attr = '' )`

توقيع: get_the_post_thumbnail( $post = null, $size = 'post-thumbnail', $attr = '' )
ترجع: HTML <img> كسلسلة — مفيد إذا تريد تعديل العلامة أو حفظها في متغير.

مثال

<?php
$img_html = get_the_post_thumbnail( get_the_ID(), 'large' );
echo $img_html; // أو تعديل قبل الطباعة
?>

`wp_get_attachment_image( $attachment_id, $size = 'thumbnail', $icon = false, $attr = '' )`

توقيع: wp_get_attachment_image( $attachment_id, $size, $icon, $attr )
وظيفة: يعرض HTML صورة من مرفقات المكتبة (attachment ID). مفيد لعرض مرفقات مخصّصة.

مثال

<?php
$attachment_id = 123;
echo wp_get_attachment_image( $attachment_id, 'medium', false, array( 'alt' => 'وصف الصورة' ) );
?>

`get_children( $args = array() )`

توقيع: get_children( $args )
ترجع: مصفوفة عناصر attachment (WP_Post) — تُستخدم لجلب مرفقات لعمل جاليري.

مثال

<?php
$images = get_children( array(
  'post_parent' => get_the_ID(),
  'post_type'   => 'attachment',
  'post_mime_type' => 'image',
  'orderby'     => 'menu_order',
) );
foreach ( $images as $img ) {
    echo wp_get_attachment_image( $img->ID, 'thumbnail' );
}
?>

المؤلف (Author)

`get_the_author_meta( $field = '', $user_id = false )`

توقيع: get_the_author_meta( $field = '', $user_id = false )
ترجع: قيمة الحقل المطلوب (display_name, user_email, description,…).
متى: لعرض بيانات الكاتب كقيمة قابلة للتعقيم.

مثال

<?php
$author_name = get_the_author_meta( 'display_name' );
echo '<p>بقلم: ' . esc_html( $author_name ) . '</p>';
?>

`the_author_posts_link()`

توقيع: the_author_posts_link()
وظيفة: تطبع رابطًا لصفحة أرشيف مؤلفات الكاتب باسم الكاتب (للمستخدمين داخل الـLoop).

مثال

<p>Author: <?php the_author_posts_link(); ?></p>

`get_author_posts_url( $author_id )`

توقيع: get_author_posts_url( $author_id )
ترجع: رابط أرشيف الكاتب.

مثال

<?php
$author_id = get_the_author_meta( 'ID' );
echo '<a href="' . esc_url( get_author_posts_url( $author_id ) ) . '">' . esc_html( get_the_author() ) . '</a>';
?>

المحتوى والـexcerpt

`the_content( $more_link_text = null, $strip_teaser = false )`

توقيع: the_content( $more_link_text = null, $strip_teaser = false )
وظيفة: تطبع محتوى البوست بعد تطبيق فلتر the_content (shortcodes، oEmbed، autop…).
متى: في صفحة single عادةً تُستخدم raw the_content() لعرض المحتوى الكامل.

مثال

<main class="entry-content">
    <?php the_content(); ?>
</main>

`get_the_content( $more_link = false )` + `apply_filters( 'the_content', $content )`

توقيع: get_the_content()
ترجع: المحتوى الخام؛ إذا أردت نفس معالجة the_content فاستعمل: $content = apply_filters( 'the_content', get_the_content() ); echo $content;
متى: عندما تريد معالجة/التعديل قبل إخراج المحتوى.

مثال

<?php
$content = apply_filters( 'the_content', get_the_content() );
echo $content; // الآن مرر عبر فلترات the_content
?>

`the_excerpt()` / `get_the_excerpt()`

الغرض: طباعة/إرجاع الملخص (excerpt). مفيد في الأرشيفات أو قوائم المقالات.

مثال

<?php if ( has_excerpt() ) {
    the_excerpt();
} else {
    echo wp_trim_words( get_the_content(), 40 );
} ?>

روابط التنقل (Adjacent / Pagination)

`get_previous_post()` / `get_next_post()`

توقيع: get_previous_post( $in_same_term = false, $excluded_terms = '', $taxonomy = 'category' )
ترجع: WP_Post أو null.
متى: عندما تريد روابط سابِق/التالي ككائن لتتحكم بالعرض.

مثال

<?php
$prev = get_previous_post();
if ( $prev ) {
    echo '<a href="' . esc_url( get_permalink( $prev ) ) . '">' . esc_html( get_the_title( $prev ) ) . '</a>';
}
?>

`previous_post_link()` / `next_post_link()`

توقيع مختصر: previous_post_link( $format, $link, $in_same_term, $excluded_terms, $taxonomy )
وظيفة: تطبع مباشرة روابط التنقل؛ أسهل للاستخدام السريع.

مثال

<div class="nav-links">
    <div class="nav-previous"><?php previous_post_link( '%link', '« %title' ); ?></div>
    <div class="nav-next"><?php next_post_link( '%link', '%title »' ); ?></div>
</div>

`get_adjacent_post( $in_same_term = false, $excluded_terms = '', $previous = true )`

استخدام: دالة مرنة للحصول على منشور متجاور (سابق أو التالي) مع تحكم بالتاكسونومي.

مثال

<?php
$adj = get_adjacent_post( true, '', false ); // التالي بنفس التصنيف
if ( $adj ) {
    echo get_the_title( $adj );
}
?>

`paginate_links()` / `posts_nav_link()`

الاستخدام: للتنقل في صفحات الأرشيف أو نتائج البحث؛ أقل استخدامًا في صفحة single، لكن مهم للأرشيفات.

مثال مختصر (أرشيف):

<?php
global $wp_query;
echo paginate_links( array(
    'total' => $wp_query->max_num_pages,
) );
?>

التعليقات (Comments)

`comments_template( $file = '/comments.php', $separate_comments = false )`

وظيفة: يحمّل قالب التعليقات (comments.php) ويعرض نموذج وقائمة التعليقات.
متى: في نهاية single.php لعرض قسم التعليقات.

مثال

<?php
if ( comments_open() || get_comments_number() ) {
    comments_template();
}
?>

`get_comments_number( $post_id = 0 )`

ترجع: عدد التعليقات (int) — يمكن استخدامه لعرض رقم التعليقات.

مثال

<p>التعليقات: <?php echo intval( get_comments_number() ); ?></p>

`comments_popup_link( $no_comments, $one_comment, $multiple_comments, $css_class, $none )`

وظيفة: تطبع رابطًا لقسم التعليقات مع نص معتمد على العدد (مفيد في القوائم).

مثال

<?php comments_popup_link( 'لا توجد تعليقات', 'تعليق واحد', '% تعليقات' ); ?>

sidebar, widgets و post class

`dynamic_sidebar( $index )`

وظيفة: يعرض الودجتس المسجلة للـsidebar المحدد.
متى: في الـsidebar أو منطقة جانبية في القالب.

مثال

<aside class="sidebar">
    <?php if ( is_active_sidebar( 'single-post-sidebar' ) ) {
        dynamic_sidebar( 'single-post-sidebar' );
    } ?>
</aside>

<aside class="sidebar">
    <?php if ( is_active_sidebar( 'single-post-sidebar' ) ) {
        dynamic_sidebar( 'single-post-sidebar' );
    } ?>
</aside>

PHP

`post_class( $class = '', $post_id = null )`

وظيفة: تطبع قائمة CSS classes للعنصر <article> بناءً على نوع المنشور، حالة النشر، تصنيفات، الخ. مفيدة للـstyling.
متى: داخل وسم المقال.

مثال

<article id="post-<?php the_ID(); ?>" <?php post_class( 'my-custom-class' ); ?>>
   ...
</article>

<article id="post-<?php the_ID(); ?>" <?php post_class( 'my-custom-class' ); ?>>
   ...
</article>

PHP

الـ Metadata وحقول مخصصة

`get_post_meta( $post_id, $key = '', $single = false )`

ترجع: قيمة الحقل المخصص أو مصفوفة منه.
متى: عندما تستخدم Advanced Custom Fields أو custom fields.

مثال

<?php
$price = get_post_meta( get_the_ID(), 'product_price', true );
if ( $price ) {
    echo '<p>السعر: ' . esc_html( $price ) . ' USD</p>';
}
?>

<?php
$price = get_post_meta( get_the_ID(), 'product_price', true );
if ( $price ) {
    echo '<p>السعر: ' . esc_html( $price ) . ' USD</p>';
}
?>

PHP

`edit_post_link( $link = null, $before = '', $after = '' )`

وظيفة: يطبع رابط “تحرير” يظهر فقط للمستخدمين المصرح لهم. مفيد في القوالب لتسهيل التعديل.

مثال

<?php edit_post_link( 'تعديل المقال', '<p>', '</p>' ); ?>

<?php edit_post_link( 'تعديل المقال', '<p>', '</p>' ); ?>

PHP

دوال مساعدة/أمان (هامة للاستخدام السليم)

`is_wp_error( $thing )`

وظيفة: يتحقق إن كان الشيء من نوع WP_Error. استخدمه عند التعامل مع دوال قد ترجع WP_Error (مثل get_term_link()).

مثال

<?php
$link = get_term_link( $term );
if ( is_wp_error( $link ) ) {
    // التعامل مع الخطأ
} else {
    echo esc_url( $link );
}
?>

<?php
$link = get_term_link( $term );
if ( is_wp_error( $link ) ) {
    // التعامل مع الخطأ
} else {
    echo esc_url( $link );
}
?>

PHP

التعقيم: `esc_html()`, `esc_url()`, `esc_attr()`

مهم جدًا: لا تطبع بيانات خارجية (عناوين، روابط، أسماء تصنيفات، نصوص المستخدمين) دون تعقيم.
- esc_html( $text ) للطباعة داخل HTML.
- esc_attr( $value ) لقيم السمات (attribute values).
- esc_url( $url ) للروابط.

مثال

<a href="<?php echo esc_url( get_permalink() ); ?>" title="<?php echo esc_attr( get_the_title() ); ?>">
    <?php echo esc_html( get_the_title() ); ?>
</a>

<a href="<?php echo esc_url( get_permalink() ); ?>" title="<?php echo esc_attr( get_the_title() ); ?>">
    <?php echo esc_html( get_the_title() ); ?>
</a>

PHP

خاتمة سريعة ونصيحة عملية

قدّمت لك دوالًا أساسية وشرحًا عمليًا + أمثلة جاهزة. إذا تريد، أستطيع فورًا:

صنع قالب single.php متكامل يجمع أفضل هذه الدوال مع تحسينات الأمان والهيكلية (Template Parts، Sidebar، Json-LD للـSEO)، أو
تصدير مرجع PDF لجميع الدوال مع أمثلة إضافية تناسب قوالب متعددة.

أي واحد ترغب به أطبق لك الآن (سأعرض الملف مباشرة جاهز للنسخ)?

have_posts()

the_post()

get_header( $name = null )

get_footer( $name = null )

دوال بيانات المنشور (IDs, Title, Permalink, Date)

get_the_ID()

the_ID()

get_the_title( $post = 0 )

the_title( $before = '', $after = '', $echo = true )

get_permalink( $post = 0 )

the_permalink()

get_the_date( $format = '', $post = null )

the_time( $format = '' ) / get_the_time()

التصنيفات والوسوم (Taxonomies)

get_the_terms( $post_id, $taxonomy )

get_term_link( $term, $taxonomy = '' )

the_category( $separator = ', ' )

the_tags( $before = '', $sep = ', ', $after = '' )

الصور والمرفقات (Media & Attachments)

has_post_thumbnail( $post = null )

the_post_thumbnail( $size = 'post-thumbnail', $attr = '' )

get_the_post_thumbnail( $post = null, $size = 'post-thumbnail', $attr = '' )

wp_get_attachment_image( $attachment_id, $size = 'thumbnail', $icon = false, $attr = '' )

get_children( $args = array() )

المؤلف (Author)

get_the_author_meta( $field = '', $user_id = false )

the_author_posts_link()

get_author_posts_url( $author_id )

المحتوى والـexcerpt

the_content( $more_link_text = null, $strip_teaser = false )

get_the_content( $more_link = false ) + apply_filters( 'the_content', $content )

the_excerpt() / get_the_excerpt()

روابط التنقل (Adjacent / Pagination)

get_previous_post() / get_next_post()

previous_post_link() / next_post_link()

get_adjacent_post( $in_same_term = false, $excluded_terms = '', $previous = true )

paginate_links() / posts_nav_link()

التعليقات (Comments)

comments_template( $file = '/comments.php', $separate_comments = false )

get_comments_number( $post_id = 0 )

comments_popup_link( $no_comments, $one_comment, $multiple_comments, $css_class, $none )

sidebar, widgets و post class

dynamic_sidebar( $index )

post_class( $class = '', $post_id = null )

الـ Metadata وحقول مخصصة

get_post_meta( $post_id, $key = '', $single = false )

edit_post_link( $link = null, $before = '', $after = '' )

دوال مساعدة/أمان (هامة للاستخدام السليم)

is_wp_error( $thing )

التعقيم: esc_html(), esc_url(), esc_attr()

خاتمة سريعة ونصيحة عملية

`have_posts()`

`the_post()`

`get_header( $name = null )`

`get_footer( $name = null )`

`get_the_ID()`

`the_ID()`

`get_the_title( $post = 0 )`

`the_title( $before = '', $after = '', $echo = true )`

`get_permalink( $post = 0 )`

`the_permalink()`

`get_the_date( $format = '', $post = null )`

`the_time( $format = '' )` / `get_the_time()`

`get_the_terms( $post_id, $taxonomy )`

`get_term_link( $term, $taxonomy = '' )`

`the_category( $separator = ', ' )`

`the_tags( $before = '', $sep = ', ', $after = '' )`

`has_post_thumbnail( $post = null )`

`the_post_thumbnail( $size = 'post-thumbnail', $attr = '' )`

`get_the_post_thumbnail( $post = null, $size = 'post-thumbnail', $attr = '' )`

`wp_get_attachment_image( $attachment_id, $size = 'thumbnail', $icon = false, $attr = '' )`

`get_children( $args = array() )`

`get_the_author_meta( $field = '', $user_id = false )`

`the_author_posts_link()`

`get_author_posts_url( $author_id )`

`the_content( $more_link_text = null, $strip_teaser = false )`

`get_the_content( $more_link = false )` + `apply_filters( 'the_content', $content )`

`the_excerpt()` / `get_the_excerpt()`

`get_previous_post()` / `get_next_post()`

`previous_post_link()` / `next_post_link()`

`get_adjacent_post( $in_same_term = false, $excluded_terms = '', $previous = true )`

`paginate_links()` / `posts_nav_link()`

`comments_template( $file = '/comments.php', $separate_comments = false )`

`get_comments_number( $post_id = 0 )`

`comments_popup_link( $no_comments, $one_comment, $multiple_comments, $css_class, $none )`

`dynamic_sidebar( $index )`

`post_class( $class = '', $post_id = null )`

`get_post_meta( $post_id, $key = '', $single = false )`

`edit_post_link( $link = null, $before = '', $after = '' )`

`is_wp_error( $thing )`

التعقيم: `esc_html()`, `esc_url()`, `esc_attr()`