دليل الاستخدام

الشروع السريع

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

في البداية، يتوجب عليك تنزيل نسخة من عركابتشا وتحميل المجلد بعد فك ضغطه إلى خادم الويب (web server) الخاص بك. في هذا المثال، سنفترض بأن ملفات عركابتشا محملة على مجلد باسم ArCaptcha في جذر دليل الويب (the root of the web directory) (على سبيل المثال وليس الحصر: www.yoursite.com/ArCaptcha/). بعدها سنضيف صورة الكابتشا إلى النموذج مع حقل نصي بجانبها ليتم استخدامه لإدخال رمز التحقق.

أضف السطر التالي في المكان المخصّص (غالباً في نهاية النموذج) لعرض صورة الكابتشا:

	
					1
				
					<img 
					id="captcha" 
					src="/ArCaptcha/GetArCaptcha.php" 
					alt="ArCaptcha" 
					/>

ثم أضف السطرين التاليين لعرض حقل نصي ليتم استخدامه لإدخال رمز التحقق وإضافة رابط لتغيير صورة الكابتشا:

	
					2
				
					<input 
					type="text" 
					name="captcha_code" 
					size="10" 
					maxlength="8" 
					style="direction: rtl" 
					/>
				
					3
				
					<a 
					href="#" 
					onclick="document.getElementById('captcha').src = '/ArCaptcha/GetArCaptcha.php?' + Math.random(); return false;">
					[غيّر الصورة]
					</a>

ملاحظة: يمكنك تغيير سِمَة maxlenght لحقل رمز التحقق لتتناسب مع إعدادات عركابتشا الخاصة بك. كما أن السطر الثاني اختياري، لكنه يعطي المستخدم الخيار بتغيير الصورة إذا لم يستطع قراءة رمز التحقق.

الآن أصبح لدينا صورة كابتشا وحق لإدخال رمز التحقق، بفي علينا إضافة تعليمات برمجية بلغة PHP للتحقق من صحة رمز التحقق المدخل من قبل المستخدم.

افتح ملف PHP الذي يقوم بمعالجة مدخلات النموذج بعد إرسالها. يمكنك إيجاده من خلال التحقق من قيمة السِّمَة action في وسام النموذج <form>.

في السطر الأول في ملف PHP الذي يقوم بمعالجة مدخلات النموذج أضف السطر التالي:

	
					1
				
					<?php 
					session_start(); ?>

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

الخطوات القادمة قد تختلف حسب الطريقة التي يتم فيها معالجة مدخلات النموذج. إذا لم يكن لديك خبرة في لغة PHP فإن الجزء التالي ربما يكون صعباً بعض الشيء.

للتحقق من رمز التحقق المدخل، سنقوم باستدعاء فئة عركابتشا (ArCaptcha Class). يتعيّن عليك إضافة رمز PHP التالي داخل المخطوطة التي تعالج مدخلات النموذج، وينصح بإضافتها في نهاية الجزء الذي يقوم بالتحقق من الأخطاء (error checking)، بحيث يتم التحقق منه فقط في حالة سلامة جميع المدخلات الأخرى. وبالطبع، يكون الرمز التالي ضمن أوسمة <?php ?>.

	
					1
				
					include_once 
					$_SERVER['DOCUMENT_ROOT']
					.
					'/ArCaptcha/ArCaptcha.php';
				
					2
				
					$ArCaptcha 
					= new 
					ArCaptcha();

السطران السابقان سيُضَمّنان ملف عركابتشا المصدري ويُنشِئان كائناً (object) جديداً من عركابتشا والذي بدوره سيقوم بإنشاء الكابتشا وإدارتها والتحقق من رمز التحقق.

