Apa PHPCS/WPCS? Fungsi Cara Install dan Menggunakannya

Kode plugin WordPress Anda lolos di localhost. Lalu reviewer WordPress.org menolak. Alasan: coding standards.

Itu bukan drama langka. Banyak developer Indonesia baru kenal phpcs wpcs setelah pull request ditolak, atau setelah merge merusak gaya kode tim.

PHPCS dan WPCS bukan “plugin cantik”. Keduanya adalah alat baca gaya kode. Mereka membandingkan file PHP Anda dengan aturan tertulis. Bukan menebak selera reviewer.

Artikel ini memetakan definisi akurat, manfaat, dan siapa yang memakai. Lanjut ke skill dasar serta risiko tanpa standar. Kemudian install di Windows, setup IDE, dan contoh nyata di Cursor serta VS Code.

Apa Itu PHPCS: Definisi PHP_CodeSniffer yang Akurat

PHPCS adalah kependekan dari PHP_CodeSniffer. Ini tool open source untuk menganalisis kode terhadap coding standard.

Definisi operasionalnya sederhana. PHPCS memecah file menjadi token. Lalu setiap aturan (sniff) memeriksa pola tertentu. Bila pola melanggar, PHPCS mencetak error atau warning.

PHPCS mendukung file PHP. Banyak setup juga memeriksa JavaScript dan CSS lewat sniff terkait. Fokus utama di dunia WordPress tetap file PHP plugin dan tema.

Satu hal yang sering salah paham:

• PHPCS bukan antivirus
• PHPCS bukan unit test
• PHPCS bukan static analyzer penuh seperti PHPStan

PHPCS menjawab pertanyaan gaya dan sebagian praktik aman WordPress. Contoh: spasi, nama fungsi, escaping output, penggunaan API tertentu. PHPStan menjawab pertanyaan tipe dan logika yang lebih dalam.

Proyek resmi sekarang berada di organisasi PHPCSStandards di GitHub. Paket Composer yang masih umum dipakai: squizlabs/php_codesniffer. Dokumentasi dan rilis ada di github.com/PHPCSStandards/PHP_CodeSniffer.

Perintah CLI utama ada dua:

• phpcs — mendeteksi pelanggaran
• phpcbf — memperbaiki pelanggaran yang bisa di-auto-fix

Tidak semua error bisa di-fix otomatis. phpcbf membantu soal format. Keputusan API tetap di tangan Anda.

Apa Itu WPCS: WordPress Coding Standards di Atas PHPCS

WPCS adalah kependekan dari WordPress Coding Standards. Ini kumpulan aturan coding untuk proyek WordPress.

WPCS bukan tool terpisah yang berdiri sendiri. WPCS adalah paket standard + sniff yang berjalan di mesin PHPCS. Tanpa PHPCS, WPCS tidak punya “mesin baca”.

Standar resmi WordPress mencakup PHP, HTML, CSS, dan JavaScript. Untuk PHP, acuan publik ada di developer.wordpress.org/coding-standards.

Paket Composer yang dipakai komunitas: wp-coding-standards/wpcs. Repositori: github.com/WordPress/WordPress-Coding-Standards.

Setelah WPCS terpasang, PHPCS mengenal beberapa nama standard. Nama yang sering muncul:

Menurut kami, untuk plugin klien Indonesia, pakai WordPress dulu. Baru naik ke Extra bila tim sudah nyaman.

WPCS juga bergantung pada paket pendukung seperti PHPCSUtils dan PHPCSExtra di versi modern. Composer menarik dependensi itu secara default.

PHPCS vs WPCS: Jangan Tertukar

Analogi kasar: PHPCS = mesin scanner. WPCS = buku peraturan WordPress yang dibaca mesin itu.

Anda bisa menjalankan PHPCS dengan standard lain. Contoh: PSR12, PEAR, atau standard custom perusahaan. Untuk proyek WordPress murni, WPCS yang relevan.

Bila seseorang bilang “pasang WPCS saja”, maksud praktisnya: pasang PHPCS + paket WPCS + daftarkan path standard.

Konteks kode WordPress yang sering kena sniff: hooks, class, dan function. Peta konsep itu ada di penjelasan hooks, class, function WordPress.

Fungsi dan Manfaat PHPCS WPCS untuk Proyek Nyata

Manfaat terbesar bukan “kode terlihat cantik”. Manfaat terbesar adalah bahasa bersama antar developer.

Tanpa standar, satu orang pakai tab. Orang lain pakai spasi. Satu orang escape output. Orang lain lupa. Review jadi debat selera.

