maria stan

ماريستان

Mariastan هي أداة تحليل ثابت لاستعلامات Mariadb. الغرض الأساسي هو أن تكون بمثابة أساس لتمديدات phpstan.

الوضع الحالي (24. 04. 2024):

ماريستان غير مكتمل إلى حد كبير. إنه يغطي على الأرجح حوالي 90 ٪ من حالات الاستخدام في قاعدة رمز كبيرة حيث أستخدمها (مئات الجداول ، الآلاف من الاستعلامات). نتيجة لذلك لا يوجد الكثير من النشاط. ولكن يتم الحفاظ عليها بنشاط بمعنى أنه إذا كان هناك شيء ما بالنسبة لي ، فمن المحتمل أن يتم إصلاحه.

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

لا يوجد وعد توافق متخلف على أي شيء ، ولا توجد إصدارات - أنا فقط أستخدم Master.

تم اختبار Mariastan مع Mariadb 10.11 و Php 8.1-8.3.

تثبيت

قم بتثبيت Mariastan باستخدام composer require --dev schlndh/maria-stan:dev-master . ثم ستحتاج إلى إضافة ما يلي إلى phpstan.neon :

 includes :
    - ./vendor/schlndh/maria-stan/extension.neon

إعدادات

ماريستان يحتاج إلى الوصول إلى مخطط قاعدة البيانات. أسهل طريقة لتوفيرها هي السماح لها بالاتصال مباشرة بقاعدة بيانات. ستحتاج إلى إضافة التكوين التالي إلى phpstan.neon وتعيين بيانات الاعتماد المناسبة:

 parameters : 
    maria-stan :
        db :
            # Change these to match your database
            host : 127.0.0.1
            port : 3306
            user : ' root '
            password : ' '
            database : ' db '

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

بدلاً من ذلك ، من الممكن أيضًا استخدام Mariastan دون الوصول إلى قاعدة البيانات أثناء التحليل. في هذه الحالة ، ستحتاج أولاً إلى تفريغ المخطط باستخدام MariaDbFileDbReflection::dumpSchema وحفظه في ملف. إليك نص مثال يقوم بذلك:

 <?php

declare (strict_types= 1 );

use MariaStan  DbReflection  MariaDbFileDbReflection ;

require_once __DIR__ . ' /vendor/autoload.php ' ;

$ mysqli = new mysqli ( ' 127.0.0.1 ' , ' root ' , '' );
file_put_contents ( __DIR__ . ' /maria-stan-schema.dump ' , MariaDbFileDbReflection:: dumpSchema ( $ mysqli , ' database ' ));

ثم أضف ما يلي إلى phpstan.neon الخاص بك:

 parameters :
    maria-stan :
        reflection :
            file : %rootDir%/../../../maria-stan-schema.dump
services :
    mariaDbReflection : @ mariaDbFileDbReflection

لاحظ أن التوسع التلقائي للمسارات النسبية لا يعمل إلا مع تكوين Phpstan الخاص (أي أنه قائمة متشددين من مفاتيح التكوين). لذلك سيكون عليك تقديم مسار مطلق إلى ملف التفريغ.

انظر extension.neon للحصول على قائمة كاملة من المعلمات.

الاستخدام

يتضمن Mariastan تمديد عينة Phpstan لـ MySqli. ومع ذلك ، فإن الغرض من هذا التمديد هو ببساطة التحقق من التكامل مع Phpstan. لا أتوقع من أي شخص استخدام MySqli مباشرة. لذلك ، من المتوقع أن تكتب امتداد Phpstan الخاص بك الذي يتكامل مع Mariastan. إذا كنت ترغب في استخدام امتداد mysqli ./vendor/schlndh/maria-stan/extension.mysqli.neon فشين phpstan.neon

يمكنك استخدام امتداد MySQLI كنقطة انطلاق ، قم بتعديلها لتتناسب مع احتياجاتك. الفكرة الأساسية هي الحصول على سلسلة الاستعلام من Phpstan ، ونقلها إلى Mariastan للتحليل ، ثم الإبلاغ عن أنواع النتائج والأخطاء مرة أخرى إلى Phpstan.

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

سمات

فيما يلي قائمة بالميزات التي يمكنك تنفيذها في امتداد Phpstan الخاص بك استنادًا إلى Mariastan (يجب أن يظهر معظمها في امتداد MySqli):

• اكتب نتائج نتائج الاستعلام. هذا وحده لا يقدر بثمن عند استخدام phpstan مع رمز يعمل مع بيانات DB.
  • يمكن لماريستان في بعض الأحيان أن يستنتج أنواعًا أضيق من الأنواع التي يتم إرجاعها بواسطة قاعدة البيانات (على سبيل المثال mysqli_result::fetch_fields ). وذلك لأن ماريستان يمكنه (في الحالات البسيطة) فهم الاستعلامات مثل SELECT col FROM tbl WHERE col IS NOT NULL وإزالة NULL من نوع النتيجة ، في حين لا يبدو أن MariaDB يفعل ذلك.
