Macareux Digital Coding Standards

Clean Code Concepts for PHP

I think this is a matter of personal taste. When is the code clean? When is it not? This is hard to say, but there are some general guidelines which you can follow to help improve your code. Below I have given the references that I use, and they have helped me so far.

👉Official Documentation

Follow the concrete5 official documentation.

👉Clean Code 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.

👉Tips & Tricks

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

Package development

👉Basic Requirements

The followings are the basic requirements when you make a package-

• Add token validation to all form, ajax request and important actions. See Security & XSS Protection.
• Add form input validation to the controller.
• Add basic HTML validation to the view. Javascript validation would be plus.
• Sanitize input before saving into the database. See Security & XSS Protection.
• Sanitize output variables. 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.
• Please use semantic versioning.
• 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 aliases in controller.
• Don't use deprecated codes.
• Follow the style guide.
• Write PHP codes with updated syntax based on the project version compatibility. e.g., Use Type Declarations as much as possible. You may check this list to know about PHP version compatibility.
• Use md_ as a prefix of our packages handle.

👉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

I've created this skeleton package as a starting point to develop packages. You can get ideas from here. Feel free to make a pull request to improve this repository.

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.