standar dan panduan bagi backend engineer DOT Indonesia atau vendor yang menggunakan PHP atau framework PHP sebagai server side programming.
PHP & Framework Quality Guideline DOT Indonesia merupakan sebuah standar dan panduan bagi backend engineer DOT Indonesia atau vendor yang menggunakan PHP atau framework PHP sebagai server side programming.
Kunjungi Development Stack & Tools untuk melihat daftar aplikasi dan perangkat development yang dibutuhkan
Hal-hal berikut ini seharusnya dimasukkan ke dalam list .gitignore
dan tidak boleh di push ke dalam repository:
vendors
, node_modules
.env
Gunakan penamaan variable atau method yang singkat & jelas, serta tidak membingungkan.
good:
$user
, $storeData
, $debetAccount
bad:
$aaaa
, $name1
, $thisistoloongvariableyoumaynotseeit
Variable atau method menggunakan format CamelCase
Error message / debug message hanya boleh ditampilkan pada mode development
atau staging
. Gunakan default error message ketika di mode production
Tidak meletakkan endpoint atau informasi credential yang bersifat private secara hard code di dalam source code. Contoh:
protected $secretKey = 'ThisIsN0tSuppOs3dToBeHere';
protected $ProdUrl = 'https://someprivateip/api';
Manfaatkan file .env
untuk menyimpan value sensitif tanpa terekspose di dalam source code.
Source code tidak boleh mengandung backdoor atau shell script yang berbahaya. Jika menggunakan script dari referensi luar, pastikan script tersebut aman & verified.
Semua form harus menggunakan CSRF Protection
Harus mengikuti PHP PSR-1: Basic Coding Standard
Harus Mengikuti PHP PSR-2: Coding Style Guide
PSR-2 overview:
<?php
namespace Vendor\Package;
use FooInterface;
use BarClass as Bar;
use OtherVendor\OtherPackage\BazClass;
class Foo extends Bar implements FooInterface
{
public function sampleMethod($a, $b = null)
{
if ($a === $b) {
bar();
} elseif ($a > $b) {
$foo->bar($arg1);
} else {
BazClass::bar($arg2, $arg3);
}
}
final public static function bar()
{
// method body
}
}
Jika menggunakan autoloading, ikuti standard PSR-4: Autoloading
Agar source code lebih mudah dibaca dan dipahami sertakan DockBlock
pada fungsi atau attribute. Manfaatkan DockBlock untuk menginformasikan proses, variable, dan output yang digunakan. Acuan penggunaan DockBlock dapat dilihat di PHPDOC - DOCKBLOCK Basic Syntax
Overview:
<?php
class Foo {
/**
* @var string
*/
protected $propertiesOne;
/**
* @var string
*/
protected $propertiesTwo;
/**
* This is description of this class
* this class may use recursion bla bla bla
*
* @param string $arg1
* @param integer $arg2
* @return array
*/
public function bar($arg1, $arg2)
{
// some code
}
}
Tidak boleh ada Dead Code
saat merge ke branch master
. Dead Code
adalah source code (method, attributes, class) yang sudah tidak digunakan akan tetapi masih tersimpan di dalam codebase dan biasanya hanya dinonaktifkan menggunakan comment
Overview:
<?php
class Foo {
/**
* This is description of this class
* this class may use recursion bla bla bla
*
* @param string $arg1
* @param integer $arg2
* @return array
*/
public function bar($arg1, $arg2)
{
// some code
}
//public function deadcode($arg1, $arg2)
//{
// some DEAD CODE
//
//}
}
Gunakan fitur Database Transaction
untuk operasi persistence yang menggunakan lebih dari 1 tabel database.
overview:
try {
DB::beginTransaction();
// first persistence operation
// second persistence operation
// operation success, then commit transaction
DB::commit();
return true;
} catch(\Exception $e) {
// if error happened, rollback transaction
DB::rollback();
return false;
}
Untuk aplikasi yang kompleks, kumpulkan class Model
, Controller
, atau Views
dalam direktori tersendiri sesuai dengan konteks / domain aplikasinya.
simple case:
├── app
│ ├── Http
│ │ ├── Controller
│ │ │ ├── Authentication
│ │ │ ├── OrderManagement
│ │ │ │ ├── OrderController.php
│ │ │ │ ├── ReportOrderController.php
├── Model
│ ├── User.php
│ ├── Order.php
├── resources
│ ├── views
│ │ ├── dashboard
│ │ ├── administrator
│ │ │ ├── index.blade.php
│ │ │ ├── create.blade.php
│ │ │ ├── edit.blade.php
│ │ │ ├── detail.blade.php
│ │ ├── ordermanagement
Untuk efisiensi dan efektivitas masa development, gunakan library yang sudah umum digunakan dengan kriteria sebagai berikut:
Gunakan perintah berikut untuk optimasi saat deployment Laravel terutama di staging & production:
php artisan route:cache
php artisan config:cache
composer dumpautoload --classmap-authoritative
khusus untuk
route:cache
tidak boleh ada fungsi closure pada file route
Manfaatkan fitur event
untuk fungsi yang tidak dependen dengan hasil outputnya. Misal: kirim email, logging, push notification. Dokumentasi event Laravel
Gunakan eager loading
untuk optimasi penggunaan relationship di eloquent. Baca implementasi Eager Loading.
migration
untuk pembuatan atau modifikasi skema database saat development baik itu menambah kolom, edit kolom, hapus kolom, atau modifikasi index.php artisan migrate:rollback
lalu php artisan migrate
lagi. Baca implementasi migration
Dalam kasus tertentu pengambilan data menggunakan Eloquent
akan memakan terlalu banyak resource. Bentuk optimalisasinya bisa dari salah satu cara berikut:
relationship
dengan menggunakan operasi join
sehingga query cukup dijalankan satu kali.Query Builder
try - catch
untuk handling exception terutama di operasi yang berkaitan dengan I/O seperti database, HTTP request, file, service layer.error exception
yang terjadi & memungkinkan aplikasi melakukan aksi tertentu terkait error tersebut.DONT:
/**
* This is description of this class
*
* @param Request $request
* @return Response
*/
public function register(Request $request)
{
try {
$service = $this->applicationService->registerUser($user);
return response()->json($service);
} catch(Exception $e) {
return response()->json(['error' => $e->getMessage()]);
}
}
DO:
report($exception)
untuk menulis detail exception di file laravel.log
./**
* This is description of this class
*
* @param Request $request
* @return Response
*/
public function register(Request $request)
{
try {
$service = $this->applicationService->registerUser($user);
return response()->json($service);
} catch(Exception $e) {
report($e);
return response()->json(['error' => "Human Friendly Message"]);
}
}
Semua konfigurasi credential dari pihak ketiga harus diset melalui config/service.php
dan value harus diambil dari file .env
overview:
<?php
// config/service.php
return [
'zenziva' => [
'userkey' => env('ZENZIVA_USER', ''),
'passkey' => env('ZENZIVA_PASS', ''),
'subdomain' => '',
'masking' => false,
],
'tcast' => [
'user' => env('TCAST_USER', ''),
'password' => env('TCAST_PASSWORD', ''),
'senderid' => env('TCAST_SENDERID', ''),
]
];
Saat production mode pastikan hal berikut:
APP_ENV=production
APP_DEBUG=false
APP_KEY
harus di generate ulang menggunakan perintah php artisan key:generate
Berikut merupakan daftar library / package PHP & Laravel yang biasa digunakan dalam proses development.
Internal engineer silakan berkontribusi untuk membuat guideline ini bisa lebih lengkap dan lebih baik. Caranya:
Jika ada pertanyaan atau permintaan update silakan untuk mengajukan issue di repository terkait.