• اكتشاف الأخطاء الأساسية. على سبيل المثال:
  • الجداول غير المعروفة ، أعمدة ، ...
  • أسماء الأعمدة الغامضة ،
  • عدد غير متطابق من العناصر النائبة ،
  • البيانات المفقودة للأعمدة الإلزامية في INSERT / REPLACE
  • ...
• الإبلاغ عن استخدام الجداول/الأعمدة المهملة.
• نطاق عدد الصفوف: في الحالات البسيطة ، يمكن لماريستان تحديد عدد الصفوف التي تم إرجاعها (على سبيل المثال SELECT COUNT(*) FROM tbl ) والتي يمكن استخدامها لتضييق نوع العائد من الأساليب مثل mysqli_result::fetch_all (أي non-empty-array ).
• تجاوز نوع العمود: يمكنك تجاوز نوع العمود (على سبيل المثال لأن الجدول "ثابت") وحتى نشره تلقائيًا عبر المفاتيح الخارجية.
• أنواع PHPDOC المخصصة: على سبيل المثال mysqlitableassocrowtype.

القيود

• لا يوجد حاليًا أي تقييم ذاكرة التخزين المؤقت التي يتم تنفيذها لـ Phpstan. ليس من الواضح ما إذا كان مثل هذا الشيء ممكن بسهولة. انظر هذا المناقشة. ومع ذلك ، فإن هذا لا يهم إلا تغييرات المخطط (أي إذا قمت بتغيير استعلام في ملف PHP ، فسيقوم PHPSTAN بإبطاله تلقائيًا).
• لا يوجد دعم لبناة الاستعلام. يتوقع المحلل استعلامًا كسلسلة على الإدخال.
• يجب أن يكون الاستعلام معروفًا تمامًا. إذا كان لديك رمز مثل هذا:

   function foo ( mysqli $ db , int $ count ) {
      return $ db -> prepare ( " SELECT * FROM tbl WHERE id IN ( " . implode ( ' , ' , array_fill ( 0 , $ count , ' ? ' )) . ' ) ' );
  }

  لن يكون Phpstan قادرًا على تقييمه بشكل ثابت ، وبالتالي لدى ماريستان أي شيء لتحليله.
• لا يوجد دعم للجداول المؤقتة.
• لا يوجد دعم لقواعد البيانات المتعددة.
• القيود المذكورة أعلاه هي تلك الرئيسية طويلة الأجل. ولكن إلى جانبهم ، يتم تنفيذ كل شيء جزئيًا فقط.

مشاريع مماثلة

Staabm/Phpstan-DBA

بقدر ما أستطيع أن أقول ، يعمل Phpstan-DBA من خلال تنفيذ الاستعلامات للحصول على المعلومات حول أنواع النتائج والأخطاء ، ... من ناحية أخرى ، يقوم Mariastan بتحليل الاستعلامات بشكل ثابت. تشمل فوائد Phpstan-DBA:

• دعم سهل لقواعد البيانات المتعددة. مع ماريستان هذا مستحيل (مع استثناء محتمل من MySQL).
• أكثر اكتمالا وموثوقة التحقق من الأخطاء بفضل قاعدة البيانات التي تقوم بالرفع الثقيل. من ناحية أخرى ، تُرجع قاعدة البيانات خطأً واحدًا فقط في وقت واحد ، في حين أن Mariastan قد تكون قادرة على اكتشاف مشكلات متعددة في وقت واحد.
• تحليل خطة الاستعلام. هذا يبدو غير ممكن أن تفعل بشكل ثابت. من ناحية أخرى ، لست متأكدًا من مدى فائدة ذلك في الممارسة خاصةً إذا كنت لا ترغب في إعطاء وصول Phpstan-DBA إلى بيانات الإنتاج.
• يبدو أنه من الأسهل البدء به ، لأنه يحتوي على ملحقات لتجريدات قاعدة البيانات المتعددة.

هناك بعض الجوانب السلبية البسيطة لنهج Phpstan-DBA:

• لا يوجد أي طريق لتحليل ثابت كامل (أي لا يتطلب قاعدة بيانات قيد التشغيل في أي وقت). يتطلب Mariastan حاليًا أيضًا قاعدة بيانات قيد التشغيل (للحصول على بيانات من information_schema ، وليس بالضرورة في وقت التحليل). ولكن من الممكن تنفيذ CREATE TABLE (وما إلى ذلك) تحليل وتنفيذ انعكاس DB علاوة على ذلك.
• نظرًا لأن الاستعلامات يتم تنفيذها ، يجب أن تكون حذرة مع استعلامات تعديل البيانات/المخطط. لقد رأيت بعض الشروط التي تقيدها SELECT الاستعلامات في عدة أماكن ، وكذلك استخدام المعاملات. لذلك ، لست متأكدًا من مدى دعم INSERT وما إلى ذلك (هناك بعض الاختبارات على الأقل).