{"id":18961716,"url":"https://github.com/pt-dot/php-guidelines","last_synced_at":"2025-04-19T11:41:31.372Z","repository":{"id":49306824,"uuid":"143324907","full_name":"pt-dot/php-guidelines","owner":"pt-dot","description":"standar dan panduan bagi backend engineer DOT Indonesia atau vendor yang menggunakan PHP atau framework PHP sebagai server side programming.","archived":false,"fork":false,"pushed_at":"2019-01-02T09:59:52.000Z","size":7,"stargazers_count":48,"open_issues_count":0,"forks_count":22,"subscribers_count":3,"default_branch":"master","last_synced_at":"2025-03-29T07:22:43.395Z","etag":null,"topics":["coding-standards","guidelines","laravel","php"],"latest_commit_sha":null,"homepage":null,"language":null,"has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/pt-dot.png","metadata":{"files":{"readme":"readme.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2018-08-02T17:20:49.000Z","updated_at":"2025-01-18T04:00:36.000Z","dependencies_parsed_at":"2022-09-17T15:22:27.173Z","dependency_job_id":null,"html_url":"https://github.com/pt-dot/php-guidelines","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pt-dot%2Fphp-guidelines","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pt-dot%2Fphp-guidelines/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pt-dot%2Fphp-guidelines/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pt-dot%2Fphp-guidelines/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/pt-dot","download_url":"https://codeload.github.com/pt-dot/php-guidelines/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":249195422,"owners_count":21228197,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["coding-standards","guidelines","laravel","php"],"created_at":"2024-11-08T14:14:05.684Z","updated_at":"2025-04-16T04:33:01.586Z","avatar_url":"https://github.com/pt-dot.png","language":null,"readme":"# PHP \u0026 Framework Quality Guideline\n\n**PHP \u0026 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.\n\nKunjungi [Development Stack \u0026 Tools](https://github.com/pt-dot/development-stack-tools) untuk melihat daftar aplikasi dan perangkat development yang dibutuhkan\n\n---\n# Table of Contents\n1. [General Standard](#1-general-standard)\n2. [PHP Coding Standard](#2-php-coding-standard)\n3. [Laravel / Lumen / PHP Framework Engineering Guideline](#3-laravel--lumen--php-framework-engineering-guideline)\n4. [Package \u0026 Libraries](#4-package--libraries)\n---\n\n## 1. General Standard\n\n### a .gitignore\nHal-hal berikut ini seharusnya dimasukkan ke dalam list `.gitignore` dan tidak boleh di push ke dalam repository:\n\n+ direktori `vendors`, `node_modules`\n+ file upload dari user\n+ file `.env`\n+ Informasi credential penting atau krusial\n\n### b. Variable Naming Conversion\nGunakan penamaan variable atau method yang singkat \u0026 jelas, serta tidak membingungkan.\n\n**good**:\n\n`$user`, `$storeData`, `$debetAccount`\n\n**bad**:\n\n`$aaaa`, `$name1`, `$thisistoloongvariableyoumaynotseeit`\n\n### c. CamelCase\nVariable atau method menggunakan format `CamelCase`\n\n### d. Error message\nError message / debug message hanya boleh ditampilkan pada mode `development` atau `staging`. Gunakan **default error message** ketika di mode `production`\n\n### e. Sensitive Information\nTidak meletakkan endpoint atau informasi credential yang bersifat private secara hard code di dalam source code. Contoh:\n\n```php\nprotected $secretKey = 'ThisIsN0tSuppOs3dToBeHere';\n\nprotected $ProdUrl = 'https://someprivateip/api';\n```\n\nManfaatkan file `.env` untuk menyimpan value sensitif tanpa terekspose di dalam source code.\n\n### f. Secure \u0026 Verified Code\nSource code tidak boleh mengandung *backdoor* atau shell script yang berbahaya.\nJika menggunakan script dari referensi luar, pastikan script tersebut aman \u0026 verified.\n\n### g. CSRF Token\nSemua form harus menggunakan `CSRF Protection`\n\n---\n\n## 2. PHP Coding Standard\n\n### a. PSR-1\nHarus mengikuti PHP [PSR-1: Basic Coding Standard](http://www.php-fig.org/psr/psr-1/)\n\n### b. PSR-2\nHarus Mengikuti PHP [PSR-2: Coding Style Guide](http://www.php-fig.org/psr/psr-2/)\n\nPSR-2 overview:\n```php\n\u003c?php\nnamespace Vendor\\Package;\n\nuse FooInterface;\nuse BarClass as Bar;\nuse OtherVendor\\OtherPackage\\BazClass;\n\nclass Foo extends Bar implements FooInterface\n{\n    public function sampleMethod($a, $b = null)\n    {\n        if ($a === $b) {\n            bar();\n        } elseif ($a \u003e $b) {\n            $foo-\u003ebar($arg1);\n        } else {\n            BazClass::bar($arg2, $arg3);\n        }\n    }\n\n    final public static function bar()\n    {\n        // method body\n    }\n}\n```\n\n### c. PSR-4\nJika menggunakan autoloading, ikuti standard [PSR-4: Autoloading](http://www.php-fig.org/psr/psr-4/)\n\n### d. DockBlock (/JavaDoc)\nAgar 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](http://docs.phpdoc.org/references/phpdoc/basic-syntax.html)\n    \nOverview:\n```php\n\u003c?php\n\nclass Foo {\n    \n    /**\n    * @var string\n    */\n    protected $propertiesOne;\n\n    /**\n    * @var string\n    */\n    protected $propertiesTwo;\n\n    /**\n    * This is description of this class\n    * this class may use recursion bla bla bla\n    *\n    * @param string $arg1\n    * @param integer $arg2\n    * @return array\n    */\n    public function bar($arg1, $arg2)\n    {\n        // some code\n\n    }\n}\n```\n\n### e. Dead Code\nTidak 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`\n\nOverview:\n\n```php\n\u003c?php\n\nclass Foo {\n    \n    /**\n    * This is description of this class\n    * this class may use recursion bla bla bla\n    *\n    * @param string $arg1\n    * @param integer $arg2\n    * @return array\n    */\n    public function bar($arg1, $arg2)\n    {\n        // some code\n\n    }\n    \n    //public function deadcode($arg1, $arg2)\n    //{\n    // some DEAD CODE\n    //\n    //}\n}\n```\n\n### f. Penggunaan Framework\n- Penggunaan PHP framework yang disarankan adalah [Laravel](https://laravel.com/) atau microframework [Lumen](https://lumen.laravel.com/).\n- Jika terpaksa menggunakan framework lain, mohon kordinasikan dengan AVP.\n\n---\n\n# 3. Laravel / Lumen / PHP Framework Engineering Guideline\n\n### a. Framework Version\n- Untuk project yang bersifat longterm disarankan menggunakan framework versi LTS (Long Term Support) atau disesuaikan dengan kebutuhan.\n- Jika tidak ada kebutuhan URGENT, dilarang mengupgrade versi framework pada project yang sedang berjalan.\n\n### b. DB Transaction\nGunakan fitur `Database Transaction` untuk operasi persistence yang menggunakan lebih dari 1 tabel database.\n\noverview:\n\n```php\n\ntry {\n    DB::beginTransaction();\n\n    // first persistence operation\n\n    // second persistence operation\n\n    // operation success, then commit transaction\n    DB::commit();\n    return true;\n} catch(\\Exception $e) {\n    // if error happened, rollback transaction\n    DB::rollback();\n    return false;\n}\n```\n\n### c. File Grouping\nUntuk aplikasi yang kompleks, kumpulkan class `Model`, `Controller`, atau `Views` dalam direktori tersendiri sesuai dengan konteks / domain aplikasinya.\n\nsimple case:\n\n```bash\n├── app\n│   ├── Http\n│   │   ├── Controller\n│   │   │   ├── Authentication\n│   │   │   ├── OrderManagement\n│   │   │   │   ├── OrderController.php\n│   │   │   │   ├── ReportOrderController.php\n├── Model\n│   ├── User.php\n│   ├── Order.php\n├── resources\n│   ├── views\n│   │   ├── dashboard\n│   │   ├── administrator\n│   │   │   ├── index.blade.php\n│   │   │   ├── create.blade.php\n│   │   │   ├── edit.blade.php\n│   │   │   ├── detail.blade.php\n│   │   ├── ordermanagement\n\n```\n\n\n### d. Penggunaan Library\nUntuk efisiensi dan efektivitas masa development, gunakan *library* yang sudah umum digunakan dengan kriteria sebagai berikut:\n\n+ library aktif di maintain oleh kontributor / owner\n+ Sesuai dengan kebutuhan engineering project\n+ Sesuai dengan development stack yang sedang digunakan\n+ Penggunaan library harus benar-benar dapat mempermudah proses development\n\n### e. Optimasi Laravel\nGunakan perintah berikut untuk optimasi saat deployment Laravel terutama di staging \u0026 production:\n\n```bash\nphp artisan route:cache\nphp artisan config:cache\ncomposer dumpautoload --classmap-authoritative\n```\n\u003e khusus untuk `route:cache` tidak boleh ada fungsi closure pada file route\n\n### f. Event\nManfaatkan fitur `event` untuk fungsi yang tidak dependen dengan hasil outputnya. Misal: kirim email, logging, push notification. [Dokumentasi event Laravel](https://laravel.com/docs/5.6/events)\n\n### g. Eloquent : Eager Loading\nGunakan `eager loading` untuk optimasi penggunaan relationship di eloquent. Baca implementasi [Eager Loading](https://laravel.com/docs/5.6/eloquent-relationships#eager-loading).\n\n### h. DB Migration\n- Selalu (WAJIB) gunakan `migration` untuk pembuatan atau modifikasi skema database saat development baik itu menambah kolom, edit kolom, hapus kolom, atau modifikasi index. \n- Metode ini lebih baik daripada merubah satu file migration lalu menjalankan perintah `php artisan migrate:rollback` lalu `php artisan migrate` lagi. Baca implementasi [migration](https://laravel.com/docs/5.6/migrations)\n\n### i. Eloquent Optimization\nDalam kasus tertentu pengambilan data menggunakan `Eloquent` akan memakan terlalu banyak resource. Bentuk optimalisasinya bisa dari salah satu cara berikut:\n    \n+ Ganti `relationship` dengan menggunakan operasi `join` sehingga query cukup dijalankan satu kali.\n+ Ganti operasi menggunakan `Query Builder`\n\n### j. Try Catch , Report \u0026 Throw\n- Gunakan blok `try - catch` untuk handling exception terutama di operasi yang berkaitan dengan I/O seperti database, HTTP request, file, service layer.\n- Try \u0026 Catch berfungsi untuk menangkap `error exception` yang terjadi \u0026 memungkinkan aplikasi melakukan aksi tertentu terkait error tersebut.\n\n**DONT:**\n- Jangan biarkan technical error muncul / terbaca oleh client app/frontend.\n\n```php\n/**\n* This is description of this class\n*\n* @param Request $request\n* @return Response\n*/\npublic function register(Request $request)\n{\n    try {\n        $service = $this-\u003eapplicationService-\u003eregisterUser($user);\n        return response()-\u003ejson($service);\n    } catch(Exception $e) {\n        return response()-\u003ejson(['error' =\u003e $e-\u003egetMessage()]);\n    }\n}\n```\n\n**DO:**\n- Gunakan fitur `report($exception)` untuk menulis detail exception di file `laravel.log`.\n- Dan tampilkan pesan error yang human friendly ke client app / frontend.\n\n```php\n/**\n* This is description of this class\n*\n* @param Request $request\n* @return Response\n*/\npublic function register(Request $request)\n{\n    try {\n        $service = $this-\u003eapplicationService-\u003eregisterUser($user);\n        return response()-\u003ejson($service);\n    } catch(Exception $e) {\n        report($e);\n        return response()-\u003ejson(['error' =\u003e \"Human Friendly Message\"]);\n    }\n}\n```\n\n### k. Service Config\nSemua konfigurasi credential dari pihak ketiga harus diset melalui `config/service.php` dan value harus diambil dari file `.env`\n\noverview:\n\n```php\n\u003c?php\n// config/service.php\nreturn [\n    'zenziva'    =\u003e [\n        'userkey'   =\u003e env('ZENZIVA_USER', ''),\n        'passkey'   =\u003e env('ZENZIVA_PASS', ''),\n        'subdomain' =\u003e '',\n        'masking'   =\u003e false,\n    ],\n\n    'tcast'      =\u003e [\n        'user'     =\u003e env('TCAST_USER', ''),\n        'password' =\u003e env('TCAST_PASSWORD', ''),\n        'senderid' =\u003e env('TCAST_SENDERID', ''),\n    ]\n];\n```\n\n### l. ENV Production\nSaat production mode pastikan hal berikut:\n\n+ `APP_ENV=production`\n+ `APP_DEBUG=false`\n+ `APP_KEY` harus di generate ulang menggunakan perintah `php artisan key:generate`\n\n---\n\n## 4. Package \u0026 libraries\n\nBerikut merupakan daftar library / package PHP \u0026 Laravel yang biasa digunakan dalam proses development.\n\n1. [Laravel Debugbar](https://github.com/barryvdh/laravel-debugbar) - debug \u0026 monitor resource laravel\n2. [Laravel Flash](https://github.com/laracasts/flash) - Flash message wrapper\n3. [Laravel CORS](https://github.com/barryvdh/laravel-cors) - Cross Origin Resource Sharing header\n4. [Laravel Excel](https://laravel-excel.maatwebsite.nl/) - Spreadsheet wrapper\n5. [Socialite](https://github.com/laravel/socialite) - OAuth authentication untuk Facebook, Twitter, Google, Linkedin, Github, Bitbucket\n6. [L5 Repository](https://github.com/andersao/l5-repository) - Laravel 5 repository abstraction\n7. [Laravel Horizon](https://horizon.laravel.com/) - Dashboard untuk monitoring Laravel Queue dengan Redis\n8. [Codeception](https://codeception.com/) - Testing suite functional, API, Acceptance, Unit, dll\n9. [Doctrine DBAL](https://github.com/doctrine/dbal) - Doctrine Database Abstraction Layer untuk support laravel migration\n10. [Predis Laravel](https://github.com/nrk/predis) - Redis client untuk PHP\n11. [Laravel Sentry](https://sentry.io/for/laravel/) - Laravel error tracking menggunakan [sentry.io](https://sentry.io/for/laravel/)\n12. [Laravelcollective HTML](https://laravelcollective.com/docs/master/html) - HTML \u0026 form laravel wrapper\n13. [Faker](https://github.com/fzaninotto/Faker) - Untuk generate data dummy\n14. [Laravel Datatable](https://github.com/yajra/laravel-datatables) - Laravel JQuery datatable library\n15. [Laravel Tinker](https://github.com/laravel/tinker) - REPL untuk laravel\n16. [Laravel PDF](https://github.com/niklasravnsborg/laravel-pdf), [laravel dompdf](https://github.com/barryvdh/laravel-dompdf) - Wrapper \u0026 generate pdf di Laravel\n17. [Laravel Self Diagnosis](https://github.com/beyondcode/laravel-self-diagnosis) - self diagnosis test laravel\n18. [Intervention Image](http://image.intervention.io/) - PHP image handling \u0026 manipulation\n19. [JWT auth](https://github.com/tymondesigns/jwt-auth) - JWT wrapper untuk laravel \u0026 lumen\n20. [Laravel Passport](https://laravel.com/docs/5.6/passport) - Oauth2 Server Laravel\n21. [Laravel fractal wrapper](https://github.com/spatie/laravel-fractal) - Data transformasi wrapper laravel\n22. [Activity Log](https://github.com/spatie/laravel-activitylog) - Pencatatan aktivitas aplikasi ke dalam log\n23. [LDAP Authentication](https://github.com/pt-dot/ldap-auth) - integrasi auth dengan LDAP\n24. [Laravel Backup](https://github.com/spatie/laravel-backup) - backup direktori laravel \u0026 dump database\n25. [Laravel ER Diagram generator](https://github.com/beyondcode/laravel-er-diagram-generator) - Generate Entity Relationship Diagram dari Model Laravel\n\n---\n\n# Kontribusi\n\nInternal engineer silakan berkontribusi untuk membuat guideline ini bisa lebih lengkap dan lebih baik. Caranya:\n\n+ Fork repository ini\n+ Buat branch baru di repository hasil fork\n+ Edit file readme sesuai dengan kebutuhan lalu commit.\n+ Ajukan pull request\n+ AVP divisi atau VP of engineering akan melakukan review dan melakukan approval Pull Request.\n\nJika ada pertanyaan atau permintaan update silakan untuk mengajukan issue di repository terkait.\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpt-dot%2Fphp-guidelines","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fpt-dot%2Fphp-guidelines","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpt-dot%2Fphp-guidelines/lists"}