WordPress Coding Standards [PHP]

ว่าจะเริ่มพัฒนา plugin ของ WordPress เลยต้องมาดูรูปแบบมาตรฐานในการเขียนโค้ดของ WordPress ซะก่อนจะได้เดินไปตามร่องตามรอยของ WordPress ที่เค้าได้วางไว้ ซึ่งจะแบ่งออกเป็น 3 ส่วน คือ PHP, HTML และ CSS ในบทความนี้จะพูดเฉพาะที่เป็น PHP ครับ

1. การใช้ single quote และ double quote ควรใช้ให้เหมาะสมในกรณีที่เราต้องการให้แสดงเฉยๆ โดยที่ไม่มีตัวแปรของ PHP อยู่ข้างในก็ควรใช้ single quote เพราะถ้าเป็นการแสดงลิงค์หรือแท็กอื่นที่มี attribute เราจะได้ไม่ต้อง escape double quote

2. การย่อหน้า (Indentation) ให้ใช้ tab ในการย่อหน้าไม่ใช่ space ซึ่งหลักการของ WordPress คือ tab ควรจะถูกใช้ตอนเริ่มบรรทัด ส่วน space ใช้ในเนื้อหาของบรรทัด (mid-line)

3. การใช้งานเครื่องหมายปีกกา (Brace style) ควรใช้เมื่อ block นั้นมีหลายบรรทัด เช่น

if ( condition ) {
    action1();
    action2();
} elseif ( condition2 & condition3 ) {
    action3();
    action4();
} else {
    defaultaction();
}

ส่วน block ที่มีแค่หนึ่่งบรรทัดก็ไม่ต้องใช้วงเล็บปีกกาครอบก็ได้เพื่อความกะทัดรัด

if ( condition )
    action1();
elseif ( condition2 )
    action2();
else
    action3();

ถ้า block ที่เกี่ยวข้องมีหลายบรรทัดก็ควรครอบด้วยวงเล็บปีกกา

if ( condition ) {
    action1();
} elseif ( condition2 ) {
    action2a();
    action2b();
}

ส่วนลูปต่างๆ (while, for, foreach,…) ต้องครอบด้วยวงเล็บปีกกา

foreach ( $items as $item ) {
    process_item( $item );
}

4. include_once vs require_once ศึกษาความแตกต่างระหว่าง include_once กับ require_once แล้วใช้อย่างเหมาะสม สองอย่างนี้จะจัดการกับข้อผิดพลาดที่เกิดขึ้นต่างกัน include จะฟ้องออกมาเป็น Warning ในขณะที่ require จะฟ้องออกมาเป็น Fatal Error ซึ่งเจ้า fatal error จะทำให้ script หยุดทำงาน

5. Regular Expressions ไม่ควรใช้ /e ควรใช้ฟังก์ชั่น preg_replace_callback แทน

6. ไม่ใช้ Shorthand PHP tags จะต้องใช้ full PHP tags เสมอ
ถูกต้อง

<?php ... ?>

ไม่ควรใช้

<? .. ?>
<?=$var;?>

7. ลบช่องว่างที่ต่อท้ายออก (Remove Trailing Spaces) ถ้ามีการปิดแท็ก PHP ที่บรรทัดสุดท้ายของไฟล์ PHP (แนะนำให้ไม่ต้องปิด) จะต้องลบช่องว่างที่ต่อจากแท็กปิดออก และลบช่องว่างทึ่ต่อท้ายแต่ละบรรทัดของโค้ดออกด้วย

8. การใช้ช่องว่าง (Space Usage) จะต้องมีช่องว่างหลังเครื่องหมาย comma (,) ทั้งสองข้างของเครื่องหมายเปรียบเทียบและเครื่องหมายกำหนดค่า (assignment operators)

x == 23
foo && bar
! foo
array( 1, 2, 3 )
$baz . '-5'
$term .= 'X'

ใส่ช่องว่างทั้งตอนเปิดและปิดวงเล็บของ if, elseif, foreach, for และ switch block

