wp-phpstan

Tổng quan về skill wp-phpstan

wp-phpstan là skill nên dùng khi bạn cần PHPStan hoạt động tốt trong một codebase WordPress, chứ không chỉ “chạy được là xong.” Skill này hướng đến các nhà phát triển plugin, theme và site muốn phân tích tĩnh sạch hơn, ít false positive hơn, và có lộ trình thực tế cho code cũ vốn đã tồn tại lỗi.

Nhiệm vụ cốt lõi là cấu hình và sửa lỗi: nối phpstan.neon, xử lý baseline, nạp WordPress stubs, và bổ sung các type annotation hiểu WordPress ở những chỗ PHPStan không thể suy luận hành vi runtime.

wp-phpstan phù hợp nhất với trường hợp nào

Hãy dùng wp-phpstan khi bạn cần:

• thiết lập hoặc cập nhật PHPStan trong một repo WordPress
• giảm lỗi do thiếu symbol của WordPress core
• quản lý phpstan-baseline.neon mà không che mất regression mới
• sửa các pattern động của WordPress như hooks, REST request và kết quả query
• xử lý các class plugin bên thứ ba tuỳ chọn như WooCommerce hoặc ACF

Vì sao skill này khác biệt

Một prompt PHPStan chung chung thường bỏ sót các ràng buộc đặc thù của WordPress: class chỉ được nạp ở runtime, callback của hook, phụ thuộc plugin, và môi trường phân tích không khớp với site đang chạy thật. wp-phpstan hữu ích vì nó ưu tiên những trường hợp biên đó trước, đặc biệt là nạp stub và ignore có mục tiêu.

Khi nào không nên dùng

Nếu bạn chỉ cần giải thích nhanh một lệnh PHPStan dùng một lần, skill này có thể quá mức cần thiết. Nó hữu ích nhất khi chất lượng phân tích đủ quan trọng để các quyết định về setup, chính sách baseline và type hint ảnh hưởng trực tiếp đến kết quả.

Cách dùng skill wp-phpstan

Cài đặt và kiểm tra skill

Với wp-phpstan install, hãy thêm skill từ repo WordPress agent skills:

npx skills add WordPress/agent-skills --skill wp-phpstan

Sau khi cài, hãy đọc SKILL.md trước, rồi đến các tài liệu tham chiếu hỗ trợ và inspection script. Repo được tổ chức để trả lời những câu hỏi ảnh hưởng lớn nhất đến việc áp dụng: PHPStan đang thấy gì, đang bỏ qua gì, và chỗ nào nên gắn type thay vì suppress.

Cung cấp đúng đầu vào cho skill

wp-phpstan hoạt động tốt nhất khi bạn đưa ngữ cảnh dự án vào trước khi yêu cầu sửa. Hãy bắt đầu bằng:

• output từ wp-project-triage
• việc có được phép thay đổi Composer dev dependencies hay không
• việc có được phép cập nhật baseline hay không
• các lỗi PHPStan cụ thể hoặc file config bạn muốn thay đổi

Một prompt yếu: “Sửa PHPStan trong plugin WordPress của tôi.”

Một prompt mạnh hơn: “Dùng wp-phpstan để kiểm tra setup PHPStan hiện tại của plugin, xác nhận szepeviktor/phpstan-wordpress đã được nạp chưa, và đề xuất thay đổi config nhỏ nhất để sửa các hàm WordPress chưa xác định mà không ignore rộng. Chỉ được phép đổi baseline cho các lỗi legacy đã có sẵn.”

Quy trình và file nên theo dõi

Để dùng wp-phpstan hiệu quả trong thực tế, hãy đi theo đúng lộ trình quyết định của repo:

1. Kiểm tra setup bằng scripts/phpstan_inspect.mjs
2. Xem các file config chính và baseline
3. Đọc references/configuration.md
4. Đọc references/third-party-classes.md
5. Dùng references/wordpress-annotations.md khi vấn đề nằm ở suy luận type, không phải ở setup

Nếu muốn đi nhanh đến kết quả tốt, hãy xem trước các file này:

• SKILL.md
• references/configuration.md
• references/third-party-classes.md
• references/wordpress-annotations.md
• scripts/phpstan_inspect.mjs

