ja-jp

C5Jのコーディング・スタンダード

PHPのためのクリーンコードの概念

これは個人の好みの問題だと思います。コードがきれいなときは？そうでないときは？これは一概には言えませんが、コードを改善するための一般的なガイドラインはいくつかあります。以下に、私が使用している参考文献を紹介します。

👉公式ドキュメント

Follow the concrete5 公式ドキュメント.

👉クリーンコード PHP

Clean Code PHP(jupeter/clean-code-php), is a guide based on the book Clean Code: A Handbook of Agile Software Craftmanship, a classic programming book about writing maintainable code by Uncle Bob Martin. I recommend this as a Must Read guideline.

👉PHP-CS-Fixer

Check their official documentation to integrate with your IDE. Also, concrete5 has a command (from 8.5.3) to use it. Please run ./concrete/bin/concrete5 c5:phpcs --help for detail.

👉ヒントとコツ

• Writing Clean Code In PHP.
• PHP 8 tricks that will help you write cleaner code.

Package development

👉Basic Requirements

パッケージを作る際の基本的な条件は以下の通りです。

• すべてのフォーム、ajaxリクエスト、重要なアクションにトークンの検証を追加しました。 See Security & XSS Protection.
• コントローラにフォーム入力のバリデーションを追加します。
• 基本的なHTML検証をビューに追加します。Javascriptでの検証も可能です。
• データベースに保存する前に入力内容を消毒する。 See Security & XSS Protection.
• 出力変数のサニタイズ。 See Security & XSS Protection.
• Add a confirmation dialog to non-returnable actions.
• Try to keep your controllers and views slim as much as possible. Don't hesitate to create a new class or element. Use Traits to avoid code repeat.
• Add README.md & CHANGELOG.md files. You may use https://www.makeareadme.com to make a README file. And https://keepachangelog.com to make a changelog.
• コントローラーにエイリアスを使わない。
• Don't use deprecated codes.
• Follow the style guide.
• プロジェクトのバージョン互換性に基づいて、最新の構文でPHPコードを書く。 e.g., Use Type Declarations as much as possible. You may check this list to know about PHP version compatibility.

👉Block Types

👉Config

• Contents (Block Types, Single Pages, Express Objects etc.) can be installed Programmatically or using CIF files. CIF is the recommended way to use.
• Add an example config file (if any). e.g., example.concrete.php

👉Routes

• Follow the official guide to register routes.

👉Single Pages

• Follow the official guide to send data to and from a controller into the page view. Please avoid using ajax unnecessarily.

👉MyPackage

パッケージ開発の出発点として、このスケルトンパッケージを作りました。ここからアイデアを得ることができます。このリポジトリを改善するためのプルリクエストもご自由にどうぞ。

Performance

• Avoid duplicate MySQL queries.
• Use Object Caching to improve performance.

Test

• Write PHPUnit tests to test your package.

Documentation

• Add phpDocumentor tags in DocBlocks.
• Use phpDocumentor to generate the PHP code documentation.
• Use ApiDocJS to generate the REST api doc.