الآن سنتحقق من رمز التحقق الذي أدخله المستخدم من خلال الرمز التالي:

	
					3
				
					if 
					($ArCaptcha->validate($_POST['captcha_code'])
					=== 
					false) {
				
					4
				
					    /**
				
					5
				
					     * .رمز التحقق الذي تم إدخاله غير صحيح
				
					6
				
					     * يجب عليك هنا
						التعامل مع عملية التحقق من المدخلات بحيث توقف عملية المعالجة
					
					7
				
					     * .وتخبر المستخدم أنّ رمز التحقق الخاص بكابتشا غير صحيح
				
					8
				
					     */
				
					9
				
					    echo 
					'رمز التحقق الذي أدخلته خاطئ';
				
					10
				
					    exit;
				
					11
				
					}

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

باتباع هذه التعليمات، حريٌّ بعركابتشا أن تعمل في أقل جهد، تعلّم المزيد عن تخصيص عركابتشا في الجزء الثاني، وفي حال واجهت صعوبات أو مشاكل، انظر صفحة الأسئلة المتكررة.

التخصيص

في الجزء السابق، تعلمنا كيفية إعداد عركابتشا في أقل جهد ممكن، هنا سنتعلم كيفية تخصيص عركابتشا لتناسب تصميمك وإعدادتك وذوقك حتى.

تخصيص عركابتشا يمكن أن يتم من مكانين، ملف GetArCaptcha.php أو ملف ArCaptcha.php مباشرة، ينصح بتخصيصها من ملف GetArCaptcha.php، وهي ما سيتم مناقشته في الأمثلة التالية:

تغيير الألوان
التحكم بدرجة التعقيد
تخصيص الخط
التحكم في طول الكابتشا وحجم الخط
التحكم في جمالية رمز التحقق
استخدام رمز تحقق ثابت

تغيير الألوان

تغيير الألوان في عركابتشا سهل للغاية، يمكنك التحكم في لون الخلفية ولون التشويش والخطوط العشوائية، بالنسبة للتشويش والخطوط العشوائية، سيتم مناقشتها في جزء التحكم بدرجة التعقيد، الألون المستخدمة في عركابتشا تكون على شكل النظام السادس عشر (hex)، مثلاً 0X000000 لللون الأسود أو 0XFFFFFF لللون الأبيض. لتغيير لون الخلفية، قم بإلغاء التعليق (un-comment) عن السطر التالي في ملف GetArCaptcha.php واستبدل قيمة المتغير باللون الذي تريده.

		
						1
					
						$img->back_color
						= 
						0XFFFFFF;

كما أن عركابتشا تتيح لك إمكانية استخدام خلفية شفافة، وهي الإعداد الإفتراضي اعركابتشا، لإلغاء الخلفية الشفافة، قم بإلغاء التعليق عن السطر التالي وضع قيمة false:

		
						1
					
						$img->transparent
						= 
						false;

ملاحظة: عند استخدام خلفية شفافة فإن لون الخلفية سيتم تجاهله.

التحكم بدرجة التعقيد

درجة التعقيد يمكن التحكم بها في ثلاثة طرق:

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

1 $img->draw_noise = false;
ثالثاً، من خلال الخطوط العشوائية، يتم استخدام خوارزمية لرسم خطوط عشوائية فوق صورة الكابتشا، يمكنك إلغاؤها طبعاً، ويتم ذلك من خلال إلغاء التعليق للسطر التالي وإعطاء قيمة المتغير false.

1 $img->draw_lines = false;

كما ويمكنك إيضاً التحكم بعدد الخطوط العشوائية من خلال إلغاء التعليق للسطر التالي وإعطاء قيمة المتغير عدد الخطوط العشوائية الذي تريده.

1 $img->num_lines = 4;

ملاحظة، إذا قمت بإلغاء إضافة الخطوط العشوائية، فإن عدد الخطوط العشوائية سيتم تجاهله.

يمكن تحديد لون التشويش والخطوط العشوائية من خلال إلغاء التعليق للسطر التالي واستبدال قيمته بالقيمة السادسة عشر للون الذي تريده.

1 $img->noise_color = 0XDCDCC8;

