أضف كود ووردبريس دون تعطيل موقعك

إذا سبق لك أن رأيت شاشة فارغة بعد لصق "مقتطف صغير" في WordPressأنت تعلم أن الخطر الحقيقي ليس في الكود نفسه... بل في المكان الذي تضعه فيه، وكيفية تحميله.

المشكلة / الحاجة

قد ترغب غالبًا في إضافة ميزة صغيرة دون تثبيت إضافة أخرى: رسالة في التذييل، أو برنامج تتبع، أو رمز مختصر، أو تعديل في لوحة التحكم، أو حقل في نموذج، إلخ. يقوم المبتدئون (والعديد من المستخدمين المتوسطين) بلصق هذا في functions.php من السمة النشطة، أو الأسوأ من ذلك: في ملف "أساسي". WordPressالنتيجة النموذجية: خطأ في لغة PHP، أو موقع غير قابل للوصول، أو رمز يختفي مع تغيير القالب التالي.

Ce توجيه هذا موجه لمدوني ووردبريس المبتدئين (والمحترفين المشغولين) الذين يرغبون في إضافة كود نظيف إلى ووردبريس 6.9.4 (أبريل 2026). دون أن ينكسر الموقع، دون فقدان التعديل أثناء التحديث، وبطريقة قابلة للتكرار.

في النهاية، ستعرف:

مكان لصق الكود حسب نوع التعديل (قالب فرعي، إضافة شخصية، إضافة متعددة)؛
كيفية تحميل CSS/JS "نمط ووردبريس" (enqueue)؛
التعليق طمأن إجراء في لوحة التحكم (الأذونات + قيمة عشوائية)؛
كيفية إجراء الاختبار بدون إجهاد (التجهيز، السجلات، وضع التصحيح)؛
كيفية التراجع إذا تسبب جزء من الكود في تعطيل كل شيء.

قبل كتابة أول كتلة من التعليمات البرمجية: أين يتم لصق التعليمات البرمجية؟ لتجنب إتلاف قالب موقعك، أنصح باستخدام "إضافة" لأي شيء ليس مرئيًا بحتًا. في هذا الدليل، ستلصق الكود في مو البرنامج المساعد (إضافة "لا غنى عنها"): ملف PHP يتم وضعه في wp-content/mu-plugins/يتم تحميله تلقائيًا، حتى إذا قمت بتغيير المظهر.

وظائف ووردبريس التي ستصادفها (مع الوثائق الرسمية):

add_action () : يربط وظيفة بحدث (خطاف إجراء).
add_filter () : يقوم بتعديل قيمة عبر "خطاف" التصفية.
wp_enqueue_script () et wp_enqueue_style() : يتم تحميل ملفات JS/CSS بشكل صحيح.
wp_nonce_field (), wp_verify_nonce() : يحمي نموذجًا (مضاد لهجمات تزوير الطلبات عبر المواقع).
يمكن للمستخدم الحالي : يتحقق من الأذونات.

ملخص سريع

ستقوم بإنشاء مو البرنامج المساعد "bpcab-safe-snippets" (نسخ ولصق، جاهز للاستخدام).
تضيف هذه الإضافة (mu-plugin) صفحة "Safe Snippets" في لوحة التحكم، مع نموذج كود قابل للتفعيل.
يظهر الطريقة الصحيحة لتحميل ملفات CSS/JS (إدراج بقائمة الانتظار), وإضافة زر في لوحة التحكم.
يتضمن ذلك إجراءات وقائية: الأذونات، والرقم العشوائي، والسجلات، والتعطيل السريع في حالة حدوث عطل.
تغادر ومعك طريقة: مرحلة الاختبار ← إضافة mu ← خطافات ← اختبارات ← نشر.

متى يستخدم هذا الحل

تريد إضافة وظائف "الموقع" (بشكل مستقل عن القالب): رمز مختصر، إعادة توجيه، تتبع، تنظيف لوحة التحكم، واجهة برمجة تطبيقات مصغرة، إضافة دور/صلاحية.
أنت تقوم بتغيير قالب موقعك بانتظام (أو تستخدم أداة إنشاء الصفحات) ولا تريد أن تفقد تغييراتك.
أنت بحاجة إلى مكان مستقر لتخزين التعليمات البرمجية التي يمكن التحكم في إصداراتها (Git) واختبارها.
إذا كنت تدير مواقع متعددة: فإن بنية mu-plugin توفر عليك عناء القيام بأي عمل في functions.php.

متى لا يجب استخدام هذا الحل

تغييرات طفيفة، بصرية بحتة (CSS): يُفضّل استخدام ملف CSS إضافي (المظهر ← تخصيص) أو ملف CSS في قالب فرعي. يمكن لمكوّن إضافي تحميل CSS، لكنه ليس الحل الأمثل دائمًا.
الميزات التي تغطيها بالفعل إضافة موثوقة تحسين محركات البحث، والتخزين المؤقت، والأمان، والنماذج. إن إعادة اختراع العجلة طريقة جيدة لخلق ديون تقنية.
رمز "قابل للتصرف" والتي لن تكون مسؤولاً عن صيانتها: من الأفضل استخدام إضافة مقتطفات مع واجهة وإصدارات، أو إضافة صغيرة نظيفة.
ليس لديك أي تجهيزات في هذه الحالة، ابدأ بذلك. لقد رأيتُ كثيراً مواقع التجارة الإلكترونية تتعطل بسبب غياب الفاصلة المنقوطة في ملف functions.php.

