EN
01

ما الذي تقدمه

حقل رفع الملفات العادي يرسل الصورة كما اختارها الزائر. أما Universal Form Cropper فتضيف إلى النموذج مربعًا يسحب الزائر إليه صورته (أو ينقر لاختيارها)، ثم يحرّكها داخل إطار مربع ويضبط التكبير، مع معاينة مباشرة للنتيجة.

عند الضغط على Save تُرفع الصورة الأصلية إلى مجلد مؤقت، ثم يقصّها الخادم ويعيد تحجيمها إلى مقاس مربع ثابت، ويحفظها في المجلد النهائي، ويحذف النسخة المؤقتة. ويُكتب رابط الصورة النهائية في أحد حقول النموذج، فإذا أُرسل النموذج حمل ذلك الحقل رابط الصورة لا الصورة نفسها. وبعد الحفظ يستطيع الزائر إعادة فتح أداة القص أو حذف الصورة.

صُممت الإضافة لتعمل مع أي نموذج، من Contact Form 7 وWPForms وGravity Forms إلى نماذج HTML العادية. فهي لا تتضمن كودًا خاصًا بأي إضافة نماذج، وإنما تعمل على كود HTML للنموذج نفسه؛ لذلك يتوقف حفظ الرابط على أمرين: أن يُعرض الكود المختصر داخل النموذج، وأن يعالج النموذج حقلًا يحمل اسم الأداة (راجع الكود المختصر).

  • كود مختصر
  • قص على الخادم
  • صورة مربعة
  • JPG · PNG · WebP
  • دون jQuery
02

التثبيت

  1. حمّل ملف ZIP.
  2. من لوحة ووردبريس افتح Plugins ← Add Plugin (اسمها Add New Plugin أو Add New في الإصدارات الأقدم)، واضغط Upload Plugin، واختر الملف، ثم Install Now ثم Activate Plugin.
  3. افتح Settings ← Universal Form Cropper. إذا كان النموذج موجّهًا لزوار غير مسجلين، أو لمستخدمين لا يملكون صلاحية upload_files، ففعّل خيار Allow guest uploads.
  4. ضع الكود المختصر داخل النموذج.
03

الكود المختصر

[universal_form_cropper field="cropped_image" label="Upload photo"]

الخصائص[universal_form_cropper]

field
اسم حقل النموذج الذي يستقبل رابط الصورة. يقبل الحروف اللاتينية الصغيرة والكبيرة والأرقام و_ و- فقط، وأي قيمة أخرى تُستبدل بالقيمة الافتراضية cropped_image.
label
النص الظاهر فوق مربع الرفع. القيمة الافتراضية: «Upload photo».
key (اختياري)
عدد صحيح موجب يحوّل الاسم إلى صيغة field[key]؛ فمثلًا key="2" ينتج cropped_image[2]. استخدمه حين يضم النموذج أكثر من أداة قص، أو لمطابقة حقل باسم مثل item_meta[152] (field="item_meta" key="152").

يجب أن يقع الكود المختصر داخل وسم <form>، وإلا ظهرت في المربع الرسالة “Universal Form Cropper must be placed inside a <form>.” ويجب كذلك أن يُعرض هناك بصيغة HTML؛ فإذا ظهر الكود نصًا عاديًا بدل مربع الرفع، فالجهة التي تطبع النموذج لا تشغّل الأكواد المختصرة في ذلك الموضع.

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

04

مثال: Contact Form 7

في قالب النموذج:

[universal_form_cropper field="cropped_image" label="Your photo"]
[hidden cropped_image]

وفي تبويب Mail أضف الوسم [cropped_image]، فيصلك في الرسالة رابط الصورة المقصوصة.

لا يشغّل Contact Form 7 افتراضيًا الأكواد المختصرة للإضافات الأخرى داخل قالب النموذج. فإذا ظهر [universal_form_cropper …] نصًا عاديًا بدل مربع الرفع، فأضف هذا السطر إلى ملف functions.php في القالب (أو إلى إضافة مخصصة صغيرة): add_filter( 'wpcf7_form_elements', 'do_shortcode' );

أما نموذج HTML العادي فيكفيه الكود المختصر وحده، لأن الإضافة تضيف الحقل المخفي بنفسها. وأي أداة بناء نماذج أخرى تحتاج إلى ما يحتاجه Contact Form 7: أن تعرض الكود المختصر داخل النموذج، وأن يحمل أحد حقولها الاسم المحدد في field (أو field[key]) بالضبط.

05

الإعدادات