تخصيص الخط

ربما تريد استخدام نوع خط مختلف عن الذي يتم استخدامه في عركابتشا، عركابتشا تدعم خطوط النوع الحقيقي (TTF)، لاستخدام خط خاص بك، قم بتحميل ملف الخط على خادم الويب وضعه في مجلد عركابتشا أو أي مكان تريده، واستخدم المسار المطلق (absolute path) للملف واستبدله بقيمة المتغير font_file في السطر التالي بعد إلغاء التعليق عن السطر طبعاً:

		
						1
					
						$img->font_file
						= 
						$_SERVER['DOCUMENT_ROOT']
						.
						'/fonts/font.ttf';

ملاحظة: المثال السابق يعني بأن ملف الخط موجود في مجلد fonts تحت جذر دليل الويب مباشرة.

التحكم في طول الكابتشا وحجم الخط

يمكن تغيير طول الكابتشا وحجم الخط بكل سهولة في عركابتشا، طول الكابتشا يعني عدد الحروف المستخدمة في رمز التحقق.
لتغيير طول الكابتشا، عدل قيمة المتغير في السطر التالي بعد إلغاء التعليق عنه:

		
						1
					
						$img->length
						= 
						4;

ولتغيير حجم الخط، عدل قيمة المتغير في السطر التالي بعد إلغاء التعليق عنه:

		
						1
					
						$img->font_size
						= 
						20;

التحكم في جمالية رمز التحقق

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

		
						1
					
						$img->darkness_level
						= 
						5;

كما يمكنك أيضاً إضافة ظلّ أسود لحروف رمز التحقق من خلال إلغاء التعليق عن السطر التالي وإعطاء المتغير قيمة true:

		
						1
					
						$img->shadow
						= 
						true;

استخدام رمز تحقق ثابت

عند استخدام الاختبار الآلي لموقعك (automated test)، قد تحتاج إلى رمز تحقق ثابت ليتم استخدامه في عركابتشا، وعندها، سيتمكن اختبارك الآلي من الإجابة على رمز تحقق عركابتشا، لاستخدام رمز تحقق ثابت، قم بإلغاء التعليق عن السطر التالي واستبدل قيمة المتغير برمز التحقق الذي تريده:

		
						1
					
						$img->fixed_verify_code
						= 
						'بنانا';

عندها، ستقوم عركابتشا باستخدام نفس رمز التحقق في كل مرة تعرض صورة كابتشا.

ملاحظة: لا تستخدم كابتشا ثابتة إلا في حالة الاختبار الآلي، وعند الانتهاء منه، قم بإلغائها مرة أخرى من خلال تعليق نفس السطر.

ملاحظة: يمكنك توليد ملف GetArCaptcha.php المخصص والخاص بك في صفحة العرض.

في حال واجهتك أية مشاكل أو لديك سؤال أو استفسار، راجع صفحة الأسئلة المتكررة، أو اطرح سؤالك في صفحة النقاشات.

2	<input type="text" name="captcha_code" size="10" maxlength="8" style="direction: rtl" />
3	<a href="#" onclick="document.getElementById('captcha').src = '/ArCaptcha/GetArCaptcha.php?' + Math.random(); return false;"> [غيّر الصورة] </a>

1	include_once $_SERVER['DOCUMENT_ROOT'] . '/ArCaptcha/ArCaptcha.php';
2	$ArCaptcha = new ArCaptcha();

3	if ($ArCaptcha->validate($_POST['captcha_code']) === false) {
4	/**
5	* .رمز التحقق الذي تم إدخاله غير صحيح
6	* يجب عليك هنا التعامل مع عملية التحقق من المدخلات بحيث توقف عملية المعالجة
7	* .وتخبر المستخدم أنّ رمز التحقق الخاص بكابتشا غير صحيح
8	*/
9	echo 'رمز التحقق الذي أدخلته خاطئ';
10	exit;
11	}