المتطلبات الأساسية / قبل البدء

الإصدارات والبيئة

WordPress : 6.9.4 أو أحدث.
PHP : 8.1 كحد أدنى موصى به (8.2/8.3 غالباً ما يكون أفضل إذا كان مزود الاستضافة الخاص بك يدعمه).
الوصول إلى الملفات: عبر SFTP/SSH أو مدير ملفات المضيف (تجنب محرر الملفات المدمج في بيئة الإنتاج).

النسخ الاحتياطي والأمان

اصنع نسخة احتياطية كاملة (الملفات + قاعدة البيانات) قبل أي تعديل. إذا كان لديك إضافة نسخ احتياطي، فتأكد من أن عملية الاستعادة تعمل.
لا تقم بالتعديل أبدا ملفات "الأساسية" في ووردبريس (wp-includes، wp-admin). أي تعديل عليها سيؤدي إلى استبدالها وقد يُسبب ثغرة أمنية.
من الأفضل العمل على انطلاق (استنساخ) ثم نشره.

أدوات مفيدة

قم بتمكين تصحيح الأخطاء بشكل صحيح (انظر أدناه).
محرر أكواد يكتشف الأخطاء: VS Code.
عميل SFTP (FileZilla) أو عميل SSH.

تفعيل التسجيل (موصى به في بيئة الاختبار)

في الفسفور الابيض بين config.php ليمكنك تفعيل تسجيل الأخطاء في PHP/WordPress. تجنب عرض الأخطاء على الشاشة في المواقع الإلكترونية العامة.

/**
 * Debug WordPress (idéalement sur staging).
 * Ne laissez pas WP_DEBUG_DISPLAY à true en production.
 */
define( 'WP_DEBUG', true );
define( 'WP_DEBUG_LOG', true );
define( 'WP_DEBUG_DISPLAY', false );

ستدخل الأخطاء في wp-content/debug.log (إذا سمح الخادم بذلك). المستند: تصحيح أخطاء ووردبريس.

النهج الساذج (ولماذا يجب تجنبه)

السيناريو المعتاد: تجد مقتطفًا في منتدى، ثم تلصقه في functions.php عند تحديث الصفحة من القالب النشط، تظهر شاشة بيضاء. أو قد يعمل القالب ثم يختفي عند تحديث القالب أو التبديل إلى Divi/Avada.

مثال بسيط: تم لصق الكود في الملف الخطأ + رمز خروج غير مُهَرَّب

إليك مثال واقعي (وخطير): عرض معلمة عنوان URL في التذييل، دون تنظيفها.

<?php
// Mauvaise idée : collé dans le footer.php ou functions.php du thème parent,
// et affiche directement une donnée utilisateur.
add_action( 'wp_footer', function () {
	echo '<div class="promo">' . $_GET['promo'] . '</div>';
} );

المشاكل:

أمن : XSS (حقن البرامج النصية) عبر $_GET['promo'].
الدورية إذا كان موجودًا في القالب الرئيسي، فسيؤدي التحديث إلى استبدال كل شيء.
مساعدة إذا ارتكبت خطأ في بناء الجملة، فقد يصبح الموقع غير قابل للوصول.
قابلية تغيير المظهر = فقدان الكود.

فخ ساذج آخر: تحميل ملفات JS/CSS "المبرمجة بشكل ثابت"

<?php
// Mauvaise idée : imprime un script sans passer par wp_enqueue_script().
add_action( 'wp_head', function () {
	echo '<script src="/wp-content/themes/mon-theme/js/custom.js"></script>';
} );

تكمن المشكلة في إدارة التبعيات، والتخزين المؤقت، وترتيب التحميل، بالإضافة إلى قيام بعض أدوات البناء (أو إضافات التحسين) بنقل/تصغير الملفات. يوفر ووردبريس نظامًا مصممًا خصيصًا للتعامل مع هذه المشكلة. إدراج بقائمة الانتظار.

النهج الصحيح - دليل خطوة بخطوة

الاستراتيجية الأكثر "مقاومة للكسر" للمبتدئين: إضافة MU بسيط، مع روابط واضحة، ومثال على ميزة قابلة للتفعيل.

الخطوة 1 - إنشاء مجلد mu-plugins

الاتصال عبر بروتوكول SFTP/SSH.
اذهب wp-content/.
أنشئ مجلدًا mu-plugins إذا لم يكن موجوداً.

يتم تحميل إضافات mu تلقائيًا بواسطة ووردبريس. doc: المكونات الإضافية التي يجب استخدامها.

الخطوة 2 - إنشاء ملف mu-plugin

أنشئ هذا الملف: wp-content/mu-plugins/bpcab-safe-snippets.php

سيحتوي هذا الملف على ما يلي:

أضف صفحة إدارية (الأدوات → مقتطفات آمنة)؛
حفظ خيار (تمكين/تعطيل جزء من التعليمات البرمجية)؛
أضف رسالة إلى التذييل إذا تم تمكين المقتطف؛
قم بتحميل ملف CSS صغير بشكل صحيح؛
استخدام الأذونات + nonce + التنظيف/الهروب.

الخطوة 3 - فهم "الخطافات" (الإجراءات والفلاتر)

Un صنارة صيد هو خطاف في ووردبريس. يوجد نوعان منه:

اكشن : تقوم بتنفيذ التعليمات البرمجية في وقت محدد (على سبيل المثال admin_menu, wp_footer). وظيفة : add_action ().
فلتر : تستلم قيمة، تقوم بتعديلها، ثم تقوم بإرجاعها (على سبيل المثال) the_content). وظيفة : add_filter ().

يُعدّ الخلط بين "الفعل والتصفية" خلطًا كلاسيكيًا. إذا نسيتَ عائد أعلى إذا استخدمتَ مُرشِّحًا، فإنك تُعطِّل العرض. وإذا حاولتَ استخدام صدى داخل مُرشِّح، فإنك تُنشئ مُخرجات في المكان الخطأ.

الخطوة 4 - إضافة صفحة إدارية (مع الصلاحيات)

ستستخدم add_management_page() لوضع الصفحة في "الأدوات". نحن نحمي الوصول إليها باستخدام يمكن للمستخدم الحالي.

الخطوة 5 - حماية التسجيل (nonce + التطهير)

عند حفظ نموذج بصفتك مسؤولاً، هناك حد أدنى من الحماية:

إذن هل للمستخدم الحق؟
مناسبة حالية هل يأتي النموذج من موقعكم الإلكتروني (لمكافحة هجمات تزوير الطلبات عبر المواقع)؟

بعد ذلك، تقوم بتنظيف البيانات الواردة (التعقيم) وتقوم بإلغاء تعريف مخرجات HTML (الهروب).

الخطوة 6 - تحميل ملفات CSS/JS بشكل صحيح (enqueue)

بدلاً من طباعة بطاقة <script>تمر به wp_enqueue_style() / wp_enqueue_script ()هذا ما تتوقعه إضافات التخزين المؤقت وأدوات البناء.

الرمز الكامل

أين ألصق هذا الكود؟ في wp-content/mu-plugins/bpcab-safe-snippets.php (أنشئ الملف إذا لزم الأمر). انسخ والصق كما هو.

<?php
/**
 * Plugin Name: BPCAB - Snippets sûrs (mu-plugin)
 * Description: Ajoute une page d'admin pour activer un snippet d'exemple sans casser le site. WordPress 6.9.4+ / PHP 8.1+.
 * Author: BPCAB
 * Version: 1.0.0
 *
 * Ce fichier doit être placé dans : wp-content/mu-plugins/bpcab-safe-snippets.php
 */

declare( strict_types=1 );

if ( ! defined( 'ABSPATH' ) ) {
	exit;
}

/**
 * Clé d'option stockée en base.
 */
const BPCAB_SAFE_SNIPPETS_OPTION = 'bpcab_safe_snippets_settings';

/**
 * Retourne les réglages actuels (avec valeurs par défaut).
 *
 * @return array{footer_notice_enabled: bool, footer_notice_text: string}
 */
function bpcab_safe_snippets_get_settings(): array {
	$defaults = array(
		'footer_notice_enabled' => false,
		'footer_notice_text'    => 'Merci de votre visite !',
	);

	$settings = get_option( BPCAB_SAFE_SNIPPETS_OPTION, array() );

	if ( ! is_array( $settings ) ) {
		return $defaults;
	}

	// Fusionne en garantissant les clés.
	return array_merge( $defaults, $settings );
}

/**
 * Enregistre le menu dans Outils → Snippets sûrs.
 */
add_action( 'admin_menu', function (): void {
	add_management_page(
		'Snippets sûrs',
		'Snippets sûrs',
		'manage_options',
		'bpcab-safe-snippets',
		'bpcab_safe_snippets_render_admin_page'
	);
} );

/**
 * Enregistre le CSS de l'admin pour cette page.
 */