Dengan phpcs wpcs, debat bergeser ke logika bisnis. Gaya sudah diurus mesin.

Manfaat yang Terasa di Lapangan

• Konsistensi indentasi, brace, dan penamaan antar file
• Peringatan dini soal escaping (esc_html, esc_attr, wp_kses)
• Peringatan dini soal nonces, capability check, dan SQL mentah berisiko
• Persiapan submit ke WordPress.org Plugin Directory
• Onboarding anggota baru lebih cepat karena aturan tertulis

Kelebihannya jelas untuk tim. Trade-off-nya juga nyata: setup awal memakan waktu. False positive kadang muncul. Sniff ketat bisa mengganggu prototipe cepat.

Menurut kami, untuk kode produksi WordPress, biaya setup jauh lebih murah daripada biaya debug gaya di PR besar.

Bila Anda merawat situs lama, alur maintenance dan checklist operasional tetap relevan. Lihat juga checklist maintenance website sebagai lapisan operasional di luar lint.

Siapa yang Memakai PHPCS dan WPCS

Penggunanya jauh lebih luas dari “senior PHP”.

Pengguna tipikal:

• Developer plugin WordPress yang bidik WordPress.org
• Developer tema custom untuk klien korporat
• Freelance yang bergabung di proyek agency dengan CI
• Tim internal perusahaan yang memelihara banyak plugin privat
• Kontributor core WordPress dan Gutenberg (konteks PHP terkait)
• Reviewer teknis yang menolak PR “liar”

Pemilik bisnis non-teknis jarang menjalankan phpcs sendiri. Namun mereka merasakan dampaknya: kode lebih rapi, handover lebih aman, risiko reject directory turun.

Mahasiswa dan peserta kursus WordPress sering baru bertemu istilah ini di materi lanjutan. Materi dasar kadang berhenti di admin. Gap skill itu muncul di kelas kursus belajar WordPress remote.

Lingkungan uji paling aman tetap lokal dulu. Setup admin lokal dibahas di localhost WordPress WP Admin.

Skill yang Anda Butuhkan Sebelum Mengandalkan PHPCS WPCS

PHPCS tidak mengganti otak developer. Ia memperkeras disiplin.

Skill minimum yang menurut kami wajar:

1. Dasar PHP: variabel, function, class, namespace, autoload sederhana
2. Dasar WordPress: hooks, template tags, plugin bootstrap
3. Dasar terminal Windows: cd, path, environment variable
4. Dasar Composer: require, vendor/bin, global vs project
5. Membaca pesan error: file, baris, kode sniff, saran perbaikan

Skill lanjutan yang mempercepat kerja:

• Menulis phpcs.xml.dist per proyek
• Exclude path vendor/, node_modules/, aset build
• Menyetel severity dan phpcs:ignore dengan alasan
• Menjalankan PHPCS di CI (GitHub Actions / GitLab CI)

Satu skill lunak sering dilupakan: menahan diri dari ignore massal. phpcs:ignore tanpa komentar alasan = utang teknis berseragam.

Bila Anda mengedit tema klien, disiplin standar membantu menghindari patch “jalan pintas”. Konteks kerja edit tema ada di edit tema WordPress profesional.

Risiko Nyata Bila Proyek Tanpa PHPCS WPCS

Kami jujur: proyek kecil sekali-pakai bisa hidup tanpa lint. Risiko naik ketika kode tumbuh, orang berganti, atau Anda bidik directory publik.

Risiko Teknis

• Output tidak di-escape → celah XSS lebih mudah lolos review manusia
• Direct DB query tanpa $wpdb->prepare → risiko injeksi
• Nonce atau capability check hilang → endpoint semi-terbuka
• Prefix fungsi bentrok antarplugin → fatal error di produksi
• Gaya campur aduk → diff PR sulit dibaca

PHPCS/WPCS tidak menjamin keamanan sempurna. Ia menandai banyak pola berisiko lebih awal. Lapisan keamanan lain tetap Anda butuhkan. Contoh konfigurasi proteksi plugin: setting WordFence.

Risiko Proses dan Bisnis

• Reject atau feedback berulang di WordPress.org Plugin Review
• Onboarding developer baru memakan minggu, bukan hari
• Handover ke vendor lain jadi mahal karena gaya “rahasia pribadi”
• Debat style di meeting yang seharusnya bahas fitur

Trade-off jujur: menjalankan WPCS Extra di legacy code bisa menghasilkan ribuan temuan. Jangan panik. Scan bertahap per folder. Perbaiki file yang aktif berubah dulu.

Backup sebelum refactor besar tetap wajib secara praktik. Panduan ringkas: cara backup website WordPress.

