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
Phan 5 ขึ้นอยู่กับ PHP 7.2+ พร้อมด้วยส่วนขยาย php-ast (แนะนำให้ใช้ 1.1.1+) และรองรับการวิเคราะห์ไวยากรณ์ PHP เวอร์ชัน 7.0-8.2 คำแนะนำในการติดตั้งสำหรับ php-ast มีอยู่ที่นี่ (สามารถใช้ Phan โดยไม่ต้องใช้ php-ast ได้โดยใช้ตัวเลือก CLI --allow-polyfill-parser แต่การแยกวิเคราะห์ความคิดเห็นของ doc จะมีความแตกต่างกันเล็กน้อย)
วิกิมีข้อมูลเพิ่มเติมเกี่ยวกับการใช้พาน
พานสามารถทำการวิเคราะห์ประเภทต่างๆ ได้ดังต่อไปนี้:
object , void , iterable , ?T , [$x] = ...; , ออฟเซ็ตสตริงเชิงลบ, catches ข้อยกเว้นหลายรายการ เป็นต้น)--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 สามารถใช้จากโปรแกรมแก้ไขและ IDE ต่างๆ สำหรับการตรวจสอบข้อผิดพลาด การสนับสนุน "ไปที่คำจำกัดความ" ฯลฯ ผ่านทาง Language Server Protocol ผู้แก้ไขและเครื่องมือยังสามารถร้องขอการวิเคราะห์ไฟล์แต่ละไฟล์ในโปรเจ็กต์โดยใช้โหมด Daemon ที่ง่ายกว่า
ดูไดเร็กทอรีการทดสอบเพื่อดูตัวอย่างการตรวจสอบต่างๆ
Phan นั้นไม่สมบูรณ์และไม่ควรใช้เพื่อพิสูจน์ว่าระบบนำทางจรวดที่ใช้ PHP ของคุณไม่มีข้อบกพร่อง
ปลั๊กอินมีคุณสมบัติการวิเคราะห์เพิ่มเติม
{ throw new Exception("Message"); return $value; } )*printf() กับอาร์กิวเมนต์ที่ให้มา (รวมถึงการตรวจสอบข้อผิดพลาดทั่วไป)preg_*() นั้นถูกต้อง@suppress ที่ไม่จำเป็นอีกต่อไปตัวอย่าง: ปลั๊กอินของ Phan สำหรับการวิเคราะห์ตนเอง
หลังจากติดตั้ง 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 ประเภทใดก็ได้สามารถเป็นโมฆะในการประกาศฟังก์ชันได้ ซึ่งหมายความว่าสามารถส่งค่าโมฆะสำหรับพารามิเตอร์นั้นได้
พานตรวจสอบประเภทของทุกองค์ประกอบของอาร์เรย์ (รวมถึงคีย์และค่า) ในทางปฏิบัติหมายความว่า [$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'} เครื่องวิเคราะห์แบบคงที่นี้ไม่ได้ติดตามการรวมหรือพยายามค้นหาความมหัศจรรย์ของตัวโหลดอัตโนมัติ มันถือว่าไฟล์ทั้งหมดที่คุณส่งไปนั้นเป็นแอปพลิเคชั่นขนาดใหญ่ตัวเดียว สำหรับโค้ดที่ห่อหุ้มในคลาสจะใช้งานได้ดี สำหรับโค้ดที่ทำงานใน Global scope อาจจะยุ่งยากเล็กน้อยเนื่องจากลำดับมีความสำคัญ หากคุณมี index.php รวมถึงไฟล์ที่ตั้งค่าตัวแปรส่วนกลางจำนวนมาก แล้วคุณพยายามเข้าถึงตัวแปรเหล่านั้นหลังจาก include(...) ใน index.php ตัววิเคราะห์แบบคงที่จะไม่ทราบอะไรเกี่ยวกับสิ่งเหล่านี้
ในทางปฏิบัติ หมายความว่าคุณควรใส่จุดเริ่มต้นและไฟล์ใดๆ ที่ตั้งค่าสิ่งต่าง ๆ ในขอบเขตส่วนกลางไว้ที่ด้านบนสุดของรายการไฟล์ของคุณ หากคุณมี config.php ที่ตั้งค่าตัวแปรโกลบอลที่ทุกอย่างต้องการ คุณควรใส่สิ่งนั้นไว้ก่อนในรายการ ตามด้วยจุดเข้าต่างๆ ของคุณ จากนั้นจึงใส่ไฟล์ไลบรารีทั้งหมดที่มีคลาสของคุณ
ดูคู่มือนักพัฒนาสำหรับ Phan เพื่อรับความช่วยเหลือในการเริ่มต้นแฮ็ก Phan
เมื่อคุณพบปัญหา โปรดสละเวลาเพื่อสร้างข้อมูลโค้ดเล็กๆ น้อยๆ ที่แสดงจุดบกพร่อง และเมื่อคุณทำเสร็จแล้ว ให้แก้ไข จากนั้นเปลี่ยนข้อมูลโค้ดของคุณเป็นแบบทดสอบและเพิ่มลงในการทดสอบ จากนั้น ./test และส่ง PR พร้อมด้วยโปรแกรมแก้ไขและทดสอบของคุณ หรือคุณสามารถเปิดปัญหาพร้อมรายละเอียดได้
หากต้องการรันการทดสอบหน่วยของ Phan เพียงแค่รัน ./test test
หากต้องการรันการทดสอบหน่วยและการทดสอบการรวมทั้งหมดของ Phan ให้รัน ./tests/run_all_tests.sh
เรามุ่งมั่นที่จะส่งเสริมชุมชนที่เป็นมิตร ผู้เข้าร่วมและผู้มีส่วนร่วมจะต้องปฏิบัติตามหลักจรรยาบรรณของเรา
ต้องใช้ Firefox/Chrome เวอร์ชันล่าสุดและ RAM ว่างอย่างน้อย 4 GB (นี่คือการดาวน์โหลดขนาด 15 MB)
เรียกใช้ Phan ทั้งหมดในเบราว์เซอร์ของคุณ