Dạng prompt thực dụng

Prompt tốt nói rõ cái gì là cố định, cái gì có thể thay đổi, và bạn muốn đầu ra gì. Ví dụ:

• “Audit phpstan.neon của một plugin WordPress và cho tôi biết có nên thêm stub, siết ignoreErrors, hay cập nhật baseline không.”
• “Viết lại annotation của REST controller này để PHPStan hiểu shape của request.”
• “Môi trường phân tích của tôi không có WooCommerce; hãy đề xuất chiến lược stub/ignore thật hẹp cho các class bị thiếu này.”

Mức chi tiết đó giúp wp-phpstan chọn giữa đổi config, thêm annotation, hay thay đổi dependency.

Câu hỏi thường gặp về skill wp-phpstan

wp-phpstan chỉ dành cho plugin WordPress thôi à?

Không. wp-phpstan cũng phù hợp với theme và các site WordPress có code tuỳ biến. Nó hữu ích nhất ở bất kỳ đâu PHPStan cần trợ giúp để hiểu hành vi runtime của WordPress.

Có cần sẵn Composer và PHPStan không?

Có. Skill này giả định bạn đang làm theo workflow PHPStan dựa trên Composer. Nếu repo của bạn không dùng Composer, hoặc PHPStan không nằm trong toolchain, thì skill này không phù hợp.

Skill này có tốt hơn viết prompt riêng không?

Thường là có, nếu bạn quan tâm đến quyết định setup có thể lặp lại. Một prompt riêng có thể sửa được một lỗi đơn lẻ, nhưng wp-phpstan cho bạn workflow tốt hơn cho baseline, stub và kiểu hoá đặc thù WordPress.

Khi nào nên tránh ignore quá rộng?

Hãy tránh ignore rộng khi class hoặc function thực ra vẫn có, chỉ là thiếu stub, lỗi autoload, hoặc môi trường phân tích không khớp. Chỉ dùng ignore có mục tiêu sau khi đã xác minh đường đi của dependency là có thật và không thể sửa gọn gàng.

Cách cải thiện skill wp-phpstan

Nêu đúng kiểu lỗi PHPStan thực sự gặp

Kết quả tốt nhất từ wp-phpstan đến khi bạn xác định đúng loại lỗi trước khi yêu cầu sửa:

• hàm WordPress core không xác định → stub hoặc config
• nhiễu do legacy → baseline workflow
• dữ liệu request động → @phpstan-param hoặc type alias dùng lại được
• API plugin tuỳ chọn → stub có mục tiêu hoặc ignore thật hẹp

Nếu bạn chỉ dán danh sách lỗi, skill có thể tối ưu triệu chứng thay vì nguyên nhân.

Chia sẻ ranh giới phân tích

Hãy nói rõ skill được phép thay đổi gì. Kết quả sẽ tốt hơn khi bạn nêu:

• có thể sửa composer.json không?
• có thể thêm dev dependencies không?
• có thể đổi phpstan.neon không?
• có thể tạo lại baseline không?

Những quyền đó quyết định wp-phpstan nên ưu tiên sửa code, sửa config hay sửa dependency.

Ưu tiên đầu vào cụ thể thay vì mục tiêu chung chung

Đầu vào càng rõ thì đầu ra càng tốt. Ví dụ, hãy đưa vào:

• level PHPStan hiện tại
• các thư mục bạn đang phân tích
• WordPress core có mặt trong CI hay không
• plugin hoặc class cụ thể đang gây lỗi thiếu symbol

Điều này giúp wp-phpstan đề xuất đúng lộ trình cài đặt và sử dụng cho công việc Backend Development, thay vì đưa ra một checklist PHPStan chung chung.

Lặp từ config sang annotation

Một wp-phpstan guide tốt thường đi theo thứ tự này:

1. xác minh stub và cơ chế discovery
2. thu hẹp excludes và ignores
3. thêm annotation cho các type động đặc thù WordPress
4. cập nhật baseline chỉ cho phần debt legacy đã chấp nhận

Thứ tự đó giữ cho phân tích đủ chặt để bắt lỗi mới, đồng thời giảm false positive ở những chỗ mô hình động của WordPress làm PHPStan không suy luận được.