Formidable

هائل

هائلة هي مكتبة PHP للتعامل مع النماذج. يوسع نموذج HTML ويسمح لك بالمعالجة منه من رمز PHP الخاص بك ، ثم تقديمه.

كيف تعمل؟

الخطوة 1: تنزيل وتثبيت هائل

عبر الملحن:

{
    "require" : {
        "gregwar/formidable" : " dev-master "
    }
}

أو مع استنساخ المستودع:

git clone https://github.com/Gregwar/Formidable.git

أو تنزيله:

• تنزيل .zip
• تنزيل .Tar.GZ

الخطوة 2: اكتب النموذج الخاص بك في HTML

أولاً ، عليك كتابة الكود الخاص بك في HTML ، على سبيل المثال:

 <!-- forms/example.html -->
< form method =" post " >
    Enter your name: 
    < input type =" text " name =" name " /> < br />
    < input type =" submit " />
</ form >

الخطوة 3: أعطها إلى هائلة

في رمز PHP الخاص بك ، أعط النموذج الخاص بك إلى هائلة:

 <?php
session_start ();
include ( ' vendor/autoload.php ' );

// Formidable will parse the form and use it to check integrity
// on the server-side
$ form = new Gregwar  Formidable  Form ( ' forms/example.html ' );

$ form -> handle ( function () {
    echo " Form OK! " ;
}, function ( $ errors ) {
    echo " Errors: <br/> " ;
    foreach ( $ errors as $ error ) {
        echo " $ error <br /> " ;
    }
});

echo $ form ;

بسيط ، أليس كذلك؟

الخطوة 4: استمتع بالسحر

يمكنك بعد ذلك استخدام واجهة برمجة التطبيقات الهائلة للعب مع النموذج الخاص بك:

 <?php

// Will set the value of the field
$ form -> name = " Bob " ;

// Will get the value of the field
$ name = $ form -> name ;

// Adds a constraint on the name
$ form -> addConstraint ( ' name ' , function ( $ value ) {
    if ( strlen ( $ value ) < 10 ) {
        return ' Your name should be at least 10 characters! ' ;
    }
});

// Adds a constraint on the whole form
$ form -> addConstraint ( function ( $ form ) {
    if ( $ form -> getValue ( ' pass1 ' ) != $ form -> getValue ( ' pass2 ' )) {
        return ' The passwords are different ' ;
    }
});

يمكنك أيضًا محاولة تغيير النموذج الخاص بك وإضافة قيد مباشرة في رمز HTML:

 < input type =" text " name =" name " minlength =" 10 " />

سيؤدي ذلك إلى إجبار النص على طول 10 أحرف على الأقل عند فحص قيود من جانب الخادم.

هل تريد Captcha لتأمين النموذج الخاص بك؟

 < input type =" captcha " name =" code " />

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

لاحظ أن هذا سيستخدم التبعية مع مكتبة Gregwar/Captcha (سيتعين عليك تثبيت التبعيات باستخدام الملحن).

الأنواع

يتم دعم أنواع الإدخال التالية:

• علامات input ، مع الأنواع:
  • text
  • number أو numeric ، انظر سمات min و max
  • int أو integer ، انظر سمات min و max
  • file
  • checkbox
  • radio
  • hidden
  • password
  • captcha ، سوف تقوم تلقائيًا بإنشاء صورة
  • date ، سيقوم بإنشاء ثلاثة اختيارات ، وإرجاع DateTime كبيانات
  • multiradio و multicheckbox (انظر القسم المصدر)
• textarea
• select

صفات

لاحظ أن بعض السمات ليست HTML-Valid ، مثل maxlength :

 < input type =" text " name =" name " maxlength =" 10 " />

لن يتم تقديمه في نموذج HTML ، ولكن سيتم استخدامه للتحقق من النزاهة.

فيما يلي قائمة السمات المتاحة:

• minlength : الحد الأدنى لطول القيمة
• maxlength : الحد الأقصى لطول القيمة
• regex : regexp التي يجب أن تحترمها القيمة
• min (للأرقام): الحد الأدنى للقيمة
• max (للأرقام): الحد الأقصى للقيمة
• required : أخبر أن الحقل مطلوب
• readonly : الحقل يقرأ ويجب ألا يكون تعديلًا
• value : القيمة الافتراضية للحقل
• min-entries : حدد الحد الأدنى لعدد الإدخالات التي يجب أن توفرها لمضاعفات (انظر أدناه)
• max-entries : حدد الحد الأقصى لعدد الإدخالات التي يمكنك توفيرها لمضاعفات (انظر أدناه)
• entries : حدد كلاً من الحد الأدنى والحد الأقصى لعدد الإدخالات للمتعددة (انظر أدناه)

