yamf php

يامف

YAMF (بعد إطار عمل MVC آخر) هو إطار صغير PHP MVC مصمم للسماح لك البدء في استخدام نموذج MVC بسرعة دون الكثير من أعمال الإعداد. كل ما تحتاجه هو خادم ويب يقبل ملفات .htaccess وأنت جيد جدًا!

يثبت

الحد الأدنى من المتطلبات: PHP 7.0+.

1. استنساخ المستودع و/أو استخدم هذا المشروع كقالب لمشروعك من خلال النقر فوق هذا الرابط أو بالنقر فوق الزر " Use this template في صفحة ريبو المشروع الرئيسية.
2. تأكد من إعداد خادم الويب الخاص بك للقراءة والاستفادة من ملفات .htaccess. (إذا كنت لا تعرف ما يعنيه هذا ، يرجى Google! ربما سنضيف بعض روابط المساعد هنا في وقت لاحق.)
3. تكوين config.php إذا لزم الأمر. اضبط أي معلمات ترغب في ذلك هناك أو إضافة معلمات جديدة إلى $app ، مثل منطق الجلسة. افتراضيًا ، لا تحتاج إلى ضبط أي شيء لتشغيل موقعك.
4. إذا كان لديك أي نوع من بيانات اعتماد قاعدة البيانات ، والمفاتيح الخاصة ، وما إلى ذلك ، والتي يجب استخدامها في الموقع ، قم بنسخ config-private.sample.php config-private.php وضبطه على احتياجاتك. على سبيل المثال ، يمكنك إعداد $app->db ليكون مثيل PDO لقاعدة البيانات المحلية الخاصة بك. لاحظ أنه سيتم تحميل config-private.php قبل حدوث أي شيء في config.php .
5. من أجل use Yamf/XYZ ، ستحتاج إلى استخدام الملحن. يعد استخدام الملحن أمرًا سهلاً للغاية: ما عليك سوى الانتقال إلى صفحة التنزيل وقم بتشغيل البرنامج النصي في الأعلى. (ملاحظة: إذا كنت على Windows ، فستحتاج إلى اتباع الإرشادات هنا على الصفحة المقدمة.)
6. composer install (إذا كنت قد حصلت على ملف composer.phar في الدليل الخاص بك ، قم بتشغيل php composer.phar install ). سوف يجلس ويفكر لمدة دقيقة.
7. لقد انتهيت! استمتع بمواقع الويب المستندة إلى MVC! يمكنك مزق العناصر العينة الافتراضية و CSS ، بالطبع!

انتظر! أين مكتبة / عرض ترحيل قاعدة البيانات / عرض المنطق / وحدة اختبار الوحدة / {إطار عمل آخر هنا}؟!

إنهم ليسوا هنا ، وهم ليسوا هنا عن قصد! تمت كتابة YAMF عن قصد لعدم استخدام أي تبعيات خارجية غير التحميل التلقائي للملحن لخفض حاجز الدخول لاستخدام نموذج MVC في PHP. إذا كنت تريد أيًا من هذه الأشياء ، فما عليك سوى سحبها مع مدير التبعية المفضل لديك (مثل الملحن). نظرًا لأن الملحن ضروري بالفعل لتشغيل هذا المشروع من أجل التحميل التلقائي PSR-4 ، فإننا نوصي باستخدام الملحن. تم تضمين vendor/autoload.php بالفعل لك في init.php .

للحصول على ملاحظة بخصوص العرض ، راجع القسم المتعلق بالفئة الفرعية.

الوثائق

إذا قرأت الوثائق التالية على YAMF ، فمن المحتمل أن تكون أفضل بكثير من مجرد التنقل ومحاولة قراءة الكود بنفسك. :) سوف يستغرق الأمر بضع دقائق فقط ، ويستحق ذلك!

ملاحظات على تطبيق $

من أجل تسهيل تمرير معلمات التكوين السهل ، مثل إعدادات قاعدة البيانات ، وما إلى ذلك ، يمر YAMF متغير $app من الفئة YamfAppConfig إلى كل وظيفة وحدة تحكم. يمكنك إعداد هذا المتغير لتخزين كائن قاعدة البيانات PDO وتغيير موقع العرض أو موقع المجلد والعديد من الإعدادات الأخرى. إذا كنت ترغب في إضافة القيم الخاصة بك إلى $app ، فيمكنك إنشاء فئة مستمدة من YamfAppConfig وتغيير إعداد appConfigClass في config.php للإشارة إلى فئة مخصصة. لاحظ أن الفصول الدراسية المخصصة يجب أن تستمد من YamfAppConfig ! راجع config.php لرؤية جميع الإعدادات والقيم التي يتم تمريرها بواسطة yamf من خلال $app . والجدير بالذكر ، يمكنك:

