Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 1 addition & 0 deletions .agents/skills/php-forge-coding-standard
1 change: 1 addition & 0 deletions .claude/skills/php-forge-coding-standard
22 changes: 22 additions & 0 deletions .gitattributes
Original file line number Diff line number Diff line change
Expand Up @@ -41,3 +41,25 @@
# Avoid merge conflicts in CHANGELOG
# https://about.gitlab.com/2015/02/10/gitlab-reduced-merge-conflicts-by-90-percent-with-changelog-placeholders/
/CHANGELOG.md merge=union

/.agents export-ignore

/.claude export-ignore

/internal export-ignore
/vendor export-ignore
/node_modules export-ignore
/.env export-ignore
/.env.* export-ignore

/.phpunit.cache export-ignore

/.phpunit.result.cache export-ignore

/.stryker-tmp export-ignore

/.codex export-ignore

/.config export-ignore

/reports/mutation export-ignore
2 changes: 1 addition & 1 deletion .github/workflows/ecs.yml
Original file line number Diff line number Diff line change
Expand Up @@ -17,6 +17,6 @@ permissions:

jobs:
easy-coding-standard:
uses: yii2-framework/actions/.github/workflows/ecs.yml@a28eb7d4ab03abd53ccd7c79014b3b27d09932ff # v2.0.1
uses: php-forge/actions/.github/workflows/ecs.yml@a574dbe95fc370db1b7b5ea546cd5ff5b70304d6 # v3.0.0
with:
command-options: check src --config src/ecs-83.php --ansi
2 changes: 1 addition & 1 deletion .github/workflows/quality.yml
Original file line number Diff line number Diff line change
Expand Up @@ -10,7 +10,7 @@ permissions:

jobs:
quality:
uses: yii2-framework/actions/.github/workflows/quality.yml@a28eb7d4ab03abd53ccd7c79014b3b27d09932ff # v2.0.1
uses: php-forge/actions/.github/workflows/quality.yml@a574dbe95fc370db1b7b5ea546cd5ff5b70304d6 # v3.0.0
permissions:
contents: read
with:
Expand Down
2 changes: 1 addition & 1 deletion .github/workflows/security.yml
Original file line number Diff line number Diff line change
Expand Up @@ -10,7 +10,7 @@ permissions:

jobs:
security:
uses: yii2-framework/actions/.github/workflows/security.yml@a28eb7d4ab03abd53ccd7c79014b3b27d09932ff # v2.0.1
uses: php-forge/actions/.github/workflows/security.yml@a574dbe95fc370db1b7b5ea546cd5ff5b70304d6 # v3.0.0
permissions:
contents: read
with:
Expand Down
13 changes: 13 additions & 0 deletions .gitignore
Original file line number Diff line number Diff line change
Expand Up @@ -114,3 +114,16 @@ Thumbs.db
.buildpath
.project
.settings

