Download the PHP package sinemacula/coding-standards without Composer

Coding Standards

Centralized coding standards, static analysis configurations, and code quality tooling for all Sine Macula repositories.

This package ships config files only - no runtime dependencies. Consuming projects install the tools themselves.

Installation

Composer (PHP-side: PHP CS Fixer, PHPStan, PHPCS)

npm (JS-side: Biome, Knip)

The npm package ships only the static configs (js/, markdown/, yaml/, shell/, security/). The PHP autoloaded code lives in the Composer package.

Usage

Each consuming project creates thin wrapper files at its root that reference the shared configs.

PHP CS Fixer

Create a .php-cs-fixer.dist.php at your project root:

You can pass rule overrides as a second argument:

PHPCS

The SineMacula coding standard is auto-discovered via the phpcodesniffer-standard composer type. Create a phpcs.xml at your project root:

PHPStan

The shared PHPStan configs are auto-included via the extra.phpstan.includes section in composer.json. Your project's phpstan.neon only needs project-specific settings:

Laravel projects

For Laravel projects, also install sinemacula/coding-standards-laravel and reference its SineMaculaLaravel PHPCS standard (which includes this one) in place of SineMacula. It adds the Laravel-specific sniffs and PHPStan rules; see that package's README for setup.

Biome (JavaScript / TypeScript)

After installing the npm package, extend the shared Biome config from your project's biome.json (or .qlty/configs/biome.json when wired through Qlty):

extends paths are resolved through normal Node module lookup, so the package only needs to be installed (no path math against node_modules/ required). Project-specific files.includes and files.excludes stay in the consumer config.

ESLint (JavaScript / TypeScript)

ESLint runs alongside Biome, not in place of it. Biome keeps owning formatting and the fast syntactic lint; ESLint adds only the two things Biome structurally cannot express: this package's custom structural rules and the opt-in type-aware rules (the curated typescript-eslint set plus the type-driven custom rules). Add the linter, the typescript-eslint tooling, and this package to your dev dependencies:

The package exposes three flat-config entry points:

• @sinemacula/coding-standards/js/eslint - the base layer of syntax-only custom rules; needs no tsconfig, so it stays cheap and runs anywhere Biome runs.
• @sinemacula/coding-standards/js/eslint/type-checked - the opt-in type-aware layer. It includes the base layer and adds the cross-file / type-driven rules, so it needs a consumer tsconfig; use it in place of the base layer where one exists.
• @sinemacula/coding-standards/js/eslint/vue - the opt-in Vue layer for single-file components. Unlike the type-aware layer it carries no base rules of its own, so spread it alongside whichever layer the repository already uses rather than in place of one.

Create an eslint.config.js (or .qlty/configs/eslint.config.js when wired through Qlty) that spreads the layer you want. Without a tsconfig, use the base layer:

Where a tsconfig exists, use the type-aware layer instead (it already carries the base rules):

Vue repositories add the Vue toolchain and spread the Vue layer after the layer they already use:

The Vue layer registers the single-file-component parser (without it .vue files are not linted at all), resolves <script lang="ts"> blocks through the TypeScript parser, and holds component filenames to kebab-case. It also carries the template layout rules, which is the one place ESLint takes on formatting: Biome does not understand single-file components, so .vue markup would otherwise go unformatted entirely. Those rules are aligned to the shared four-space indent.

When wiring ESLint through Qlty, the shared eslint plugin sandbox installs only eslint, jest, and prettier by default, so the flat config's imports of this package and typescript-eslint fail to resolve. Widen the install filter in your .qlty/qlty.toml so the sandbox carries them (this repository's source.toml exports the same override, but source-exported plugin definitions do not reliably propagate, so mirror it consumer-side):

Repositories enabling the Vue layer widen the same filter further, since its plugins have to resolve inside that sandbox too:

Knip (JavaScript / TypeScript)

Qlty

Reference this repository as a source in your project's .qlty/qlty.toml, pinning tag to the latest release:

What's Included

Rules

These are the custom rules this package enforces on top of PSR-12. A deliberate exception can be bypassed with the native directive - // phpcs:ignore <code> for a sniff, @phpstan-ignore <identifier> for a rule, // eslint-disable-next-line <rule> for an ESLint rule.

PHPCS sniffs

PHPStan rules

ESLint rules

All rules run in the base layer except boolean-method-name, which resolves return types and so requires the opt-in type-checked layer.

boolean-method-name takes additionalPrefixes, additionalPredicates and additionalCommandVerbs (string arrays) to widen the accepted vocabulary from a consumer config. max-methods-per-class takes max, no-base-error takes allow, and require-copyright takes tags to adjust their defaults. align-doc-tags takes tags and column, the column counting from the @, so the default of 14 gives @author six spaces and @copyright three. Together single-line-property-doc and multiline-function-doc set a member's comment shape by its kind: data members (interface property signatures, enum members and data class fields) take one line, while methods, interface method signatures and class fields holding a function take several. A data comment is never required, only held to one line where present; a free function keeps the freedom of either shape.

The base layer also switches on a set of built-in rules: @typescript-eslint/no-explicit-any, max-lines-per-function (50 lines, test code exempt) and max-depth (4), plus eslint-plugin-jsdoc rules that require a documentation comment on every declared function, method, class, interface member and class field, forbid types in @param/@returns (the tags themselves are welcome, types belong in the signature) and keep a blank line above every documentation block, single-line blocks included. The type-checked layer adds @typescript-eslint/explicit-module-boundary-types and @typescript-eslint/only-throw-error.

Requirements

• PHP ^8.3 (Composer package)
• Node.js (npm package)

Testing

Changelog

See CHANGELOG.md for a list of notable changes.

Contributing

Contributions are welcome. Please read CONTRIBUTING.md for guidelines on branching, commits, code quality, and pull requests.

Security

If you discover a security vulnerability, please report it responsibly. See SECURITY.md for the disclosure policy and contact details.

License

Licensed under the Apache License, Version 2.0.