جميع الخيارات في Settings ← Universal Form Cropper، وفيها زر «Reset to defaults» يعيد القيم الافتراضية دون المساس بالصور المرفوعة.

الإعدادالقيمة الافتراضية

Allow guest uploads
معطّل. لا يرفع الصور إلا المستخدمون المسجلون الذين يملكون صلاحية upload_files، ويرى غيرهم رسالة «Please sign in to upload an image.» أو «You don't have permission to upload images.»، ويفشل الحفظ برمز E_LOGIN_REQUIRED أو E_FORBIDDEN. فعّله في النماذج العامة، وعندها يستطيع كل من يفتح الصفحة الرفع في حدود معدلات الطلب.
Max upload size
‏2 ميجابايت (من 0.25 إلى 20). الأنواع المسموح بها JPG وPNG وWebP فقط، ويتحقق المتصفح من الملف أولًا ثم يتحقق الخادم منه مرة أخرى.
Output size
600 × 600 بكسل، وهو مقاس الصورة المربعة النهائية (من 64 إلى 2000 بكسل). وتحتفظ الصورة النهائية بصيغة الملف المرفوع.
Minimum crop size
‏100 بكسل (من 32 إلى 2000) مقيسة على الصورة الأصلية. يُرفض القص الأصغر برمز E_CROP_TOO_SMALL، لذا قد يفشل الحفظ مع صورة صغيرة جدًا أو تكبير مفرط.
Token lifetime
‏600 ثانية (من 60 إلى 3600): مدة صلاحية رمز الرفع الموقّع. وعند الضغط على Save تطلب الأداة رمزًا جديدًا إن قاربت صلاحية الرمز الحالي على الانتهاء.
Rate limits
لكل عنوان IP: ‏60 طلب رمز، و20 عملية رفع، و20 عملية قص نهائي. ويُصفَّر العداد بعد نافذة زمنية واحدة (ساعة) من آخر طلب احتسبه. ويمكن ضبط النافذة وكل حد منها.
Temp retention
‏24 ساعة (حتى 168، والقيمة 0 توقف التنظيف). تحذف مهمة تعمل كل ساعة الملفات المؤقتة الأقدم من هذه المدة، مثل الصور التي لم تبلغ الخطوة النهائية. أما الصور النهائية فلا تُحذف تلقائيًا أبدًا.
Widget UI
مقاس مربع القص (250 بكسل)، ومقاس المعاينة (160 بكسل)، والحد الأدنى والأقصى للتكبير ومقدار خطوته (1× و3× و0.01).
Enable event logging
معطّل. عند تفعيله تُسجَّل الأحداث في logs/events.log داخل مجلد الرفع الخاص بالإضافة، ويُدوَّر الملف عند 5 ميجابايت مع الاحتفاظ بآخر 5 ملفات. ولا تُحفظ عناوين IP إلا مجزّأة (hash). استخدمه لتتبع الأخطاء.
06

كيف تحافظ على الأمان

  • آمنة افتراضيًا. رفع الزوار معطّل إلى أن تسمح به.
  • كل طلب يخضع للتحقق. يحمل كل طلب رمز nonce من ووردبريس، وتتطلب خطوتا الرفع والقص فوق ذلك رمزًا موقّعًا قصير العمر (10 دقائق افتراضيًا) مرتبطًا بعنوان IP الزائر ومتصفحه.
  • فحص صارم للملفات. حد للحجم، وقائمة مسموحة تقتصر على JPG وPNG وWebP، وفحص ثانٍ لنوع الملف المرفوع، وأسماء عشوائية للملفات.
  • الخادم هو من يصنع الصورة النهائية. لا يرسل المتصفح إلا إحداثيات القص، ويفرض الخادم الحد الأدنى للقص، ويأخذ مقاس الصورة من إعداداتك لا من المتصفح، ويطبّق اتجاه الصورة المسجّل في بيانات EXIF أولًا، فيطابق القص ما رآه الزائر.
  • مجلدات محمية. تكتب الإضافة قواعد .htaccess (لخادم Apache) وweb.config (لخادم IIS): تُغلق الملفات المؤقتة والسجلات أمام زوار الويب، وتمنع مجلدات الصور تشغيل ملفات البرمجيات وعرض محتويات المجلد. ولا يقرأ Nginx هذه الملفات، فإن كان خادمك Nginx فأضف قواعد مماثلة بنفسك.
  • تحديد معدل الطلبات لكل عنوان IP في طلب الرموز والرفع والقص النهائي.
  • روابط عامة بأسماء عشوائية. كل من يملك رابط صورة نهائية يستطيع فتحها.
  • حذف الإضافة لا يحذف صورك. يزيل الحذف إعدادات الإضافة ومهمة التنظيف المجدولة، ويبقى مجلد الرفع universal-form-cropper، فتظل الصور التي أرسلتها نماذجك تعمل.