foreach ( $foo as $bar ) { ...

การประกาศฟังก์ชัน

function my_function( $param1 = 'foo', $param2 = 'bar' ) { ...

การเรียกใช้ฟังก์ชัน

my_function( $param1, func_param( $param2 ) );

เมื่อใช้เครื่องหมายเปรียบเทียบ (logical comparisons)

if ( ! $foo ) { ...

เมื่อมีการใช้ type casting

foreach ( (array) $foo as $bar ) { ...

$foo = (boolean) $bar;

กรณีอ้างถึงค่าในอะเรย์ (array items) ก็ให้ใส่ช่องว่างครอบ index ถ้าใช้ตัวแปรมาอ้างถึง index

$x = $foo['bar']; // ใช้

$x = $foo[ 'bar' ]; // ไม่ใช้

$x = $foo[ $bar ]; // ใช้

$x = $foo[$bar]; // ไม่ใช้

9. การตั้งชื่อ (Naming Conventions) ชื่อตัวแปร ฟังก์ชัน action ให้ใช้ตัวพิมพ์เล็ก (lowercase) และขั้นด้วยเครื่องหมาย _ (underscore)

function some_name( $some_variable ) { [...] }

ชื่อคลาส (Class names) จะต้องขึ้นต้นด้วยตัวพิมพ์ใหญ่ (Capitalized) และขั้นด้วยเครื่องหมาย _ (underscore) ตัวย่อให้ใช้ตัวพิมพ์ใหญ่ทั้งหมด

class Walker_Category extends Walker { [...] }
class WP_HTTP { [...] }

ชื่อไฟล์ใช้ตัวพิมพ์เล็กทั้งหมดขั้นคำด้วยเครื่องหมายขีดกลาง (hyphens)

my-plugin-name.php

ส่วนไฟล์ของคลาสจะต้องตั้งตามชื่อคลาสและเพิ่ม class- เข้าไปข้างหน้าเปลี่ยนจาก underscore ในชื่อคลาสเป็นเครื่องหมายขีดกลาง (hyphens) เช่น WP_Error ก็จะเป็น

class-wp-error.php

ไฟล์ template ที่อยู่ในโฟลเดอร์ wp-includes จะต้องมี -template ต่อท้าย

general-template.php

10. Self-Explanatory Flag Values for Function Arguments ในการรับค่าจาก argument ควรใช้เป็น string เพื่อจะได้อ่านโค้ดเข้าใจได้ง่ายเมื่อมีการเรียกใช้ฟังก์ชัน
//ไม่ควรใช้

function eat( $what, $slowly = true ) {
...
}
eat( 'mushrooms' );
eat( 'mushrooms', true ); // true หมายถึงอะไร?
eat( 'dogfood', false ); // false หมายถึงอะไร? ตรงข้ามกับ true รึป่าว?

//ควรใช้

function eat( $what, $speed = 'slowly' ) {
...
}
eat( 'mushrooms' );
eat( 'mushrooms', 'slowly' );
eat( 'dogfood', 'fast' );

11. Yoda Conditions เมื่อมีการเปรียบเทียบค่าต้องให้ตัวแปรอยู่ด้านขวา ค่าคงที่หรือ literals อยู่ด้านซ้าย

if( true == $the_force ){
  $victorious = you_will( $be );
}

แล้วทำไมต้องให้ค่าคงที่อยู่ด้านซ้ายด้วยล่ะ จากตัวอย่างด้านบนถ้าเราพิมพ์เครื่องหมายเท่ากับใน if เป็น ( true = $the_force ) จะทำให้ parse error เราก็จะสามารถแก้ไขให้ถูกต้องได้ แต่ถ้าให้ตัวแปรอยู่ด้านซ้าย จะทำให้กลายเป็นการกำหนดค่าให้ตัวแปร ซึ่งจะได้ผลออกมาเป็น true เสมอ มันก็จะทำให้โปรแกรมทำงานไม่ถูกต้อง