phan
Release 5.4.5 supporting PHP 7.0-8.2 syntax
Phan هو محلل ثابت لـ PHP ويفضل تقليل النتائج الإيجابية الخاطئة. يحاول فان إثبات الخطأ وليس الصواب.
يبحث Phan عن المشكلات الشائعة وسيتحقق من توافق النوع في العمليات المختلفة عندما تكون معلومات النوع متاحة أو يمكن استنتاجها. يتمتع فان بفهم جيد (ولكن ليس شاملاً) للتحكم في التدفق ويمكنه تتبع القيم في عدد قليل من حالات الاستخدام (مثل المصفوفات والأعداد الصحيحة والسلاسل).
أسهل طريقة لاستخدام Phan هي عبر Composer.
composer require phan/phan
بعد تثبيت Phan، ستحتاج إلى إنشاء ملف .phan/config.php في مشروعك لإخبار Phan بكيفية تحليل كود المصدر الخاص بك. بمجرد تكوينه، يمكنك تشغيله عبر ./vendor/bin/phan .
يعتمد Phan 5 على PHP 7.2+ مع امتداد php-ast (يفضل 1.1.1+) ويدعم تحليل تركيب PHP الإصدار 7.0-8.2. يمكن العثور على تعليمات التثبيت لـ php-ast هنا. (يمكن استخدام Phan بدون php-ast باستخدام خيار CLI --allow-polyfill-parser ، ولكن هناك اختلافات طفيفة في تحليل تعليقات المستند)
لدى Wiki مزيد من المعلومات حول استخدام Phan.
يستطيع فان إجراء الأنواع التالية من التحليلات:
object ، void ، iterable ، ?T ، [$x] = ...; ، إزاحات السلسلة السالبة، وصيد الاستثناءات المتعددة، وما إلى ذلك)--dead-code-detection )--unused-variable-detection )--redundant-condition-detection )use غير المستخدمة. يمكن إصلاح هذه الأنواع وبعض أنواع المشكلات الأخرى تلقائيًا باستخدام --automatic-fix .@template ).int[] و UserObject[] و array<int,UserObject> وما إلى ذلك.array{key:string,otherKey:?stdClass} وما إلى ذلك (داخليًا وفي علامات PHPDoc) ويدعم هذا أيضًا الإشارة إلى أن حقول شكل المصفوفة اختيارية عبر array{requiredKey:string,optionalKey?:string} (مفيدة ل @param )@deprecated لإهمال الفئات والأساليب والوظائف@internal للعناصر (مثل ثابت أو وظيفة أو فئة أو ثابت فئة أو خاصية أو طريقة) باعتبارها داخلية للحزمة التي تم تعريفها فيها.@suppress <ISSUE_TYPE> لقمع المشكلات.@property <union_type> <variable_name> )@method <union_type> <method_name>(<union_type> <param1_name>) )class_alias (تجريبية، معطلة بشكل افتراضي)@phan-closure-scope (مثال)array_map و array_filter ووظائف المصفوفة الداخلية الأخرى.pcntl )راجع أنواع مشكلات Phan للحصول على أوصاف وأمثلة لجميع المشكلات التي يمكن لـ Phan اكتشافها. قم بإلقاء نظرة على PhanIssue لمعرفة تعريف كل نوع خطأ.
ألقِ نظرة على البرنامج التعليمي لتحليل قاعدة أكواد برمجية كبيرة غير متقنة للتعرف على الشكل الذي قد تبدو عليه عملية إجراء التحليل المستمر بالنسبة لك.
يمكن استخدام Phan من العديد من المحررين وIDEs للتحقق من الأخطاء، ودعم "الانتقال إلى التعريف"، وما إلى ذلك عبر بروتوكول خادم اللغة. يمكن للمحررين والأدوات أيضًا طلب تحليل الملفات الفردية في المشروع باستخدام الوضع الخفي الأبسط.
راجع دليل الاختبارات للحصول على بعض الأمثلة على عمليات الفحص المختلفة.
Phan غير كامل ولا ينبغي استخدامه لإثبات أن نظام توجيه الصواريخ المبني على PHP خالي من العيوب.
تم توفير ميزات تحليل إضافية بواسطة المكونات الإضافية.
{ throw new Exception("Message"); return $value; } )*printf() مقابل الوسائط المتوفرة (بالإضافة إلى التحقق من الأخطاء الشائعة)preg_*()@suppress التي لم تعد هناك حاجة إليها.مثال: ملحقات فان للتحليل الذاتي.
بعد تثبيت Phan، يجب تكوين Phan بتفاصيل حول مكان العثور على التعليمات البرمجية لتحليلها وكيفية تحليلها. أسهل طريقة لإخبار Phan بمكان العثور على الكود المصدري هي إنشاء ملف .phan/config.php . قد يبدو ملف .phan/config.php البسيط كما يلي.
<?php
/ * *
* This configuration will be read and overlaid on top of the
* default configuration . Command line arguments will be applied
* after this file is read .
* /
return [
// Supported values : `'5.6'` , `'7.0'` , `'7.1'` , `'7.2'` , `'7.3'` , `'7.4'` ,
// `'8.0'` , `'8.1'` , `'8.2'` , `'8.3'` , `null` .
// If this is set to `null` ,
// then Phan assumes the PHP version which is closest to the minor version
// of the php executable used to execute Phan .
" target_php_version " => null ,
// A list of directories that should be parsed for class and
// method information . After excluding the directories
// defined in exclude_analysis_directory_list , the remaining
// files will be statically analyzed for errors .
//
// Thus , both first - party and third - party code being used by
// your application should be included in this list .
' directory_list ' => [
' src ' ,
' vendor/symfony/console ' ,
],
// A directory list that defines files that will be excluded
// from static analysis , but whose class and method
// information should be included .
//
// Generally , you ' ll want to include the directories for
// third - party code ( such as "vendor/" ) in this list .
//
// n . b .: If you ' d like to parse but not analyze 3 rd
// party code , directories containing that code
// should be added to the `directory_list` as
// to `exclude_analysis_directory_list` .
" exclude_analysis_directory_list " => [
' vendor/ '
],
// A list of plugin files to execute .
// Plugins which are bundled with Phan can be added here by providing their name
// ( e . g . 'AlwaysReturnPlugin' )
//
// Documentation about available bundled plugins can be found
// at https : // github . com / phan / phan / tree / v5 / . phan / plugins
//
// Alternately , you can pass in the full path to a PHP file
// with the plugin ' s implementation .
// ( e . g . 'vendor/phan/phan/.phan/plugins/AlwaysReturnPlugin.php' )
' plugins ' => [
// checks if a function , closure or method unconditionally returns .
// can also be written as 'vendor/phan/phan/.phan/plugins/AlwaysReturnPlugin.php'
' AlwaysReturnPlugin ' ,
' DollarDollarPlugin ' ,
' DuplicateArrayKeyPlugin ' ,
' DuplicateExpressionPlugin ' ,
' PregRegexCheckerPlugin ' ,
' PrintfCheckerPlugin ' ,
' SleepCheckerPlugin ' ,
// Checks for syntactically unreachable statements in
// the global scope or function bodies .
' UnreachableCodePlugin ' ,
' UseReturnValuePlugin ' ,
' EmptyStatementListPlugin ' ,
' LoopVariableReusePlugin ' ,
],
];قم بإلقاء نظرة على إنشاء ملف التكوين وتعزيز التحليل بشكل متزايد لمزيد من التفاصيل.
سيؤدي تشغيل phan --help إلى إظهار معلومات الاستخدام وخيارات سطر الأوامر.
يقرأ Phan ويفهم معظم التعليقات التوضيحية لأنواع PHPDoc بما في ذلك أنواع Union (مثل int|MyClass|string|null ) وأنواع المصفوفات العامة (مثل int[] أو string[]|MyClass[] أو array<int,MyClass> ).
قم بإلقاء نظرة على التعليق التوضيحي على كود المصدر الخاص بك وحول أنواع الاتحاد للحصول على بعض المساعدة للبدء في تحديد الأنواع في التعليمات البرمجية الخاصة بك.
يدعم Phan التعليقات التوضيحية على النمط (int|string)[] ، ويمثلها داخليًا كـ int[]|string[] (يتم التعامل مع كلا التعليقين التوضيحيين مثل المصفوفة التي قد تحتوي على أعداد صحيحة و/أو سلاسل). عندما يكون لديك مصفوفات من أنواع مختلطة، فما عليك سوى استخدام array .
يعرض التعليمة البرمجية التالية التعليقات التوضيحية المتنوعة المدعومة.
/ * *
* @ return void
* /
function f () {}
/ * * @ deprecated * /
class C {
/ * * @ var int * /
const C = 42 ;
/ * * @ var string [] | null * /
public $ p = null ;
/ * *
* @ param int | null $ p
* @ return string [] | null
* /
public static function f ( $ p ) {
if ( is_null ( $ p )) {
return null ;
}
return array_map (
/ * * @ param int $ i * /
function ( $ i ) {
return " thing $ i " ;
},
range ( 0 , $ p )
);
}
}تمامًا كما هو الحال في PHP، يمكن إلغاء أي نوع في تعريف الدالة مما يعني أيضًا السماح بتمرير قيمة فارغة لتلك المعلمة.
يتحقق Phan من نوع كل عنصر من عناصر المصفوفات (بما في ذلك المفاتيح والقيم). من الناحية العملية، هذا يعني أن [$int1=>$int2,$int3=>$int4,$int5=>$str6] يُنظر إليه على أنه array<int,int|string> ، والذي يمثله Phan array<int,int>|array<int,string> . سيتم تمثيل [$strKey => new MyClass(), $strKey2 => $unknown] كـ array<string,MyClass>|array<string,mixed> .
[12,'myString'] داخليًا كأشكال مصفوفة مثل array{0:12,1:'myString'} لا يتتبع هذا المحلل الثابت التضمينات أو يحاول اكتشاف سحر أداة التحميل التلقائي. فهو يتعامل مع جميع الملفات التي ترميها عليه كتطبيق واحد كبير. بالنسبة للكود المغلف في الفئات، يعمل هذا بشكل جيد. بالنسبة للتعليمات البرمجية التي يتم تشغيلها في النطاق العالمي، يصبح الأمر صعبًا بعض الشيء لأن الترتيب مهم. إذا كان لديك ملف index.php يتضمن ملفًا يقوم بتعيين مجموعة من المتغيرات العامة وحاولت بعد ذلك الوصول إليها بعد include(...) في index.php فلن يعرف المحلل الثابت أي شيء عن هذه المتغيرات.
من الناحية العملية، يعني هذا ببساطة أنه يجب عليك وضع نقاط الدخول وأي ملفات تحدد الأشياء في النطاق العالمي في أعلى قائمة الملفات الخاصة بك. إذا كان لديك ملف config.php يقوم بتعيين المتغيرات العامة التي يحتاجها كل شيء آخر، فيجب عليك وضع ذلك أولاً في القائمة متبوعة بنقاط الإدخال المختلفة، ثم جميع ملفات مكتبتك التي تحتوي على فئاتك.
قم بإلقاء نظرة على دليل المطورين لـ Phan للحصول على المساعدة في بدء القرصنة على Phan.
عندما تجد مشكلة، يرجى تخصيص الوقت لإنشاء مقتطف رمز صغير يوضح الخطأ. وبمجرد الانتهاء من ذلك، قم بإصلاحه. ثم قم بتحويل مقتطف الكود الخاص بك إلى اختبار وأضفه إلى الاختبارات ثم ./test وأرسل PR مع الإصلاح والاختبار. وبدلاً من ذلك، يمكنك فتح مشكلة تحتوي على التفاصيل.
لتشغيل اختبارات وحدة Phan، ما عليك سوى تشغيل ./test .
لتشغيل جميع اختبارات وحدة Phan واختبارات التكامل، قم بتشغيل ./tests/run_all_tests.sh
ونحن ملتزمون بتعزيز مجتمع الترحيب. يتعين على أي مشارك ومساهم الالتزام بقواعد السلوك الخاصة بنا.
يتطلب هذا إصدارًا محدثًا من Firefox/Chrome وما لا يقل عن 4 جيجابايت من ذاكرة الوصول العشوائي المجانية. (هذا تنزيل بحجم 15 ميغابايت)
قم بتشغيل Phan بالكامل في متصفحك.