Studi Kasus: Plugin Custom Klien Ciledug Ditolak Gaya Kodenya

Klien UMKM jasa di Ciledug minta plugin form lead sederhana. Fitur jalan di staging. Submit ke directory tertunda.

Reviewer menandai escaping output dan penamaan fungsi tanpa prefix. Bukan bug fitur. Justru gaya dan keamanan dasar.

Awalnya tim kami belum memasang WPCS di CI. Perbaikan manual baris per baris memakan dua malam.

Lalu kami pasang PHPCS + WPCS di laptop Windows. Kami jalankan phpcs pada folder includes/. Daftar temuan muncul ratusan baris.

Setelah itu kami pakai phpcbf untuk isu format. Sisanya kami perbaiki manual. Submit ulang jauh lebih tenang.

Lesson keras: lint lebih murah daripada malu di antrean review.

Cara Install PHPCS dan WPCS di Windows

Bagian ini untuk Windows 10/11. Alur yang kami pakai di lapangan: PHP CLI → Composer → PHPCS → WPCS → verifikasi.

Anda boleh memakai Laragon, XAMPP, atau PHP standalone. Syaratnya: perintah php dan composer tersedia di terminal.

1. Pastikan PHP CLI Siap

Buka PowerShell atau Command Prompt. Ketik:

php -v

Target praktis 2026: PHP 8.1 atau lebih baru untuk proyek WordPress modern. Bila perintah tidak dikenal, perbaiki PATH PHP dulu.

Stack lokal sering menyatu dengan web server. Ringkasan pilihan server ada di aplikasi web server yang banyak dipakai.

2. Install Composer di Windows

Unduh installer resmi Composer untuk Windows dari getcomposer.org. Ikuti wizard. Centang opsi yang menambahkan Composer ke PATH bila tersedia.

Uji:

composer -V

Bila versi muncul, Composer siap.

3. Pilih Mode Install: Global atau Per Proyek

Dua pola umum:

Menurut kami, untuk tim dan CI, mode per proyek lebih aman. Untuk belajar sendiri, global lebih nyaman.

4. Install PHPCS + WPCS Per Proyek (Direkomendasikan)

Masuk ke folder plugin atau tema Anda:

cd C:\projects\my-wp-plugin
composer require --dev squizlabs/php_codesniffer wp-coding-standards/wpcs

Banyak proyek modern juga memasang plugin Composer yang mendaftarkan path otomatis:

composer require --dev dealerdirect/phpcodesniffer-composer-installer

Plugin itu membantu PHPCS menemukan standard WPCS tanpa installed_paths manual. Bila auto-detect gagal, lanjut langkah manual di bawah.

5. Daftarkan installed_paths Secara Manual (Jika Perlu)

Cari path folder WPCS di vendor. Lalu:

.\vendor\bin\phpcs --config-set installed_paths vendor/wp-coding-standards/wpcs,vendor/phpcsstandards/phpcsutils,vendor/phpcsstandards/phpcsextra

Path pasti bisa berbeda antar versi. Sesuaikan dengan isi folder vendor Anda.

Verifikasi standard yang dikenal:

.\vendor\bin\phpcs -i

Anda ingin melihat nama seperti WordPress, WordPress-Core, WordPress-Extra, WordPress-Docs.

6. Install Global (Opsional untuk Belajar)

composer global require squizlabs/php_codesniffer wp-coding-standards/wpcs

Pastikan folder Composer global bin ada di PATH Windows. Uji:

phpcs -i
phpcs --version

7. File phpcs.xml.dist untuk Proyek

Buat file phpcs.xml.dist di root proyek. Contoh minimal yang sering kami pakai:

<?xml version="1.0"?>
<ruleset name="My Plugin Standards">
  <description>WordPress coding standards for this plugin.</description>

  <file>.</file>

  <exclude-pattern>*/vendor/*</exclude-pattern>
  <exclude-pattern>*/node_modules/*</exclude-pattern>
  <exclude-pattern>*/tests/*</exclude-pattern>

  <arg name="basepath" value="." />
  <arg name="extensions" value="php" />
  <arg name="parallel" value="8" />
  <arg value="ns" />

  <rule ref="WordPress">
    <exclude name="WordPress.Files.FileName" />
  </rule>

  <config name="minimum_supported_wp_version" value="6.0" />
  <config name="testVersion" value="8.1-" />
</ruleset>

Exclude WordPress.Files.FileName hanya bila struktur nama file Anda memang beda dari aturan. Jangan exclude “asal hilang merah”.

Jalankan scan:

.\vendor\bin\phpcs
.\vendor\bin\phpcbf

Tanpa argumen, PHPCS membaca phpcs.xml / phpcs.xml.dist di folder kerja.

Install dan Setup PHPCS di IDE: VS Code, Cursor, dan PhpStorm

CLI sudah cukup. IDE membuat feedback muncul saat mengetik. Itu menghemat siklus “simpan → terminal → baca error”.

Web developer HardaWebPro memakai kombinasi CLI + editor agar review gaya tidak menumpuk di akhir sprint.

VS Code dan Cursor: Extension yang Dipakai

Cursor berbasis VS Code. Extension Marketplace yang sama pada praktiknya jalan.

Pilihan extension yang umum:

• phpcs (Ioannis Kappas / ikappas) — menjalankan PHPCS dan menampilkan diagnostik
• PHP Sniffer & Beautifier — menggabungkan phpcs + phpcbf di editor
• PHP Intelephense — bukan PHPCS, tapi pelengkap autocomplete PHP

Menurut kami, untuk pemula: pasang satu extension PHPCS dulu. Jangan tumpuk dua runner PHPCS bersamaan. Bentrok diagnostik bikin bingung.

Langkah di Cursor/VS Code:

1. Buka Extensions
2. Cari phpcs
3. Install extension runner PHPCS pilihan Anda
4. Buka Settings JSON workspace
5. Isi path executable dan standard

Contoh settings workspace (sesuaikan path Windows Anda):

{
  "phpcs.enable": true,
  "phpcs.executablePath": "C:\\\\projects\\\\my-wp-plugin\\\\vendor\\\\bin\\\\phpcs.bat",
  "phpcs.standard": "WordPress",
  "phpcs.autoConfigSearch": true
}

Untuk PHP Sniffer & Beautifier, kunci settings berbeda (phpsab.*). Baca README extension yang Anda pasang. Pokoknya sama: path executable + standard + auto search config.

PhpStorm: Inspection WordPress / Quality Tools

Di PhpStorm:

1. Settings → PHP → Quality Tools → PHP_CodeSniffer
2. Set path ke phpcs.bat (vendor atau global)
3. Validation: klik validate
4. Pilih coding standard WordPress atau file ruleset proyek

PhpStorm nyaman untuk tim yang sudah bayar lisensi. VS Code/Cursor lebih ringan untuk freelance solo.

Catatan PATH .bat di Windows

Di Windows, executable Composer sering berupa phpcs.bat, bukan binary Unix. Arahkan settings ke file .bat itu. Bila extension gagal jalan, uji dulu di terminal yang sama dengan path absolut.

Contoh Penggunaan PHPCS WPCS di Cursor dan VS Code

Bagian ini menunjukkan perintah dan cuplikan kode. Tiap contoh punya tujuan eksplisit. Bukan “kode pajangan”.

Contoh 1: Scan Satu File Plugin

Tujuan: menemukan pelanggaran di file bootstrap tanpa memindai seluruh vendor.

.\vendor\bin\phpcs --standard=WordPress ./my-plugin.php

Di Cursor: buka file → lihat panel Problems. Baris bermasalah sering digarisbawahi.

Output CLI menampilkan file, baris, kolom, severity, dan kode sniff. Contoh bentuk pesan: WordPress.Security.EscapeOutput.OutputNotEscaped.

Contoh 2: Kode yang Sengaja Melanggar, Lalu Diperbaiki

Tujuan: memahami sniff escaping output yang sering muncul di review.

Kode bermasalah:

<?php
function hwp_show_title( $title ) {
        echo '<h2>' . $title . '</h2>';
}

PHPCS/WPCS cenderung menandai output tanpa escape. Perbaikan tipikal:

<?php
function hwp_show_title( $title ) {
        echo '<h2>' . esc_html( $title ) . '</h2>';
}

Tujuan perbaikan: mencegah XSS dari judul yang berasal input tidak dipercaya. Escaping bukan diganti sanitasi input. Keduanya punya peran berbeda.

Contoh 3: Auto-fix Format dengan phpcbf

Tujuan: merapikan spasi/indentasi otomatis sebelum review manusia.

.\vendor\bin\phpcbf --standard=WordPress ./includes/

Di VS Code/Cursor dengan extension beautifier: jalankan perintah “Fix” dari Command Palette pada file aktif.

Ingat batasnya: phpcbf tidak selalu tahu intent bisnis Anda. Setelah auto-fix, baca diff. Jangan commit buta.

Contoh 4: Ignore Bertarget dengan Alasan

Tujuan: menekan false positive pada baris yang memang pengecualian, tanpa mematikan seluruh sniff.

<?php
// phpcs:ignore WordPress.Security.EscapeOutput.OutputNotEscaped -- raw SVG trusted from theme asset pipeline
echo $trusted_svg_markup;

Tanpa komentar alasan, ignore sulit diaudit. Tim lain akan curiga.

Contoh 5: Hanya Tampilkan Error, Sembunyikan Warning Saat Triage

Tujuan: fokus perbaikan kritis dulu pada legacy code yang “merah semua”.

.\vendor\bin\phpcs --standard=WordPress --warning-severity=0 ./includes/

Ini taktik triage. Bukan alasan permanent membiarkan warning.

Contoh 6: Report JSON untuk CI

Tujuan: menyimpan hasil scan agar pipeline CI bisa gagal build bila skor jelek.

.\vendor\bin\phpcs --standard=WordPress --report=json ./ > phpcs-report.json

Di GitHub Actions, langkah serupa dijalankan di runner Linux. Di laptop Windows, pola perintah tetap sama lewat vendor/bin.

Contoh 7: Workflow Harian yang Kami Sarankan

1. Tulis fitur di branch
2. Simpan file; biarkan IDE menandai isu cepat
3. Jalankan phpcbf pada folder yang berubah
4. Jalankan phpcs full ruleset proyek
5. Perbaiki sisa error manual
6. Baru buat pull request

Urutan itu terdengar kaku. Di praktik, justru memotong waktu review.

Bila Anda membangun situs perusahaan, kualitas kode backend ini menopang jasa website company profile yang tahan maintenance panjang. Soft skill proses sama pentingnya dengan desain visual.

Konfigurasi Lanjutan yang Sering Dibutuhkan

Setelah setup dasar stabil, isu berikutnya sering berupa legacy dan pengecualian.

Text Domain dan Prefix

WPCS bisa memeriksa text domain plugin untuk i18n. Set di ruleset:

<rule ref="WordPress.WP.I18n">
  <properties>
    <property name="text_domain" type="array">
      <element value="my-plugin-slug" />
    </property>
  </properties>
</rule>

Tujuan: mencegah string translation memakai text domain salah.

Minimum WP dan PHP Version

Konfigurasi minimum_supported_wp_version dan testVersion membantu sniff kompatibilitas. Sesuaikan dengan janji readme plugin Anda. Jangan mengaku support PHP 7.4 bila sniff hanya diuji di 8.2.

Exclude Folder Build

Jangan scan minified JS vendor, Composer packages, atau artefak build. Noise tinggi. Signal turun.

Untuk proyek compro WordPress yang juga menyentuh performa server, disiplin lint ini melengkapi hardening konfigurasi. Baca pula htaccess WordPress untuk performa dan keamanan. Lapisan berbeda. Saling melengkapi.

Batasan Jujur: Apa yang Tidak Dilakukan PHPCS WPCS

Kami sering melihat ekspektasi berlebihan.

PHPCS/WPCS tidak:

• Mengganti unit test dan integration test
• Menjamin bebas bug logika bisnis
• Mengganti code review manusia untuk arsitektur
• Menemukan semua celah keamanan modern tanpa intervensi manusia
• Membuat plugin “layak jual” hanya karena 0 error

Nol error PHPCS = gaya dan sebagian praktik sesuai standar. Bukan sertifikat kualitas produk.

Bila Anda membandingkan stack WordPress dengan opsi lain untuk compro, baca juga WordPress vs Laravel untuk compro. Standar kode ada di kedua dunia. Namanya beda. Tujuannya mirip: kode tim tidak kacau.

Kategori Sniff WPCS yang Paling Sering Muncul

Saat pertama jalan, daftar error bisa terasa “serangan”. Kelompokkan dulu. Otak Anda lebih tenang.

Prioritas perbaikan yang kami pakai di proyek klien Tangerang Selatan:

1. Security + DB dulu
2. Nonce dan capability berikutnya
3. Naming dan prefix
4. Format dan FileName di akhir

Urutan itu menurunkan risiko produksi lebih cepat daripada merapikan spasi duluan.

Satu opini bertekstur: banyak junior “berburu angka hijau” dengan phpcbf saja. Angka hijau format tanpa escape tetap berbahaya.

Troubleshooting Windows yang Paling Sering Menghabiskan Waktu

Sebagian besar “PHPCS rusak” di Windows ternyata masalah path, bukan WPCS.

phpcs tidak dikenali di PowerShell

Gejala: phpcs : The term 'phpcs' is not recognized.

Perbaikan cepat:

• Pakai path lokal: .\vendor\bin\phpcs.bat
• Atau tambahkan Composer global bin ke PATH user
• Tutup lalu buka ulang terminal setelah ubah PATH

Lokasi global Composer di banyak laptop Windows:

%APPDATA%\Composer\vendor\bin

Tambahkan folder itu ke Environment Variables → Path.

Standard WordPress unknown

Gejala: ERROR: the "WordPress" coding standard is not installed.

Cek tiga hal:

1. Paket wp-coding-standards/wpcs benar-benar ada di vendor
2. installed_paths mengarah ke folder yang benar
3. Anda tidak memanggil PHPCS global lama yang kosong

Perintah diagnostik:

.\vendor\bin\phpcs --config-show
.\vendor\bin\phpcs -i
where.exe phpcs

Bila where.exe menunjuk binary lain, IDE mungkin ikut tersesat ke binary itu.

Permission / antivirus mengunci vendor\bin

Beberapa antivirus Windows memindai script .bat agresif. Gejala: phpcs hang atau exit code aneh. Pengecualian folder proyek untuk scanner (bukan mematikan antivirus total) sering menolong.

Line ending CRLF vs LF

Repo lintas OS kadang ribut soal line ending. Samakan kebijakan di .gitattributes. Jangan biarkan diff “seluruh file berubah” hanya karena CRLF.

Menjalankan PHPCS WPCS di CI: Contoh GitHub Actions

Lint di laptop mudah dilupakan sebelum push. CI menutup celah itu.

Tujuan workflow di bawah: gagalkan pull request bila PHPCS menemukan error pada folder plugin.

name: phpcs
on:
  pull_request:
  push:
    branches: [ main ]
jobs:
  phpcs:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: shivammathur/setup-php@v2
        with:
          php-version: "8.2"
          tools: composer
      - run: composer install --no-interaction --prefer-dist
      - run: vendor/bin/phpcs --standard=phpcs.xml.dist --report=full

Di Windows lokal Anda tetap pakai vendor\bin\phpcs.bat. Di CI Linux, binary tanpa .bat.

Trade-off jujur: CI menambah beberapa menit pipeline. Imbalannya: reviewer manusia tidak jadi “mesin spasi”.

Untuk tim kecil freelance, CI ringan sudah cukup. Untuk produk plugin komersial, gabungkan PHPCS + PHPUnit + smoke test.

Strategi Legacy: Baseline, Jangan Heroik Semalam

Kode tema lima tahun sering menghasilkan ribuan temuan di scan pertama. Kami pernah melihat angka empat digit. Panik tidak membantu.

Pendekatan yang lebih waras:

1. Scan sekali. Simpan report sebagai baseline
2. Aktifkan lint ketat hanya pada file baru dan file yang diubah
3. Tiap sprint, bayar utang di satu modul saja
4. Naikkan ruleset perlahan dari WordPress ke Extra

Beberapa tim memakai tools baseline / ignore file generated. Pola kerjanya sama: hentikan penambahan utang baru, lunasi utang lama bertahap.

Opini kami: memaksa Extra penuh di hari pertama pada legacy hampir selalu gagal secara sosial. Developer memberontak. Ruleset lalu dimatikan diam-diam.

Lebih baik standar sedang yang ditaati daripada standar sempurna yang diabaikan.

Checklist Cepat Sebelum Anda Klaim “Sudah Pakai WPCS”

• phpcs -i menampilkan WordPress*
• Ada phpcs.xml.dist di root repo
• vendor/ dan build assets ter-exclude
• IDE mengarah ke binary yang sama dengan CI
• Minimal satu perintah phpcs di dokumentasi README
• Kebijakan phpcs:ignore wajib menyertakan alasan

Bila enam poin itu belum lengkap, klaim “kami sudah WPCS” masih prematur.

Di proyek HardaWebPro, checklist ini jadi bagian briefing sebelum handover kode ke pihak lain. Bukan untuk gaya. Untuk mengurangi tiket “tiba-tiba fatal error setelah edit kecil”.

FAQ PHPCS dan WPCS

Apa bedanya PHPCS dan WPCS dalam satu kalimat?

PHPCS adalah mesin pemeriksa coding standard. WPCS adalah paket aturan WordPress yang dijalankan mesin itu.

Apakah PHPCS sama dengan PHPStan atau Psalm?

Tidak. PHPStan/Psalm fokus analisis tipe dan bug potensial. PHPCS fokus standar gaya dan sniff khusus ekosistem. Paling masuk akal dipakai bersama, bukan dipilih salah satu sebagai agama.

Apakah saya wajib pakai WPCS untuk plugin privat klien?

Tidak wajib secara hukum. Kami tetap menyarankannya. Handover dan keamanan dasar jauh lebih tenang. Untuk submit WordPress.org, mendekati WPCS hampir tidak bisa ditawar.

Kenapa phpcs -i belum menampilkan WordPress?

Penyebab paling sering: installed_paths belum mengarah ke folder WPCS. Atau Anda menjalankan binary PHPCS yang berbeda dari yang baru di-install Composer. Cek path where phpcs di Windows.

Apakah phpcbf aman dijalankan di seluruh repo?

Aman dari sisi mesin bila Anda punya git clean state. Tetap review diff. Auto-fix bisa menyentuh file yang tidak Anda maksud bila exclude pattern longgar.

Extension di Cursor tidak menampilkan error, padahal CLI ada temuan. Kenapa?

Penyebab umum: path phpcs.bat salah, standard tidak ketemu, atau workspace belum membuka root yang berisi phpcs.xml.dist. Uji CLI dulu. Baru debug settings editor.

Apakah WPCS memperlambat laptop Windows?

Scan folder besar bisa terasa berat. Pakai parallel, exclude vendor, dan scan folder yang berubah saat kerja harian. Full scan biarkan di CI.

Haruskah setiap warning diperbaiki sampai nol?

Untuk plugin baru: usahakan mendekati nol. Untuk legacy: turunkan bertahap. Baseline + “tidak menambah warning baru” sering lebih realistis daripada heroik semalam.

Di mana dokumentasi resmi yang paling layak di-bookmark?

• PHP_CodeSniffer: GitHub PHPCSStandards
• WPCS: GitHub WordPress/WordPress-Coding-Standards
• Human-readable standards: developer.wordpress.org/coding-standards

Bookmark tiga itu cukup untuk kerja harian.

Cara Menulis Komentar Ignore PHPCS/WPCS (False Positif & Pengecualian)

Kadang sniff salah baca konteks. Kadang Anda memang butuh pengecualian sadar. Jangan matikan seluruh ruleset. Tulis anotasi bertarget.

Acuan resmi sintaks ada di wiki PHP_CodeSniffer Advanced Usage.

Empat anotasi yang wajib dihafal

Menurut kami, urutan aman: perbaiki dulu → ignore bertarget → disable blok → ignoreFile sebagai opsi terakhir.

Contoh 1: Ignore satu baris + alasan wajib

Tujuan: menekan false positif escaping pada markup SVG yang sudah dipercaya dari pipeline aset tema.

<?php
// phpcs:ignore WordPress.Security.EscapeOutput.OutputNotEscaped -- trusted SVG from sanitized theme asset pipeline
echo $trusted_svg_markup;

Pisahkan alasan dengan --. Tanpa alasan, reviewer dan diri Anda enam bulan kemudian akan bingung.

Contoh 2: Ignore di akhir baris yang sama

Tujuan: mengecualikan hanya baris aktif, tanpa “menyapu” baris berikutnya.

<?php
update_option( 'hwp_flag', $raw ); // phpcs:ignore WordPress.Security.ValidatedSanitizedInput.InputNotSanitized -- value already sanitized upstream in REST callback

Bila komentar phpcs:ignore berdiri sendiri di baris sendiri, PHPCS mengabaikan baris komentar itu dan baris berikutnya. Letakkan di akhir baris kode bila Anda hanya ingin satu baris.

Contoh 3: Disable / enable untuk blok

Tujuan: mengecualikan beberapa baris integrasi library pihak ketiga tanpa mematikan sniff di sisa file.

<?php
// phpcs:disable WordPress.NamingConventions.ValidVariableName -- vendor SDK forces camelCase properties
$client->accessToken = $token;
$client->apiEndpoint = $url;
// phpcs:enable WordPress.NamingConventions.ValidVariableName

Sebut kode sniff yang sama di enable bila Anda menonaktifkan secara selektif. Jangan biarkan disable terbuka sampai akhir file tanpa perlu.

Contoh 4: Beberapa sniff sekaligus

Tujuan: satu baris kena dua kode pesan yang memang dikecualikan bersama.

<?php
// phpcs:ignore WordPress.DB.PreparedSQL.NotPrepared,WordPress.DB.DirectDatabaseQuery.DirectQuery -- legacy report query audited; prepared via $wpdb->prepare above
$results = $wpdb->get_results( $sql );

Pisahkan kode sniff dengan koma. Targetkan kode pesan spesifik, bukan seluruh standard WordPress, kecuali situasi darurat yang terdokumentasi.

Contoh 5: Ignore file generated

Tujuan: melewati file autoload/stub yang di-generate tool lain.

<?php
// phpcs:ignoreFile
// This file is generated by a build script. Do not edit.

Taruh di dekat atas file. File ini tetap bisa masuk repo, tapi PHPCS tidak memindainya.

Contoh 6: Yang dilarang tim kami

<?php
// phpcs:ignore
echo $title;

// phpcs:disable
// ... ratusan baris ...
// phpcs:enable

Ignore tanpa kode sniff = menutup mata. Disable tanpa batas jelas = utang tersembunyi. Keduanya merusak nilai WPCS.

Wiki WPCS juga membahas isu sering muncul: github.com/WordPress/WordPress-Coding-Standards/wiki.

Bug dan False Positive PHPCS/WPCS dari Sumber Resmi

PHPCS dan WPCS adalah software aktif. Mereka punya bug. Itu normal. Yang tidak normal: menganggap setiap temuan selalu benar 100%.

Sebelum menulis ignore, cek dulu isu terbuka di tracker resmi. Mungkin sniff-nya yang salah, bukan kode Anda.

Di mana mencari laporan bug

• WPCS: github.com/WordPress/WordPress-Coding-Standards/issues
• PHPCS: github.com/PHPCSStandards/PHP_CodeSniffer/issues
• Changelog PHPCS 4.x: file CHANGELOG-4.x.md di repo PHPCSStandards

Forum WordPress.org dan Slack Make/Core sering mengarahkan kembali ke GitHub Issues sebagai sumber kebenaran.

Pola bug WPCS yang sedang aktif dibahas

Di tracker WPCS (2025–2026), banyak isu terkait pemanggilan fungsi ber-namespace saat masih berjalan di PHPCS 3.x. Tokenisasi namespace di PHPCS 3.x memecah nama. Sniff lalu salah mengenali fungsi global.

Contoh isu yang layak Anda bookmark:

• #2648 — WordPress.DB.PreparedSQL salah hitung/identifikasi error pada pemanggilan namespaced
• #2665 — bug ContextHelper::is_in_function_call() bila nama fungsi namespaced mirip fungsi global valid (dampak ke sanitasi input)
• #2674 — WordPress.Security.EscapeOutput salah menerapkan logika array_map/map_deep pada fungsi namespaced sejenis
• #2720 — PreparedSQLPlaceholders false negative pada MyNamespace\sprintf() atau method sprintf()

Maintainer sering menulis: perbaikan penuh lebih mudah setelah dukungan PHPCS 3.x dihentikan, karena PHPCS 4.x menangani token namespace secara berbeda.

Artinya praktis untuk Anda di 2026: bila proyek memakai namespace PHP modern dan WPCS “aneh”, bandingkan versi PHPCS di composer.lock dengan isu di atas sebelum menyalahkan diri sendiri.

Bug di sisi mesin PHPCS

PHPCS pun punya regresi anotasi. Di jalur 4.x, changelog mencatat perbaikan soal whitespace pada daftar sniff di phpcs:ignore, serta kasus lama di mana phpcs:enable selektif bisa menimpa phpcs:ignore berikutnya.

Upgrade guide PHPCS 4.0 juga menegaskan: sintaks lama @codingStandardsIgnore* sudah dihapus. Ganti ke phpcs: / @phpcs:. Baca ringkasannya di Version 4.0 User Upgrade Guide.

Cara bersikap saat dugaan bug

1. Reproduksi minimal di file kecil
2. Catat versi: PHP, PHPCS, WPCS, PHPCSUtils, PHPCSExtra
3. Cari isu terbuka dengan nama sniff
4. Bila cocok: tulis phpcs:ignore + tautan isu di alasan
5. Bila belum ada: buka issue baru dengan contoh kode

<?php
// phpcs:ignore WordPress.DB.PreparedSQL.NotPrepared -- false positive on namespaced helper; see WPCS#2648
$sql = MyPlugin\SQL\build_report_query( $args );

Tujuan komentar di atas: mengecualikan baris tanpa menyembunyikan konteks. Reviewer langsung tahu ini dugaan bug upstream, bukan malas escape.

Trade-off jujur: ignore karena bug upstream harus ditinjau ulang saat WPCS/PHPCS naik versi mayor. Jangan biarkan “sementara” menjadi permanen tanpa review.

Bila Anda membangun atau merawat kode WordPress jangka panjang, disiplin phpcs wpcs adalah fondasi sunyi yang jarang dipamerkan di portfolio. Namun ia yang menjaga kode tetap bisa disentuh orang lain tanpa drama.