Ageras PHP Coding Standards

This document describes the coding standards for PHP code written by Ageras.

At Ageras, we aim to maintain high-quality, consistent, and maintainable PHP code. These coding standards ensure compliance with PSR-12 and leverage modern tools to enhance code reliability and developer productivity.

Table of Contents

1. Installation
2. Configuration
   • PHP CS Fixer Configuration
   • PHPStan Configuration
3. Usage
4. License

---

Installation

To install the coding standards, run the following command:

composer require billysbilling/php-coding-standards --dev

Versioning

Make sure to require a specific version of the package to maintain stability in your project. For example:

composer require billysbilling/php-coding-standards:^1.0 --dev

Composer Scripts

Add the following scripts to the scripts section of your composer.json file to simplify usage:

{
  "scripts": {
    "csfixer:fix": "vendor/bin/php-cs-fixer fix",
    "csfixer:check": "vendor/bin/php-cs-fixer fix --dry-run -vv",
    "phpstan:analyse": "vendor/bin/phpstan analyse --memory-limit=1G",
    "phpstan:generate-baseline": "vendor/bin/phpstan analyse --generate-baseline --memory-limit=1G"
  }
}

---

Configuration

PHP CS Fixer Configuration

The default PHP CS Fixer configuration provided by Ageras ensures compliance with PSR-12 and enforces modern PHP coding standards. It includes rules such as:

• Array syntax: Short array syntax [] instead of array().
• Strict typing: Enables strict types for all files.
• Modernizations: Removes legacy function aliases and uses modern casting.

Default Configuration

To use the default PHP CS Fixer configuration provided by Ageras, create a .php-cs-fixer.php file in the root directory of your project with the following content:

<?php

declare(strict_types=1);

use BillysBilling\PhpCodingStandards\PhpCsFixerConfig;

$config = new PhpCsFixerConfig();

// Exclude directories like vendor or legacy folders
$finder = PhpCsFixer\Finder::create()->in(__DIR__)->exclude(['vendor']);
$config->setFinder($finder);

return $config;

Relaxing Rules Temporarily

If you need to temporarily relax certain rules to support legacy code or incremental adoption, you can modify the $rules array:

<?php

declare(strict_types=1);

use BillysBilling\PhpCodingStandards\PhpCsFixerConfig;

$config = new PhpCsFixerConfig();

$finder = PhpCsFixer\Finder::create()->in(__DIR__)->exclude(['vendor']);
$config->setFinder($finder);

// Temporary relaxation of the rules
$rules = $config->getRules();
$rules['declare_strict_types'] = false;
$rules['modernize_types_casting'] = false;
$rules['native_constant_invocation']  = false;
$rules['no_alias_functions'] = false;
$rules['strict_comparison'] = false;
$rules['strict_param'] = false;
$rules['void_return'] = false;
$config->setRules($rules);

return $config;

Note: Temporarily relaxing rules is intended for incremental migration of legacy code. Plan to re-enable these rules as you clean up the codebase.

---

PHPStan Configuration

The default PHPStan configuration provided by Ageras enforces strong static analysis to detect errors, bugs and coding standard violations.

Default Configuration

Create a phpstan.neon file in the root directory of your project:

includes:
    - vendor/billysbilling/php-coding-standards/phpstan.neon

Relaxing Rules Temporarily

includes:
    - vendor/billysbilling/php-coding-standards/phpstan.neon

parameters:
    level: max # Maximum analysis level for strict checks
    paths: # Define the paths to analyze
        - src
        - tests
    ignoreErrors: # Optionally ignore errors in specific paths
        -
            message: '#.*#'
            paths:
                - src/legacy/*
                - tests/legacy/*

Note: Temporarily relaxing rules is intended for incremental migration of legacy code. Plan to re-enable these rules as you clean up the codebase.

Handling Existing Issues with PHPStan Baseline

When working with legacy codebases, you may encounter many errors during static analysis. PHPStan provides a baseline feature that allows you to temporarily ignore existing errors while focusing on new issues.

Run the following command to generate a phpstan-baseline.neon file:

composer phpstan:generate-baseline

This will save all current errors to phpstan-baseline.neon.

Include the generated baseline in your phpstan.neon file:

includes:
    - vendor/billysbilling/php-coding-standards/phpstan.neon
    - phpstan-baseline.neon

Note: The baseline file serves as a temporary solution. You should gradually address the errors listed in the baseline to achieve full compliance.

---

Usage

Fix Code Style Issues

Automatically fix code style violations based on Ageras PHP Coding Standards:

composer csfixer:fix

This command runs PHP CS Fixer and applies the defined coding standards to your codebase.

Check Code Style

Validate the codebase for style violations without applying changes. This is particularly useful for development workflows and CI/CD pipelines:

composer csfixer:check

This command runs PHP CS Fixer in dry-run mode and outputs any violations it finds.

Static Code Analysis

Perform static analysis to detect bugs, potential issues, or deviations from coding standards:

composer phpstan:analyse

This command runs PHPStan to analyze the codebase and report any errors or inconsistencies.

Static Code Baseline Generation

Generate a baseline file for PHPStan to temporarily ignore existing issues in the codebase. This is especially useful for legacy projects:

composer phpstan:generate-baseline

This command runs PHPStan with the --generate-baseline option and creates a phpstan-baseline.neon file to record the current issues.

---

License

This project is licensed under the proprietary license. See the LICENSE file for more details.

---

Resources

For more information about the tools used in this project, refer to the official documentation:

• PHP CS Fixer: Official Documentation
• PHPStan: Official Documentation
• PSR-12 Coding Standard: PSR-12