API

يمكنك استدعاء هذه الطريقة على كائن $form الخاص بك:

• posted() : إرجاع صحيح إذا تم نشر النموذج
• check() : تحقق من النموذج وإرجاع مجموعة من أخطاء الصلاحية
• handle($callback, $errorCallback) ، استدعاء طريقة الاختصار هذه المنشورة والتحقق () ، وسوف يتصل $callback إذا كان النموذج صالحًا ، $errorCallback else
• setAttribute($field, $attr, $value) : تعيين سمة إضافية على حقل
• getAttribute($field, $attr) : يحصل على سمة إضافية على حقل
• source($source, $values) : تغذية مصدر (انظر قسم "المصدر")
• setPlaceholder($name, $value) : يضبط قيمة العنصر النائب (انظر أدناه)
• addConstraint($field, $callback) : يضيف قيدًا مخصصًا على حقل ، وسيتم استدعاء callback مع قيمة الحقل ويجب أن يعيد خطأ إذا لم تكن هناك مشكلة ، أو سلسلة خطأ. إذا قمت فقط بإغلاقه ، فسيتم استدعاء الإغلاق مع تمرير النموذج كوسيطة ويمكنه بعد ذلك إجراء بعض الاختبارات التي تتضمن حقول متعددة أو معلومات النموذج.
• setValue($field, $value) : اضبط قيمة الحقل
• getValue($field) : يحصل على قيمة الحقل
• setValues(array $values) : اضبط القيم لبعض الحقول
• getValues() : احصل على قيم جميع الحقول

حماية CSRF

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

يتم استخدام الرمز المميز لوجود وصلاحية CSRF للتحقق من نشر نموذج عند استدعاء الطريقة posted (يتم استخدامه داخليًا في handle )

إذا قمت بتحديد سمة name في form ، فسيكون رمز CSRF مختلفًا لهذا النموذج المحدد ، فسيسمح ذلك بإحداث الفرق الذي يتم تقديم النموذج إذا كان هناك نموذج متعدد في نفس الصفحة.

اللغات

يمكن تعيين لغة الأخطاء باستخدام setLanguage() :

 <?php

// Will set the language to french for errors
$ form -> setLanguage ( new Gregwar  Formidable  Language  French );

تأكد من أن لغتك مدعومة في دليل Language ، لا تتردد في المشاركة!

مصدر

يمكنك استخدام نظام المصادر لملء ديناميكي مجموعة select أو multiradio أو multicheckbox :

 < input type =" multicheckbox " name =" colours " source =" colours " />

ثم تملأه source :

 <?php
$ form -> source ( ' colours ' , array ( ' red ' , ' yellow ' , ' blue ' ));

سيتم تقديم هذا بواسطة بعض مربعات الاختيار.

يمكنك القيام بذلك بهذه الطريقة مع select :

 < select name =" colour " >
    < options source =" colours " />
    < option value =" other " > Other </ option >
</ select >

ثم مصدرها بنفس الطريقة

إنشاء نموذج من السلسلة

يمكنك إنشاء نموذج من ملف أو من سلسلة ، وسيتم اكتشاف ذلك تلقائيًا:

 <?php