add_action( 'admin_enqueue_scripts', function ( string $hook_suffix ): void {
	// Le hook_suffix ressemble à : tools_page_bpcab-safe-snippets
	if ( $hook_suffix !== 'tools_page_bpcab-safe-snippets' ) {
		return;
	}

	// Petit CSS inline : pratique pour un mu-plugin (pas de fichier à gérer).
	$css = '
		.bpcab-box{background:#fff;border:1px solid #dcdcde;padding:16px;border-radius:8px;max-width:860px}
		.bpcab-row{margin:12px 0}
		.bpcab-help{color:#646970}
		.bpcab-code{background:#f6f7f7;border:1px solid #dcdcde;padding:12px;border-radius:6px;overflow:auto}
	';
	wp_register_style( 'bpcab-safe-snippets-admin', false );
	wp_enqueue_style( 'bpcab-safe-snippets-admin' );
	wp_add_inline_style( 'bpcab-safe-snippets-admin', $css );
} );

/**
 * Affiche la page d'administration.
 */
function bpcab_safe_snippets_render_admin_page(): void {
	if ( ! current_user_can( 'manage_options' ) ) {
		wp_die( esc_html__( 'Accès refusé.', 'default' ) );
	}

	$settings = bpcab_safe_snippets_get_settings();

	// Message de succès/erreur simple via paramètre d'URL (échappé à l'affichage).
	$updated = isset( $_GET['bpcab_updated'] ) ? sanitize_text_field( wp_unslash( $_GET['bpcab_updated'] ) ) : '';
	?>
	<div class="wrap">
		<h1>Snippets sûrs</h1>

		<?php if ( $updated === '1' ) : ?>
			<div class="notice notice-success is-dismissible"><p>Réglages enregistrés.</p></div>
		<?php endif; ?>

		<div class="bpcab-box">
			<p>
				Cette page sert de “bac à sable” : vous activez un snippet simple, et vous voyez la méthode propre
				(hooks, permissions, nonce, sanitization, escaping).
			</p>

			<hr />

			<form method="post" action="<?php echo esc_url( admin_url( 'admin-post.php' ) ); ?>">
				<?php
				// Nonce = jeton anti-CSRF.
				wp_nonce_field( 'bpcab_safe_snippets_save', 'bpcab_safe_snippets_nonce' );
				?>

				<input type="hidden" name="action" value="bpcab_safe_snippets_save" />

				<div class="bpcab-row">
					<label>
						<input type="checkbox" name="footer_notice_enabled" value="1" <?php checked( (bool) $settings['footer_notice_enabled'] ); ?> />
						<strong>Activer le message en pied de page</strong>
					</label>
					<p class="bpcab-help">Le message apparaîtra côté visiteurs via le hook <code>wp_footer</code>.</p>
				</div>

				<div class="bpcab-row">
					<label for="footer_notice_text"><strong>Texte du message</strong></label><br />
					<input
						type="text"
						id="footer_notice_text"
						name="footer_notice_text"
						value="<?php echo esc_attr( (string) $settings['footer_notice_text'] ); ?>"
						class="regular-text"
						maxlength="120"
					/>
					<p class="bpcab-help">Astuce : gardez-le court. Ce champ est nettoyé et échappé.</p>
				</div>

				<p>
					<button type="submit" class="button button-primary">Enregistrer</button>
				</p>
			</form>

			<hr />

			<h2>À quoi ressemble le snippet côté code ?</h2>
			<p class="bpcab-help">
				Vous n’avez rien à copier ici : c’est juste pour comprendre. Le snippet réel est plus bas dans ce mu-plugin.
			</p>
			<pre class="bpcab-code"><code>add_action( 'wp_footer', function () {
  // ... affiche un message si l'option est activée
} );</code></pre>
		</div>
	</div>
	<?php
}

/**
 * Traite l'enregistrement du formulaire (admin-post.php).
 *
 * Hook WordPress : admin_post_{action}
 * Doc : https://developer.wordpress.org/reference/hooks/admin_post_action/
 */
add_action( 'admin_post_bpcab_safe_snippets_save', function (): void {
	if ( ! current_user_can( 'manage_options' ) ) {
		wp_die( esc_html__( 'Accès refusé.', 'default' ) );
	}

	// Vérifie le nonce.
	$nonce = isset( $_POST['bpcab_safe_snippets_nonce'] ) ? sanitize_text_field( wp_unslash( $_POST['bpcab_safe_snippets_nonce'] ) ) : '';
	if ( ! wp_verify_nonce( $nonce, 'bpcab_safe_snippets_save' ) ) {
		wp_die( esc_html__( 'Nonce invalide. Rafraîchissez la page et réessayez.', 'default' ) );
	}

	// Sanitization (nettoyage) des entrées.
	$enabled = isset( $_POST['footer_notice_enabled'] ) && (string) $_POST['footer_notice_enabled'] === '1';

	$text_raw = isset( $_POST['footer_notice_text'] ) ? wp_unslash( $_POST['footer_notice_text'] ) : '';
	// Nettoyage conservateur : une simple ligne de texte.
	$text = sanitize_text_field( (string) $text_raw );
	$text = mb_substr( $text, 0, 120 );

	$settings = array(
		'footer_notice_enabled' => (bool) $enabled,
		'footer_notice_text'    => $text !== '' ? $text : 'Merci de votre visite !',
	);

	update_option( BPCAB_SAFE_SNIPPETS_OPTION, $settings, false );

	// Redirection post/redirect/get pour éviter la double soumission.
	wp_safe_redirect( add_query_arg( 'bpcab_updated', '1', admin_url( 'tools.php?page=bpcab-safe-snippets' ) ) );
	exit;
} );

/**
 * Snippet "front" : affiche un message en pied de page si activé.
 *
 * Hook : wp_footer
 * Doc : https://developer.wordpress.org/reference/hooks/wp_footer/
 */
add_action( 'wp_footer', function (): void {
	$settings = bpcab_safe_snippets_get_settings();

	if ( empty( $settings['footer_notice_enabled'] ) ) {
		return;
	}

	// Escaping : on affiche du texte utilisateur en HTML.
	$text = isset( $settings['footer_notice_text'] ) ? (string) $settings['footer_notice_text'] : '';

	echo '<div class="bpcab-footer-notice" style="text-align:center; padding:14px 10px; font-size:14px; opacity:.85">';
	echo esc_html( $text );
	echo '</div>';
}, 20 );

/**
 * Variante propre : charger un CSS front via enqueue au lieu d'un style inline.
 * Ici on reste minimaliste avec un CSS inline (pas de fichier) pour le guide.
 */
add_action( 'wp_enqueue_scripts', function (): void {
	$settings = bpcab_safe_snippets_get_settings();
	if ( empty( $settings['footer_notice_enabled'] ) ) {
		return;
	}

	$css = '.bpcab-footer-notice{background:#f6f7f7;border-top:1px solid #e5e5e5}';
	wp_register_style( 'bpcab-safe-snippets-front', false );
	wp_enqueue_style( 'bpcab-safe-snippets-front' );
	wp_add_inline_style( 'bpcab-safe-snippets-front', $css );
} );

شرح الكود

اختيار الملحق المناسب لـ mu (ولماذا يمنع الكوارث)

يتم تحميل إضافة mu تلقائيًا، دون ظهور شاشة "الإضافات". وهذا له نتيجتان:

مصلحة لن يختفي الكود الخاص بك إذا قمت بتغيير السمات، ولن يقوم أحد بتعطيله "عن طريق الخطأ".
صعب إذا أدخلت خطأً فادحاً فيه، فسيتم تشغيله في كل عملية تحميل. ومن هنا تأتي أهمية التخزين المؤقت وتسجيل الأحداث.

بحسب تجربتي، فإن إضافة mu-plugin مثالية لـ "الوظائف المصغرة" المستقرة: عمليات إعادة التوجيه، ومقتطفات الأداء، والتعديلات الإدارية الصغيرة، وما إلى ذلك.

خيارات: حفظ الإعدادات دون الحاجة إلى إعادة اختراع العجلة

نقوم بتخزين الإعدادات باستخدام get_option() / update_option() (خيارات واجهة برمجة التطبيقات). وثيقة: خيارات واجهة برمجة التطبيقات.

يستخدم الكود دالة bpcab_safe_snippets_get_settings() وهذا يوفر قيمًا افتراضية. وهذا يتجنب ظهور إشعارات PHP مثل "فهرس غير معرف" عندما لا يكون الخيار موجودًا بعد.

المسؤول: القائمة + الصفحة + النموذج

الخطاف admin_menu يُستخدم هذا لتعريف الصفحات في لوحة التحكم. هنا نستخدم add_management_page() (القائمة "الأدوات").

يتم إرسال النموذج إلى admin-post.php مع حقل مخفي actionثم يقوم ووردبريس بتشغيل الإجراء admin_post_{action}دكتور: admin_post_{action}.

الأمان: الأذونات + قيمة عشوائية (nonce)

هناك سطران فقط يميزان بين "إنه يعمل" و "إنه عرضة للهجوم":

current_user_can( 'manage_options' ) لا يُسمح بالتسجيل إلا للأشخاص الذين لديهم صلاحيات إدارية.
wp_verify_nonce() يمنع هذا الخيار موقعًا خارجيًا من إجبار متصفحك على إرسال النموذج (CSRF).

الطبيب البابوي: الراهبات.

التعقيم مقابل الهروب (الخلط الأكثر شيوعًا)

التعقيم (الإدخال): تقوم بتنظيف البيانات الواردة من النموذج/عنوان URL. مثال: sanitize_text_field().
الهروب (خروج): قبل العرض مباشرةً، يتم استخدام رمز الهروب لسياق HTML. مثال: esc_html(), esc_attr(), esc_url().

سترى كليهما في الكود: نقوم بالتنظيف عند التسجيل، ثم نهرب عند العرض (شبكة أمان مزدوجة).

استطلاع رأي: لماذا يصر ووردبريس على ذلك بشدة؟

الخطاف wp_enqueue_scripts يُعد هذا المكان القياسي لتعريف CSS/JS في واجهة المستخدم. وهذا يسمح بما يلي:

لتجنب التكرار؛
احترام ترتيب التحميل؛
للسماح لمكونات التحسين الإضافية بتجميع/تصغير الملفات؛
ليكون متوافقًا مع القوالب/أدوات البناء التي تنقل الكتل.

المستندات: بما في ذلك CSS و JavaScript.

المتغيرات وحالات الاستخدام

الخيار 1 - ضع الكود في إضافة "كلاسيكية" (والتي يمكن تعطيلها)

إذا كنت تفضل تعطيله من لوحة التحكم (الإضافات)، فأنشئ إضافة قياسية في wp-content/plugins/غالباً ما يكون الأمر أكثر راحة خلال المرحلة التجريبية.

بنية بسيطة:

wp-content/plugins/bpcab-safe-snippets/bpcab-safe-snippets.php

قد يكون الكود متطابقًا. الفرق الوحيد هو أنك تقوم بتفعيله/إلغاء تفعيله عبر لوحة التحكم.

الخيار الثاني — قالب فرعي للتعديلات المتعلقة بالتصميم

إذا كان الكود الخاص بك يعتمد على المظهر (على سبيل المثال، إضافة منطقة عناصر واجهة المستخدم، أو تعديل قالب، أو نمط معين)، فاستخدم موضوع الطفلوإلا، فسوف تخلط بين "الوظائف" و "العرض".

وثيقة ذات طابع خاص بالأطفال: ثيمات الطفل.

الخيار 3 - إضافة رمز مختصر نظيف (مثال كامل)

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

أضف هذا إلى نفس إضافة mu-plugin (أو إضافتك المخصصة). يُستخدم الرمز المختصر كـ [bpcab_notice text="..."].

add_shortcode( 'bpcab_notice', function ( $atts ): string {
	$atts = shortcode_atts(
		array(
			'text' => 'Contenu par défaut',
		),
		(array) $atts,
		'bpcab_notice'
	);

	// Nettoyage et échappement.
	$text = sanitize_text_field( (string) $atts['text'] );

	// Retour (un shortcode doit retourner, pas echo).
	return '<div class="bpcab-notice" style="border:1px solid #dcdcde;padding:12px;border-radius:8px">'
		. esc_html( $text )
		. '</div>';
} );

دكتور: رموز API المختصرة.

التوافق مع Divi 5 / Elementor / Avada

ديفي 5

يعمل Divi 5 بشكل جيد للغاية مع:

الرموز المختصرة (على سبيل المثال) [bpcab_notice]) عبر وحدة "الرمز" أو "النص"؛
خطافات ووردبريس القياسية (wp_footer, wp_enqueue_scripts).

مأزق رأيته من قبل: بعض إعدادات الأداء/التصغير (Divi أو إضافات الطرف الثالث) تؤخر تحميل جافا سكريبت. إدراج بقائمة الانتظارلديك فرصة أفضل في أن يبقى كل شيء مستقراً.

Elementor

يقبل Elementor ما يلي:

رمز مختصر في أداة "الرمز المختصر"؛
تم تحميل ملف CSS عبر wp_enqueue_scripts ;
تعديلات التذييل عبر wp_footer (شريطة أن يتطلب الموضوع ذلك) wp_footer()(وهذا هو الحال بالنسبة للسمات المتوافقة).

إذا لم تجد رسالتك في التذييل، فتأكد من أن قالب موقعك لم "ينساها". wp_footer()يحدث هذا في القوالب المخصصة للغاية.

أفادا (منشئ الاندماج)

يتوافق Avada بشكل عام مع خطافات WordPress والرموز المختصرة. لإدراج رمز مختصر:

استخدم عنصر "كتلة التعليمات البرمجية" أو "كتلة النص" حسب التكوين الخاص بك؛
أو ضع الرمز المختصر في محتوى الصفحة.

خطأ شائع: التخزين المؤقت المفرط (أفادا + إضافة التخزين المؤقت). بعد تفعيل جزء من التعليمات البرمجية، قم بمسحه.

مخبأ أفادا،
ذاكرة التخزين المؤقت للملحق (إن وجدت)،
وذاكرة التخزين المؤقت للمتصفح.

فحوصات ما بعد التثبيت

في لوحة التحكم: انتقل إلى الأدوات ← مقتطفات آمنةيجب أن تظهر الصفحة الآن.
حدد خيار "تمكين الرسالة"، ثم احفظ التغييرات. ستظهر لك رسالة "تم حفظ الإعدادات".
في واجهة المستخدم: قم بتحديث صفحة عامة. ستظهر الرسالة في الأسفل.
إذا كان لديك ذاكرة تخزين مؤقتة: قم بمسحها واختبر في وضع التصفح الخاص.
بحث wp-content/debug.log (في بيئة الاختبار): يجب ألا تظهر أي أخطاء في لغة PHP.

مخطط التشخيص السريع

عرض	السبب المحتمل	التحقق	الحلول
لا تظهر صفحة "المقتطفات الآمنة".	الملف في المكان الخطأ	هل الملف موجود في الموقع الصحيح؟ `wp-content/mu-plugins/` ?	يتحرك `bpcab-safe-snippets.php` في `mu-plugins`
شاشة بيضاء / خطأ 500	خطأ في لغة PHP (فاصلة منقوطة، قوسان، حرف غير مرئي)	تشاور `debug.log` أو سجلات الخادم	قم بتصحيح السطر المشار إليه، أو احذف الملف لاستعادة الموقع.
رسالة التذييل مفقودة	الخيار غير مفعل أو ذاكرة التخزين المؤقت	هل تم تحديد الخيار؟ هل تم مسح ذاكرة التخزين المؤقت؟	قم بتفعيل الخيار، وامسح ذاكرة التخزين المؤقت، ثم اختبر في الوضع الخاص.
"رقم عشوائي غير صالح"	تم فتح الصفحة لفترة طويلة، ذاكرة التخزين المؤقت للمسؤول، إضافة الأمان	قم بتحديث الصفحة وحاول مرة أخرى.	قم بتحديث الصفحة، وقم بتعطيل الحماية المفرطة مؤقتًا
لا ينطبق CSS	تحسين يزيل CSS المضمن	قم بتعطيل خاصية التصغير/الدمج وأعد الاختبار.	قم بالتبديل إلى ملف CSS مناسب وقم بإضافته إلى قائمة الانتظار بشكل صحيح.

إذا لم ينجح الأمر

إجراءات استكشاف الأخطاء وإصلاحها (بالترتيب)

نفس في 90% من الحالات، يكون السبب هو مسار ملف أو خطأ في بناء الجملة.
تحقق من الموقع : wp-content/mu-plugins/bpcab-safe-snippets.phpليس في pluginsليس له علاقة بالموضوع.
تحقق من PHP هل يعمل خادمك بنظام PHP 8.1 أو أحدث؟ (الأدوات ← صحة الموقع، أو لوحة تحكم الاستضافة). قد يتسبب استخدام إصدار أقدم في حدوث أخطاء في التعليمات البرمجية الحديثة. راجع توثيق PHP: الإصدارات المعتمدة.
تفعيل التسجيل (في مرحلة الإخراج) واقرأ wp-content/debug.log.
قم بتعطيل ذاكرة التخزين المؤقت مؤقتًا (ذاكرة التخزين المؤقت للملحقات، ذاكرة التخزين المؤقت للخادم، شبكة توصيل المحتوى) ثم أعد الاختبار.
جربه باستخدام سمة افتراضية (إن أمكن في بيئة الاختبار) لاستبعاد سمة لا يتم تشغيلها wp_footer().
النزاعات قم بتعطيل إضافات "القصاصات" والأمان والتحسين مؤقتًا. لقد واجهتُ في كثير من الأحيان إضافات تقوم بتصفية البيانات بشكل مفرط. admin-post.php.

إذا كان الموقع معطلاً (خطأ فادح) ولم يعد بإمكانك الوصول إلى لوحة التحكم الإدارية

الاتصال عبر بروتوكول نقل الملفات الآمن (SFTP).
أعد تسمية الملف: bpcab-safe-snippets.php → bpcab-safe-snippets.php.off
أعد تحميل الموقع: لن يقوم ووردبريس بتحميل هذا الملحق mu-plugin بعد الآن.
ثم قم بتصحيح الخطأ بذهن صافٍ (باستخدام السجلات).

الأخطاء الشائعة والمزالق

خطأ	سبب	الحلول
انسخ الكود إلى القالب الرئيسي	يتم تطبيق التغيير عند تحديث القالب.	استخدم قالبًا فرعيًا أو، من أجل الوظائف، إضافة/إضافة متعددة
ألصق كود PHP في محرر "CSS إضافي"	الارتباك بين اللغات	يتم وضع ملف PHP في ملف `.php` (إضافة/قالب)، ملف CSS `.css`
نسيان الفاصلة المنقوطة `;`	خطأ في بناء جملة PHP	اقرأ السجل، وصحح السطر، واستخدم محرر نصوص مزودًا بخاصية تمييز الصيغة/التشخيص.
استخدام خطاف غير مناسب	مثال: تحميل برنامج نصي على `init` بدلا من `wp_enqueue_scripts`	استخدم خطافات قياسية: `wp_enqueue_scripts`, `admin_enqueue_scripts`, `wp_footer`
إجراء وتصفية مربكان	يجب أن تُرجع دالة التصفية قيمة.	مع `add_filter`، يفعل `return`. مع `add_action`، تقوم بالتنفيذ دون إرجاع
لا يعمل الكود بسبب ذاكرة التخزين المؤقت.	إضافة التخزين المؤقت/شبكة توصيل المحتوى/المتصفح	امسح جميع ذاكرات التخزين المؤقت، واختبر في وضع التصفح الخاص، وعطّل خاصية تصغير الملفات مؤقتًا.
الاختبار مباشرة في بيئة الإنتاج	لا يوجد تجهيز، ولا تراجع	قم بإنشاء بيئة تجريبية، أو على الأقل نسخة احتياطية قابلة للاستعادة مع إمكانية الوصول عبر بروتوكول SFTP.
كود من برنامج تعليمي قديم وغير متوافق	وظائف مهملة، أنماط قديمة، لغة PHP قديمة جدًا	راجع وثائق WordPress 6.9+ الرسمية، وقم بتكييفها، وقم بتحديث PHP.
"تم إرسال الترويسات بالفعل"	المسافات/النص قبل `<?php` أو الخروج قبل إعادة التوجيه	قم بإزالة جميع قوائم المواد/المسافات، وتجنب `echo` قبل `wp_safe_redirect()`

نصائح السلامة والأداء والصيانة

السلامة: الحد الأدنى من ردود أفعالك

أبدا عرض بيانات المستخدم بدون استخدام علامات الهروب (esc_html, esc_attr, esc_url).
لجميع نماذج الإدارة: إذن + رقم عشوائي.
تجنب تخزين البيانات السرية (مفاتيح واجهة برمجة التطبيقات) كنص عادي في قاعدة البيانات إذا كان بإمكانك استخدام متغيرات البيئة من جانب الخادم.

الأداء: تجنب استخدام الخطافات "مبكراً جداً" والطلبات غير الضرورية

تجنب إرسال طلبات ثقيلة في كل صفحة إذا كان بإمكانك الحد منها (على سبيل المثال، فقط إذا تم تمكين الخيار).
تجنب wp_head / wp_footer لتحميل البرامج النصية "يدويًا"، استخدم enqueue.
إذا أضفت رمزًا شرطيًا، فقم بإجراء عمليات إرجاع سريعة (return;) كما في المثال.

الصيانة: اجعل مقتطفاتك "مقبولة"

قم بإضافة بادئة إلى وظائفك (على سبيل المثال: bpcab_...) لتجنب التعارض مع المكونات الإضافية الأخرى.
التعليق باللغة الفرنسية، وخاصة الأسباب ("لماذا")، وليس فقط "ماذا".
قم بإصدار نسخة من برنامج mu-plugin الخاص بك (Git) إذا كنت تقوم بتعديل الكود بشكل متكرر.
احتفظ بسجل للتغييرات: التاريخ، والسبب، ورابط التذكرة.

الموارد

الأسئلة الشائعة

هل يمكنني وضع كل شيء في ملف functions.php؟

من الناحية التقنية، نعم، ولكنك تدفع ثمن ذلك بالمخاطر: خسارة عند تغيير القوالب، وأخطاء يصعب تحديدها، وإغراء تعديل القالب الأصلي. احتفظ بـ functions.php لإجراء تعديلات متعلقة بالموضوع (ويفضل أن يكون ذلك في موضوع فرعي).

إضافة Mu أم إضافة عادية: أيهما أختار؟

استخدم إضافة Mu إذا كنت ترغب في تحميلها دائمًا وعدم إمكانية تعطيلها من لوحة التحكم. استخدم إضافة عادية إذا كنت في مرحلة الاختبار، أو إذا كان العميل بحاجة إلى تعطيلها بسهولة.

تظهر لي شاشة بيضاء، ماذا أفعل أولاً؟

أعد تسمية ملف mu-plugin إلى SFTP لتعطيله، ثم اقرأ السجل (wp-content/debug.log أو سجلات الخادم). في 80% من الحالات: خطأ في بناء الجملة أو قوس معقوف مفقود.

لماذا لا يتم تحميل ملفات CSS/JS الخاصة بي مع أداة البناء؟

غالباً ما يكون هذا بسبب خطأ في الربط أو تحميل ثابت. استخدم wp_enqueue_scripts / admin_enqueue_scriptsبعد ذلك، قم بمسح ذاكرة التخزين المؤقت (ذاكرة التخزين المؤقت للمنشئ + ذاكرة التخزين المؤقت للمكون الإضافي + شبكة توصيل المحتوى).

هل يجب عليّ استخدام إضافة مقتطفات التعليمات البرمجية (مثل "مقتطفات التعليمات البرمجية")؟

قد يكون ذلك مفيدًا، خاصةً للتفعيل/التعطيل السريع. لكنني رأيت مواقع تتعطل بعد تحديث إضافة مقتطفات برمجية أو تعارض. بالنسبة للتعليمات البرمجية "الحساسة"، أفضل استخدام إضافة مخصصة ذات إصدارات، أو إضافة متعددة.

كيف يمكننا منع تنفيذ جزء من التعليمات البرمجية مبكراً جداً؟

قم بتثبيته على الخطاف الصحيح. مثال: لا تقم بتحميل البرامج النصية على init، استعمال wp_enqueue_scriptsلا تفترض أن كل شيء متاح قبل plugins_loaded.

كيف أعرف أي خطاف أستخدم؟

ابدأ بالوثائق الرسمية (مرجع الخطافات)، ثم ابحث في شفرة مصدر ووردبريس (GitHub) لمعرفة مكان تفعيل الخطاف. عند الشك، أبحث في wordpress-develop على اسم الخطاف.

هل هذا الدليل متوافق مع ووردبريس 6.9.4 و PHP 8.1؟

نعم: يتجنب الكود استخدام واجهات برمجة التطبيقات القديمة، ويستخدم وظائف قياسية، ويظل متوافقًا مع PHP 8.1 والإصدارات الأحدث. إذا كان خادمك أقدم من ذلك، فقم بتحديث إصدار PHP أولًا.

هل يمكنني إضافة عدة مقاطع برمجية إلى نفس المكون الإضافي mu-plugin؟

نعم، ولكن حافظ على بنية واضحة: خيار واحد لكل ميزة، ووظائف مسبوقة ببادئات، وكتل منفصلة بوضوح. إذا ازداد حجمه، فانتقل إلى إضافة مناسبة ذات ملفات منفصلة.

لماذا تستخدم ملف admin-post.php بدلاً من واجهة برمجة تطبيقات الإعدادات (Settings API)؟

دليل للمبتدئين، admin-post.php يوضح هذا بوضوح ثنائية "الإذن + القيمة العشوائية + التنظيف". تُعد واجهة برمجة تطبيقات الإعدادات ممتازة لصفحات الإعدادات الشاملة، لكنها تضيف طبقة إضافية من المفاهيم.

هل يمكنني تحقيق التوازن بين تكلفة موقعي الإلكتروني واستخدام إضافة mu؟

نعم، في حال حدوث خطأ فادح. الفرق هو أن لديك إجراءً بسيطًا جدًا للتراجع: إعادة تسمية الملف أو حذفه عبر بروتوكول نقل الملفات الآمن (SFTP). وبذلك تتجنب تحديثات القوالب التي تستبدل التعليمات البرمجية الخاصة بك.