07

للمطورين

  • الفلتر ufc_allow_guest_uploads: يسمح برفع الزوار أو يمنعه برمجيًا، ويستقبل قيمة الإعداد.
  • الفلتر ufc_upload_capability: يغيّر الصلاحية المطلوبة للرفع والقص (الافتراضية upload_files).
  • الفلتر ufc_enable_logging يشغّل التسجيل أو يوقفه. وتعريف الثابت UFC_DISABLE_LOGGING بقيمة true في wp-config.php يوقفه أيًا كان الإعداد أو الفلتر.
  • تُرسل الطلبات إلى admin-ajax.php بالإجراءات ufc_get_token وufc_upload_tmp وufc_make_final.
  • تُخزَّن الملفات في مجلد الرفع (عادة wp-content/uploads/universal-form-cropper/) داخل tmp/ وfinal/ وlogs/.
  • يُؤخذ عنوان IP المستخدم في حدود الطلبات والرموز من REMOTE_ADDR وحده. فإذا كان الموقع خلف وسيط (proxy) أو شبكة CDN لا تمرّر عنوان الزائر إلى PHP، يتشارك جميع الزوار عدادات الحدود نفسها.
  • لا تُحمَّل ملفات CSS وJavaScript إلا في الصفحات التي تستخدم الكود المختصر، والسكربت مكتوب بلغة JavaScript الخالصة دون أي اعتماديات.
08

أسئلة شائعة

هل يرسل النموذج ملف الصورة؟

لا، يرسل رابط الصورة المقصوصة المحفوظة على موقعك.

لماذا يرى الزوار رسالة «Please sign in to upload an image.» أو الرمز E_LOGIN_REQUIRED؟

لأن رفع الزوار معطّل افتراضيًا. فعّل خيار Allow guest uploads من الإعدادات.

هل يمكن وضع أداتي قص في نموذج واحد؟

نعم، امنح كل أداة قيمة field مختلفة، أو الحقل نفسه مع قيم key مختلفة.

هل تُحذف الصور المقصوصة؟

لا. لا يُنظَّف إلا الملفات المؤقتة، وتبقى الصور النهائية إلى أن تحذفها بنفسك، ومنها الصور المحفوظة في نماذج لم تُرسل قط. وأيقونة سلة المهملات في النموذج تُفرغ الحقل فقط، ويبقى الملف على الخادم.

يفشل الحفظ ويظهر رمز خطأ. ما معناه؟

يظهر تحت المربع سطر يبدأ بكلمة «Failed:» يليها الرمز. وهذه أكثر الرموز شيوعًا:

الرمزالمعنى

E_LOGIN_REQUIRED
المستخدم غير مسجل الدخول، ورفع الزوار معطّل.
E_FORBIDDEN
المستخدم مسجل لكنه لا يملك الصلاحية المطلوبة، ورفع الزوار معطّل.
E_CSRF
فشل التحقق من رمز nonce المطبوع في الصفحة، كأن تكون أداة تخزين مؤقت قد قدّمت نسخة قديمة منها. فإن كان التخزين المؤقت هو السبب، فاستثن صفحة النموذج منه.
E_RATE_LIMIT
بلغ عنوان IP هذا أحد حدود معدل الطلبات.
E_TOKEN_IP, E_TOKEN_UA, E_TOKEN_EXPIRED
تغيّر عنوان IP الزائر أو متصفحه منذ تحميل الصفحة، أو انتهت صلاحية الرمز. وإعادة تحميل الصفحة تمنحه رمزًا جديدًا.
E_SIZE, E_MIME, E_UPLOAD_HANDLE
الملف فارغ أو يتجاوز الحد المسموح، أو ليس صورة JPG أو PNG أو WebP حقيقية، أو تعذّر على ووردبريس تخزينه.
E_UPLOAD
رفضت PHP عملية الرفع، كأن يتجاوز الملف حد الرفع المضبوط في إعدادات PHP على الخادم.
E_CROP_TOO_SMALL
مساحة القص أصغر من الحد الأدنى.
E_EDITOR
مكتبة معالجة الصور على الخادم لا تستطيع فتح الملف. ولصيغة WebP يجب أن تدعمها مكتبة GD أو Imagick.

تحميل Universal Form Cropper الإصدار 0.6.4