$ form = new Gregwar  Formidable  Form ( ' <form method="post">
    <select name="colour">
        <option value="blue">Blue</option>
        <option selected value="red">Red</option>
        <option value="green">Green</option>
    </select>
    </form> ' );

echo $ form -> getValue ( ' colour ' ) . "n" ;
// red

// Sets the color to blue
$ form -> setValue ( ' colour ' , ' blue ' );

echo $ form ;
/* Will display:
<form method="post">
    <select name="colour" >
        <option selected="selected" value="blue">Blue</option>
        <option value="red">Red</option>
        <option value="green">Green</option>
    </select>
    <input type="hidden" name="posted_token" value="d293dc38017381b6086ff1a856c1e8fe43738c60" />
</form>
*/ 

رسم الخرائط

يمكنك أيضًا استخدام السمة mapping لملء النموذج الخاص بك أو لاستعادة بيانات النموذج في صفيف أو في كائن ، على سبيل المثال:

 <?php

class Person
{
    protected $ name ;
    public function getName () { return $ this -> name ; }
    public function setName ( $ name ) {
        $ this -> name = $ name ;
    }
}

$ person = new Person ;
$ person -> setName ( ' Jack ' );

$ form = new Gregwar  Formidable  Form ( ' <form method="post">
    <input type="text" name="name" mapping="name" />
    </form> ' );

$ form -> setData ( $ person );

echo $ form ;
/*
Will output something like:

<form method="post">
    <input required="required" type="text" name="name" value="Jack" />
    <input type="hidden" name="posted_token" value="aa27f437cc6127c244db14361fd614af51c79aac" />
</form>
*/

لاحظ أن التعيين يستخدم Symfony PropertyAccessor ، يمكنك بعد ذلك استخدام الملحق كما في المثال أعلاه لإلغاء الخصائص.

يمكنك استخدام:

• getData($entity = array()) : populate وإرجاع الكيان مع البيانات الملوثة بالبيانات
• setData($entity) : ملء النموذج بسمات الكيان

إنشاء أشكال فرعية متعددة

يمكنك إضافة أشكال فرعية متعددة إلى صفحة باستخدام علامة <multiple> :

 < form method =" post " >
    Film name: < input type =" text " name =" film_name " mapping =" name " />

    < h2 > Actors </ h2 >
    < multiple name =" actors " mapping =" actors " >
        First name: < input name =" first_name " mapping =" firstName " /> < br />
        Last name: < input name =" last_name " mapping =" lastName " /> < br />
    </ multiple >
    < input type =" submit " />
</ form >

مع هذا ، يمكن استخدام <multiple> تمامًا مثل الحقل ، ولكنه سيحتوي على مجموعة من العناصر.

سيتم حقن بعض JS في الصفحة ويسمح لك بإضافة/إزالة بعض العناصر.

يمكنك استخدام min-entries وقيود max-entries لوضع حدود على عدد الإدخالات في متعددة.

إذا قمت بتحديد نفس القيمة للدخول min-entries max-entries ، أو حددت قيمة entries (والتي هي في الواقع اسم مستعار للقيام بذلك) ، سيتم إصلاح عدد مدخلات OFR ولن يتطلب الأمر أي جافا سكريبت.

إضافة بيانات ديناميكية إلى النموذج

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

أول طريقة: استخدام العناصر النائبة

يتيح لك بناء جملة {{ something }} مجرد ضخ البيانات من الكود ، مثل هذا:

 <?php

$ form = new Gregwar  Formidable  Form ( ' <form method="post">
    Hello {{ name }}!
    </form> ' );

$ form -> setPlaceholder ( ' name ' , ' Bob ' );

echo $ form ;

في المثال أعلاه ، سيتم تقديم {{ name }} Bob .

لاحظ أنه يمكن استخدام العناصر النائبة على أي حال مستثنى في <form> وعلامات الإدخال:

 <?php

$ form = new Gregwar  Formidable  Form ( ' <form method="post">
    <span style="color:{{ color }}">Hello</span>
    </form> ' );

$ form -> setPlaceholder ( ' color ' , ' red ' );

echo $ form ;

الطريقة الثانية: استخدام نموذج PHP

يمكنك أيضًا كتابة النموذج الخاص بك باستخدام PHP ، مثل القالب ، على سبيل المثال:

<form>
    <?php echo $ label ; ?> : <input type="text" name="name" />
    <input type="submit" />
</form>

ثم قم بتركيب النموذج الخاص بك الذي يمر متغيرات القالب كوسيطة ثانية:

 <?php

$ form = new Gregwar  Formidable  Form ( ' the-above-form.php ' , array ( ' label ' => ' Your name ' ));

سيتم تفسير $label باستخدام PHP.

التخزين المؤقت

لأسباب الأداء ، قد ترغب في تخزين النماذج المحسورة.

للقيام بذلك ، ببساطة تمرير true كوسيطة ثالثة للمُنشئ:

 <?php

/**
 * Parsed data for the form will be serialized and stored in a cache file,
 * if you use this form often, this will offer you better performances.
 */
$ form = new Gregwar  Formidable  Form ( ' form.html ' , null , true );

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

حاول تشغيل examples/ النصي performances.php .

يمكنك أيضًا تمرير مثيل لـ GregwarCacheCache باعتباره المعلمة الثالثة ، والتي ستسمح لك بتعيين دليل ذاكرة التخزين المؤقت.

رخصة

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

تاريخ

v2.0.0 دعم نهاية PHP <5.6

v2.1.0 قم بإزالة الاعتماد الصعب على مكتبة Captcha