• قم بتغيير موقع مجلد وجهات النظر الخاصة بك ( viewsFolderName )
• قم بتغيير امتداد ملفات العرض الخاصة بك ( viewExtension )
• قم بتغيير اسم الرأس أو تذييل الافتراض ( defaultHeaderName / defaultFooterName )
• يمكنك الوصول السهل إلى قاعدة بيانات PDO/أخرى (إعداد في config-private.php )

$app متاح تلقائيًا في طرق العرض الخاصة بك لك.

إضافة طريق جديد

أول شيء ربما تريد القيام به هو إضافة طريق جديد. للقيام بذلك ، اتبع هذه الخطوات:

1. إذا لم يكن لديك بالفعل فئة وحدة تحكم لمسارك الجديد ، فاستمر في إضافة واحدة في مجلد app/Controllers في المشروع. المجلدات الفرعية على ما يرام. لا يتعين على وحدة التحكم في الواقع أن يكون لها Controller في الاسم ، ولكن تأكد من تطابق اسم الفصل مع اسم الملف.
2. أضف كعبًا لطريقة وحدة التحكم الخاصة بك. على الأقل ، يجب أن تكون وظيفة public تأخذ معلمتين: $app و $request (بهذا الترتيب).
3. افتح routes.php وتأكد من فهم الوثائق والأمثلة على كيفية عمل الطرق.
4. أضف طريقك إلى مجموعة routes .
   • تأكد من تعيين POST إذا لزم الأمر.
   • يجب أن تتطابق سلسلة اسم وحدة التحكم مع اسم الملف واسم الفصل لوحدة التحكم من الخطوة الأولى.
   • إذا كانت وحدة التحكم في مجلد فرعي (أو المجلدات الفرعية) ، فتأكد من حصولك على الاسم بتنسيق Parent-Folder/Controller-Name .
   • يجب أن يتطابق اسم الوظيفة مع اسم الوظيفة من الخطوة 2.
5. في هذه المرحلة ، يعمل المسار ، لكن طريقة وحدة التحكم الخاصة بك تحتاج إلى إرجاع نوع من yamf/Responses/Response ، والتي يمكن أن تكون أي شيء من View إلى استجابة JSON ، حسناً ، كل ما تريد ، حقًا. انظر القسم التالي لمزيد من المعلومات هنا.
6. ربما تكون حالة الاستخدام العادية هي إرجاع yamf/Responses/View . قم بإنشاء ملف PHP (عرض) في مجلد views - مرة أخرى ، المجلدات الفرعية على ما يرام - وفي طريقة وحدة التحكم الخاصة بك ، return new View('name/of/view'); .
7. يجب أن يكون المسار الآن وظيفيًا!

باختصار:

1. إضافة وحدة تحكم وطريقة تحكم إلى مجلد app/Controllers
2. أضف الطريق إلى routes.php
3. إنشاء عرض في مجلد views إذا لزم الأمر
4. تعديل طريقة وحدة التحكم return new View('name/of/view');

أنواع الإرجاع من وظائف وحدة التحكم

يجب أن تُرجع جميع أساليب وحدة التحكم التي تسمى نتيجة المسار yamf/Responses/Response أو فئة فرعية من الفئة المذكورة. فيما يلي بعض الأوصاف حول كيفية استخدام كل واحد. يمكن استخدام معظمها في سطر واحد مع المُنشئ فقط.

• Response - فئة الأساس للاستجابة من الطريق.
  • تنسيق المنشئ: new Response($statusCode = 200)
  • يخرج رمز الحالة.
  • نظرًا لأن جميع الفئة الفرعية الأخرى لـ yamf/Responses/Response من هذه الفئة الأصل ، يمكنهم جميعًا إعادة رمز حالة HTTP مخصص ، إذا كنت تريد!