# Package skill discovery; keep other local client state private.
!/.agents/
/.agents/*
!/.agents/skills/
/.agents/skills/*
!/.agents/skills/php-forge-coding-standard
!/.claude/
/.claude/*
!/.claude/skills/
/.claude/skills/*
!/.claude/skills/php-forge-coding-standard
/internal/
2 changes: 2 additions & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -7,6 +7,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0

## 0.3.5 Under development

- chore: standardize package guidance, skill discovery, configuration checks and security reporting.

## 0.3.4 September 07, 2026

- fix: support ECS `13.3.2+` with the native PER-CS set and explicit PHP `8.1-8.4` migration rules instead of the removed `withPhpCsFixerSets()` arguments.
Expand Down
46 changes: 28 additions & 18 deletions README.md
Original file line number Diff line number Diff line change
@@ -1,7 +1,7 @@
<!-- markdownlint-disable MD041 -->
<p align="center">
<a href="https://github.com/php-forge/coding-standard" target="_blank">
<img src="https://avatars.githubusercontent.com/u/103309199?s%25253D400%252526u%25253Dca3561c692f53ed7eb290d3bb226a2828741606f%252526v%25253D4" width="35%" alt="PHP Forge">
<img src="https://avatars.githubusercontent.com/u/103309199?s=400" width="35%" alt="PHP Forge">
</a>
<h1 align="center">Coding standard</h1>
<br>
Expand Down Expand Up @@ -40,21 +40,21 @@ Then run `composer update`.

This package ships shared ECS and Rector configurations under `vendor/php-forge/coding-standard/src/`:

| File | Purpose |
| ------------------- | ------------------------------------------------------- |
| `src/ecs.php` | Shared ECS base rules, no PHP migration set |
| `src/ecs-81.php` | Base + `@PHP81Migration` PHP-CS-Fixer set |
| `src/ecs-82.php` | Base + `@PHP82Migration` |
| `src/ecs-83.php` | Base + `@PHP83Migration` |
| `src/ecs-84.php` | Base + `@PHP84Migration` |
| `src/rector.php` | Shared Rector base rules, no PHP level set |
| `src/rector-81.php` | Base + `SetList::PHP_81` + `LevelSetList::UP_TO_PHP_81` |
| `src/rector-82.php` | Base + `SetList::PHP_82` + `LevelSetList::UP_TO_PHP_82` |
| `src/rector-83.php` | Base + `SetList::PHP_83` + `LevelSetList::UP_TO_PHP_83` |
| `src/rector-84.php` | Base + `SetList::PHP_84` + `LevelSetList::UP_TO_PHP_84` |

Pick the version that matches the **minimum** PHP your project supports; Rector upgrades code up to that level and
PHP-CS-Fixer enforces matching syntax. The plain `ecs.php` / `rector.php` apply no PHP-version migrations.
| File | Purpose |
| ----------------- | -------------------------------------------------- |
| src/ecs.php | Shared ECS base rules, no PHP migration set |
| src/ecs-81.php | Base + `@PHP81Migration` |
| src/ecs-82.php | Base + `@PHP82Migration` |
| src/ecs-83.php | Base + `@PHP82Migration` (no additional 8.3 rules) |
| src/ecs-84.php | Base + `@PHP84Migration` |
| src/rector.php | Shared Rector base rules, no PHP level set |
| src/rector-81.php | Base + `LevelSetList::UP_TO_PHP_81` |
| src/rector-82.php | Base + `LevelSetList::UP_TO_PHP_82` |
| src/rector-83.php | Base + `LevelSetList::UP_TO_PHP_83` |
| src/rector-84.php | Base + `LevelSetList::UP_TO_PHP_84` |

Pick the version that matches the **minimum** PHP your project supports; Rector applies migrations up to that level and
ECS applies the corresponding non-risky migration rules. These tools do not prove minimum-version compatibility. The plain `ecs.php` / `rector.php` apply no PHP-version migrations.

### ECS wrapper (ecs.php)

Expand Down Expand Up @@ -187,6 +187,16 @@ Follow the same convention used across PHP Forge repositories:
}
```

## Testing

Run `composer tests` to check that each versioned ECS and Rector configuration detects a sample transformation
without modifying the input. Development dependencies require PHP 8.3 or later; the package runtime supports PHP 8.1.

## AI assistance

Use the [php-forge-coding-standard skill](skills/php-forge-coding-standard/SKILL.md) and the [AI assistance guide](docs/agents.md) for
package-specific setup, invocation examples and verification.

## Package information

[![PHP](https://img.shields.io/badge/%3E%3D8.1-777BB4.svg?style=for-the-badge&logo=php&logoColor=white)](https://www.php.net/releases/8.1/en.php)
Expand All @@ -196,8 +206,8 @@ Follow the same convention used across PHP Forge repositories:
## Project status

[![Quality](https://img.shields.io/github/actions/workflow/status/php-forge/coding-standard/quality.yml?style=for-the-badge&label=Quality&logo=github)](https://github.com/php-forge/coding-standard/actions/workflows/quality.yml)
[![Security](https://img.shields.io/github/actions/workflow/status/php-forge/coding-standard/security.yml?style=for-the-badge&label=Security&logo=github)](https://github.com/php-forge/coding-standard/actions/workflows/security.yml)
[![StyleCI](https://img.shields.io/badge/StyleCI-Passed-44CC11.svg?style=for-the-badge&logo=github&logoColor=white)](https://github.styleci.io/repos/1141292628?branch=main)
[![Zizmor](https://img.shields.io/github/actions/workflow/status/php-forge/coding-standard/security.yml?style=for-the-badge&label=Zizmor&logo=github)](https://github.com/php-forge/coding-standard/actions/workflows/security.yml)
[![StyleCI](https://img.shields.io/badge/StyleCI-Passing-44CC11.svg?style=for-the-badge&logo=github&logoColor=white)](https://github.styleci.io/repos/1141292628?branch=main)

## Our social networks

Expand Down
4 changes: 3 additions & 1 deletion composer.json
Original file line number Diff line number Diff line change
Expand Up @@ -41,6 +41,9 @@
"allowed-packages": [
"php-forge/baseline"
]
},
"skills": {
"source": "skills"
}
},
"config": {
Expand All @@ -50,7 +53,6 @@
}
},
"scripts": {
"tests": "php tests/ecs.php",
"ecs": "./vendor/bin/ecs check src --config src/ecs-83.php --fix",
"rector": "./vendor/bin/rector process src --config src/rector-83.php"
}
Expand Down
55 changes: 55 additions & 0 deletions docs/agents.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,55 @@
# AI assistance

Use the package-owned [php-forge-coding-standard](../skills/php-forge-coding-standard/SKILL.md) skill for selecting PHP Forge ECS and Rector configurations for a supported PHP target. The canonical source is `skills/`; checkout discovery links in `.agents/skills/` and `.claude/skills/` point to that same source.

## Install in an application

Composer is the primary distribution path. `extra.skills.source` declares the bundle; installing the package alone does
not register its skill at the application root. In a consumer already configured for `llm/skills`, explicitly trust
`php-forge/coding-standard` and use that installed synchronizer's documented setup. Do not enable plugins or broaden trust by
copying an example. With verified auto-sync enabled, installation/update can synchronize the bundle; otherwise use
`composer skills:update` and inspect `composer skills:show`. Composer exit zero is not proof of client activation.

An optional pinned installer can use a local checkout or an installed package that contains the bundle:

```bash
npx skills@1.7.2 add /absolute/path/to/coding-standard --list
npx skills@1.7.2 add /absolute/path/to/coding-standard --skill php-forge-coding-standard --agent claude-code codex opencode
```

Keep project scope. Inspect a remote source with `--list` before claiming an unpublished skill is available there.
Copied installations must be refreshed after upgrades. The complete skill directory is the unit of installation.

## Discover and invoke

Open a fresh client session at the checkout or consumer root. Codex discovers `.agents/skills/php-forge-coding-standard/` and supports
`$php-forge-coding-standard` or its skill picker. Claude Code uses `.claude/skills/php-forge-coding-standard/` and `/php-forge-coding-standard`. For OpenCode, verify the
installed client's native skill tool and shared paths. Do not assume one client's invocation syntax works in another.

## Example prompts

Explicit Codex invocation:

```text
$php-forge-coding-standard
Prepare ECS and Rector wrappers for a PHP 8.1 consumer using this package. Preserve its src/tests paths and demonstrate dry-run commands; do not upgrade syntax to the host PHP version.
```

Natural selection:

```text
My project supports PHP 8.1 but runs tools on PHP 8.5. Configure its ECS and Rector wrappers using php-forge/coding-standard, preserve src and tests paths, and show non-mutating checks.
```

Record whether the client loads this skill rather than a global same-named copy. As an unrelated negative control, ask it to explain HTTP 301 versus 302 without inspecting the
repository or loading package skills.

## Verify the result

Capture the native load/tool evidence and selected source path, then execute the generated task checks against the
installed package. Cover the normal operation, the described boundary case and a failure/unsupported input. Inspect
generated code before executing it; use disposable fixtures for writes. Run the package's actual non-mutating checks
and report runtime versions, warnings and unavailable dependencies. Listing, manually reading the skill, or supplying
its body in a prompt does not prove native activation or functional execution.

[Back to README](../README.md)
10 changes: 5 additions & 5 deletions docs/svgs/features-mobile.svg
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
10 changes: 5 additions & 5 deletions docs/svgs/features.svg
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
35 changes: 35 additions & 0 deletions ecs.php
Original file line number Diff line number Diff line change
@@ -0,0 +1,35 @@
<?php

declare(strict_types=1);

use PhpCsFixer\Fixer\Import\NoUnusedImportsFixer;
use Symplify\EasyCodingStandard\Config\ECSConfig;

return ECSConfig::configure()
->withPaths([
__DIR__ . '/src',
__DIR__ . '/tests',
])
// include *.php files in the root directory
->withRootFiles()

// add a single rule
->withRules([
NoUnusedImportsFixer::class,
])

// add sets - group of rules, from easiest to more complex ones
// uncomment one, apply one, commit, PR, merge and repeat
//->withPreparedSets(
// spaces: true,
// namespaces: true,
// docblocks: true,
// arrays: true,
// comments: true,
//)

// ...but first: take it step by step
->withSpacesLevel(0)
->withArrayLevel(0)
->withControlStructuresLevel(0)
->withDocblockLevel(0);
32 changes: 32 additions & 0 deletions skills/php-forge-coding-standard/SKILL.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,32 @@
---
name: php-forge-coding-standard
description: Use when selecting PHP Forge ECS and Rector configurations for a supported PHP target.
license: BSD-3-Clause
---

# Use php-forge/coding-standard

## Resolve the package

Inspect the installed package path, actual source and Composer metadata before choosing APIs. The current PHP constraint
is `>=8.1`. A lockfile or branch alias alone does not prove the installed files match it. Use
local guides at that revision; if a guide is excluded from the archive, consult the matching repository revision, not
unverified current documentation. Installing this skill does not install dependencies or authorize mutations.

## Package contracts

Select `src/ecs-81.php` through `ecs-84.php` and the corresponding Rector configuration from the consumer's minimum
supported PHP version, not the interpreter currently running. For other minimum versions, inspect the available sets and explain that no matching wrapper is provided. Plain
`ecs.php` and `rector.php` do not select a migration level. Inspect actual configuration files: an ECS entrypoint returns a builder; the Rector configuration returns a
closure that receives `RectorConfig`. Do not assume interchangeable wrapper shapes.

Preserve consumer paths and justified skips. Run non-mutating checks first; ECS/Rector fix commands change files.
Do not raise the language target merely to clear a finding. Verify installed ECS/Rector compatibility and the selected
configuration with the consumer's tests.

## Verify the task

Run the relevant existing package checks and independent assertions for the selected operation. Read `composer.json`
scripts before executing them: fixers, installers and cleanup commands can mutate files. Use isolated synthetic inputs
for side-effecting behavior. Report the PHP version and missing dependencies. Distinguish native skill discovery,
activation, generated snippets and executed functional results; none substitutes for the others.
7 changes: 5 additions & 2 deletions src/ecs.php
Original file line number Diff line number Diff line change
Expand Up @@ -9,7 +9,7 @@
use PhpCsFixer\Fixer\PhpUnit\PhpUnitTestCaseStaticMethodCallsFixer;
use PhpCsFixer\Fixer\Strict\{DeclareStrictTypesFixer, StrictComparisonFixer, StrictParamFixer};
use PhpCsFixer\Fixer\StringNotation\SingleQuoteFixer;
use PhpCsFixer\Fixer\Whitespace\HeredocIndentationFixer;
use PhpCsFixer\Fixer\Whitespace\{HeredocIndentationFixer, NoExtraBlankLinesFixer};
use Symplify\EasyCodingStandard\Config\ECSConfig;

return ECSConfig::configure()
Expand Down Expand Up @@ -86,5 +86,8 @@
],
)
->withSkip(
[HeredocIndentationFixer::class],
[
HeredocIndentationFixer::class,
NoExtraBlankLinesFixer::class,
],
);
2 changes: 1 addition & 1 deletion src/rector.php
Original file line number Diff line number Diff line change
Expand Up @@ -14,7 +14,7 @@
* import either this file (no version target) or one of the version-pinned wrappers (`rector-81.php`, `rector-82.php`,
* `rector-83.php`, `rector-84.php`) and set their own paths.
*
* The version-pinned wrappers add the matching `SetList::PHP_XX` and `LevelSetList::UP_TO_PHP_XX` on top of this base.
* The version-pinned wrappers add the matching `LevelSetList::UP_TO_PHP_XX` on top of this base.
*/
return static function (RectorConfig $rectorConfig): void {
$rectorConfig->parallel();
Expand Down
Loading