• ErrorMessage - غلاف بسيط حول العرض لإرسال رمز الحالة 400 وعرض error.php.
  • تنسيق المنشئ: new ErrorMessage($msg = '', $name = 'error', $title = '', $headerName = '', $footerName = '') . $name هو اسم العرض.
  • لاحظ أن المعلمة الأولى هي رسالة الخطأ ، وليس اسم العرض!
  • بشكل افتراضي ، فإن الاسم المتغير للخطأ لإخراجه في عرضك هو $error . لا يمكنك تغيير هذا دون التصنيف الفرعي.
  • بشكل افتراضي ، فإن الرأس والتذييل المستخدمين هما views/header.php views/footer.php .
  • يمكن تغيير رمز الحالة ، بالطبع ،.
• JsonResponse - مثال على كيفية إعادة استجابة JSON من وحدة التحكم الخاصة بك
  • تنسيق المنشئ: new JsonResponse($data, $jsonEncodeOptions = 0)
  • يخرج $data عبر echo json_encode($this->data, $this->jsonEncodeOptions);
• NotFound - يستخدم لإعادة 404 لم يتم العثور على رسالة إلى العميل.
  • تنسيق المنشئ: new NotFound($name = '404', $data = [], $title = '', $headerName = '', $footerName = '') . $name هو اسم العرض.
  • بشكل افتراضي ، فإن الرأس والتذييل المستخدمين هما views/header.php views/footer.php .
  • إذا كنت ترغب في إعادة إرسال 404 فقط (على سبيل المثال لواجهة برمجة التطبيقات) ، استخدم Response .
• Redirect - يسمح بإعادة توجيه 302 إلى صفحة أو مسار آخر
  • تنسيق مُنشئ: new Redirect($redirectPath, $isInternalRedirect = true)
  • رمز الحالة هو 302 بشكل افتراضي
  • يتم استخدام $isInternalRedirect لإعادة توجيه إلى طريق داخل موقع الويب/ routes.php الحالي . إذا كنت ترغب في إعادة توجيه إلى طريق داخلي ، فاستخدم Redirect مثل هذا: new Redirect('/route/name); (لاحظ البداية / ). إذا لم يكن الأمر كذلك ، استخدم Redirect مثل هذا: new Redirect('https://example.com', false); .
• View -يستخدم لإعادة بعض عرض HTML المستند إلى PHP.
  • تنسيق المنشئ: new View($name, $data = [], $title = '', $headerName = '', $footerName = '') . $name هو اسم العرض.
  • لإرسال البيانات إلى عرضك ، ربما تكون أسهل طريقة هي استخدام الوظيفة compact . انظر العينة BlogController .
  • بشكل افتراضي ، فإن الرأس والتذييل المستخدمين هما views/header.php views/footer.php .

إذا كانت لديك أفكار لمزيد من أنواع Response التي يجب تضمينها في YAMF ، فيرجى فتح طلب ميزة (عبر علامة تبويب المشكلات) أو فتح طلب سحب!

البيانات المرسلة في طرق وحدة التحكم

يتم إرسال متغيرين رئيسيين في أساليب وحدة التحكم الخاصة بك من المسار: $app و $request . لاحظ أن جميع إخراج View سيكون له $app ومتغيرات $request المتاحة للاستخدام. لا تحتاج إلى إرسالها كمعلمة $data .

AppConfig $app

$app هو متغيرات التكوين بشكل أساسي قمت بإعدادها في config.php . تحقق من هذا الملف لإلقاء نظرة سريعة على ما هو متاح. بعض العناصر الأكثر أهمية هي:

• $app->db لاتصال قاعدة البيانات
• أسماء ملفات الرأس الافتراضية لجميع المشاهدات ، صفحة 404 ، وصفحة الخطأ. يمكنك ضبط هذه على null لتجنب استخدامها على الإطلاق.

بالإضافة إلى ذلك ، هناك متغيران متاحان تم إعدادهما في init.php :

• $app->isLocalHost سواء كان التطبيق قيد التشغيل على المضيف المحلي أم لا ( 127.0.0.1 أو ::1 )
• $app->basePath الدليل الأساسي لتطبيق الويب الحالي الخاص بك. يمكن استخدام هذا للسماح بتطبيقات الويب المتداخلة على خادم الويب الخاص بك. أوصي بشدة بالاستفادة من هذا المتغير في views عند القيام بروابط موقع الويب المحلي بحيث إذا قمت بنقل الملفات حولها أو نقلها لاحقًا إلى مقلع فرعي لا ينهار كل شيء. للربط بصفحة أخرى على موقعك ، ما عليك سوى استخدام وظيفة $app->yurl(string) (url url yamf) مثل هذا: <?= $app->yurl('/path/to/page') ?> .

$request

سيكون $request جميع بياناتك حول مسارك والمعلمات المختلفة التي جاءت مع طلبك. إنه من نوع yamf/Request . لديها هؤلاء الأعضاء العامين متاحين:

• $request->route -سلسلة الطريق الخام لهذا الطلب
• $request->controller -اسم سلسلة وحدة التحكم
• $request->function -اسم سلسلة وظيفة وحدة التحكم للاتصال
• $request->routeParams أي معاملات في المسار مثل {id}. التنسيق: ['id' => value]
• $request->get أي الحصول على معاملات موجودة في عنوان URL-نفس التنسيق مثل $ _get (لا يتم إجراء معالجة إضافية)
• $request->post أي post params-نفس التنسيق مثل $ _post (لا يتم إجراء معالجة إضافية)
• $request->anchor -إذا تم استخدامه ، فإن الجزء # من عنوان URL (بدون #). جهاز التوجيه ذكي بما فيه الكفاية حتى لا يتطابق مع عناوين URL مثل /blah/#/foo .

التصنيف الفرعي لتمديد الإطار

أسهل طريقة لك لتوسيع هذا الإطار هي الاستخلاص من Response (أو بعض فئة Response الأخرى للطفل) و/أو إنشاء فئة الوالدين لبعض وحدات التحكم الخاصة بك. على سبيل المثال ، من خلال الاستخلاص من View ، يمكنك تغيير إخراج العرض لاستخدام محرك templating Twig بدلاً من مجرد إخراج PHP بسيط. من خلال إنشاء فئة أوليلية لوحدات التحكم الخاصة بك ، يمكنك إضافة أشياء مثل التحقق من الصحة أو معالجة إضافية أخرى للبيانات التي يجب أن تحدث لجميع طرق API الخاصة بك ، مثل التحقق من اسم المستخدم/كلمة المرور أو الرمز المميز. الخيارات لا حصر لها والرائعة المحتملة!

هناك مثال على استخدام الغصين بدلاً من PHP الخام على فرع الغصين!

بساطة الصفحة الثابتة

إحدى الميزات الأنيقة التي يدعمها YAMF هي صفحات ويب ثابتة لا تتطلب route أو controller . إذا كنت تريد /about أن تكون صفحة بسيطة ، فقم برمي صفحة about.php views/static/ - /about الأعمال على موقع الويب الخاص بك. ماذا عن المجلدات الفرعية مثل /blog/post-name ؟ هذا يعمل أيضا! أضف ملفات views/static/blog/post-name.php وهو يعمل فقط (TM)! يمكنك استخدام هذا للاستمرار في الحصول على عناوين URL جميلة على موقع الويب الخاص بك دون أن تزعجك بإضافة الطرق ووحدات التحكم.

يمكنك تكوين موقع طرق العرض الثابت في config.php .

لاحظ أن جهاز التوجيه يحاول مطابقة مسار router.php قبل التحقق من صفحات ثابتة.

URL Shortener

الميزة التي يدعمها جهاز التوجيه الذي لم يتم تمكينه على الفور هو تقصير URL-على سبيل المثال https://example.com/short-url . يتطلب اتصال قاعدة البيانات ، ولكن إذا قمت بإضافة اتصال قاعدة البيانات ولديه جدول قاعدة البيانات المناسب (المخطط في config.sample.php ) ، يمكن استخدام تقصير عنوان URL إذا كنت تريد. لست مطلوبًا لتمكين هذه الميزة.

منطق الجلسة الافتراضي

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

هل يمكنني المساعدة في المساهمة؟

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

رخصة

رخصة معهد ماساتشوستس للتكنولوجيا. يرجى التأكد من تضمين ترخيص هذا الإطار (جنبًا إلى جنب مع رابط GitHub إذا كنت تشعر بالسخاء!) عند استخدامه على موقعك. شكرًا لك! سائدا

شكر خاص

شكر خاص لـ BootSwatch لموضوع ورقة bootstrap المستخدمة في العينة.