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
45 changes: 45 additions & 0 deletions .agents/skills/php-forge-diff/SKILL.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,45 @@
---
name: php-forge-diff
description: Integrate or troubleshoot php-forge/diff line edit scripts and unified diff rendering in PHP applications. Use for LineDiffer, DifferInterface, or UnifiedDiffRenderer; exclude applying patches and unrelated Git operations.
license: BSD-3-Clause
metadata:
source: https://github.com/php-forge/diff
---

# Use php-forge/diff

Inspect the installed revision and its `composer.json`, source and guides before choosing an API. For a dependency,
resolve Composer's installed path and reference; a path checkout can contain uncommitted changes. Compare the lock file,
which may describe a different installation. Use documentation matching the installed files and report a gap if it
cannot be found. PHP 8.3 or later is required by the current package.

## Choose the result

Use `(new PHPForge\Diff\LineDiffer())->diff($old, $new)` for an ordered list of `DiffLine` objects with
`DiffOp::Context`, `Remove`, or `Add`. It splits both strings literally on `"\n"`: an empty string is one empty line and
a trailing newline produces an empty final line. Remove `Add` entries to reconstruct the old input, or `Remove` entries
for the new input, joining the remaining `line` values with `"\n"`. It does not normalize line endings.

Use `(new PHPForge\Diff\UnifiedDiffRenderer())->render($old, $new, $fromLabel, $toLabel, $context)` for unified text;
`$context` is optional and defaults to `3`. It normalizes CRLF and CR to LF, returns an empty string for normalized
equal texts and otherwise returns a patch without a trailing newline or Git's `diff --git` and `index` headers. Negative
context is treated as zero. Missing final newlines are represented by `\ No newline at end of file`. Labels are supplied
by the caller; this renderer does not read files, apply patches, or escape labels for untrusted presentation.

A custom `DifferInterface` can be injected into the renderer. Its script must reconstruct both inputs in order. The
renderer takes the rendered lines from the texts by operation position and does not validate `DiffLine::line`: a script
whose operations do not consume both inputs exactly throws `LogicException`, while a balanced script with wrong
operations renders an incorrect diff without any error. Test a non-empty change as well as empty inputs because the
renderer handles empty sides separately. Do not swallow `LogicException` as an empty diff.

The default differ follows Git's default xdiff pipeline and indent heuristic, but lacks Git's cost limit. Its edit
script is not guaranteed shortest or identical to Git on expensive inputs. Do not promise binary diff support or exact
byte preservation after renderer line-ending normalization.

## Verify

Use the application's existing tests and the package's `docs/examples.md`, `docs/algorithms.md` and `docs/testing.md` at
the matching revision. Assert both reconstructed sides, unchanged inputs, empty sides, trailing-newline differences,
line-ending normalization, requested context and custom-differ failure as relevant. If comparing with Git, disable user
and system Git configuration and document the chosen options. Record installation, client discovery, native skill
loading, actual task behavior and test results separately; reading this file alone proves no activation.
42 changes: 27 additions & 15 deletions .gitattributes
Original file line number Diff line number Diff line change
Expand Up @@ -4,38 +4,50 @@
# ...Unless the name matches the following overriding patterns

# Definitively text files
*.php text
*.css text
*.js text
*.txt text
*.md text
*.xml text
*.json text
*.bat text
*.sql text
*.yml text
*.php text
*.css text
*.js text
*.txt text
*.md text
*.xml text
*.json text
*.json5 text
*.neon text
*.bat text
*.sql text
*.yml text
*.yaml text
*.svg text

# Ensure those won't be messed up with
*.png binary
*.jpg binary
*.gif binary
*.ttf binary
*.png binary
*.jpg binary
*.gif binary
*.ttf binary

# Exclude files from the archive
/.agents export-ignore
/.claude export-ignore
/.editorconfig export-ignore
/.gitattributes export-ignore
/.github export-ignore
/.gitignore export-ignore
/.prettierignore export-ignore
/.prettierrc.json export-ignore
/.styleci.yml export-ignore
/.stylelintignore export-ignore
/AGENTS.md export-ignore
/codeception.yml export-ignore
/codecov.yml export-ignore
/composer-require-checker.json export-ignore
/docs export-ignore
/ecs.php export-ignore
/infection.json* export-ignore
/internal export-ignore
/phpstan*.neon* export-ignore
/phpunit.xml.dist export-ignore
/rector.php export-ignore
/runtime export-ignore
/testo.php export-ignore
/tests export-ignore

# Avoid merge conflicts in CHANGELOG
Expand Down
7 changes: 2 additions & 5 deletions .github/workflows/build.yml
Original file line number Diff line number Diff line change
Expand Up @@ -16,10 +16,7 @@ permissions:
contents: read

jobs:
phpunit:
uses: yii2-framework/actions/.github/workflows/phpunit.yml@a28eb7d4ab03abd53ccd7c79014b3b27d09932ff # v2.0.1
with:
extensions: gd, intl
php-version: '["8.3","8.4","8.5"]'
testo:
uses: php-forge/actions/.github/workflows/testo.yml@72def618dcf8a77705c26faa53e9f8b1dc1f53bb # v3.0.1
secrets:
CODECOV_TOKEN: ${{ secrets.CODECOV_TOKEN }}
1 change: 1 addition & 0 deletions .gitignore
Original file line number Diff line number Diff line change
@@ -1,4 +1,5 @@
# AI agents (if present)
.agents/skills/testo-*
.codex
.claude

Expand Down
1 change: 1 addition & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -8,6 +8,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
## 0.3.0 Under development

- feat!: rename package to `php-forge/scaffold` with namespace `PHPForge\Scaffold`; update `require`, `allow-plugins` and class references.
- feat!: overhaul sync, merge modes and CLI; enforce strict manifests and locks; support Console 8 and drop Composer runtime dependency.

## 0.2.0 July 04, 2026

Expand Down
122 changes: 73 additions & 49 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -10,7 +10,7 @@

<p align="center">
<a href="https://github.com/php-forge/scaffold/actions/workflows/build.yml" target="_blank">
<img src="https://img.shields.io/github/actions/workflow/status/php-forge/scaffold/build.yml?style=for-the-badge&label=PHPUnit&logo=github" alt="PHPUnit">
<img src="https://img.shields.io/github/actions/workflow/status/php-forge/scaffold/build.yml?style=for-the-badge&label=Testo&logo=github" alt="Testo">
</a>
<a href="https://dashboard.stryker-mutator.io/reports/github.com/php-forge/scaffold/main" target="_blank">
<img src="https://img.shields.io/endpoint?style=for-the-badge&url=https%3A%2F%2Fbadge-api.stryker-mutator.io%2Fgithub.com%2Fphp-forge%2Fscaffold%2Fmain" alt="Mutation Testing">
Expand Down Expand Up @@ -39,90 +39,106 @@

```bash
composer config allow-plugins.php-forge/scaffold true
composer require php-forge/scaffold:^0.3
composer require --dev php-forge/scaffold:^0.3
```

Install your scaffold providers, then declare which are permitted to write files into your project:
Require the providers and list, in order, the ones allowed to write files into the project:

```json
{
"require-dev": {
"php-forge/baseline": "^0.2",
"php-forge/coding-standard": "^0.3",
"php-forge/scaffold": "^0.3"
},
"config": {
"allow-plugins": {
"php-forge/scaffold": true
}
},
"extra": {
"scaffold": {
"allowed-packages": [
"php-forge/baseline",
"php-forge/coding-standard"
]
"allowed-packages": ["php-forge/baseline", "php-forge/coding-standard"]
}
}
}
```

Run `composer install` to trigger the scaffold process. Commit `scaffold-lock.json` to version control.
Run `composer install`. The plugin copies the provider files, merges the shared ones, writes `scaffold-lock.json` and
prints one summary line:

To opt out of auto-trigger and manage updates manually via `vendor/bin/scaffold`, set `auto: false` (see
[Configuration Reference](docs/configuration.md#auto)):

```json
{
"extra": {
"scaffold": {
"auto": false,
"allowed-packages": ["php-forge/baseline", "php-forge/coding-standard"]
}
}
}
```text
[scaffold] 10 files written, 1 unchanged, 1 warning.
```

Review the result with `git diff` and commit the files together with `scaffold-lock.json`.

## Configuration

Scaffold configuration for a project with `php-forge/baseline` and `php-forge/coding-standard` already installed:
| Setting | Default | Effect |
| --------------------------------- | ------- | ------------------------------------------------------------------------------------------------- |
| `extra.scaffold.allowed-packages` | `[]` | Providers allowed to write files, in order; the later provider wins when two ship the same file. |
| `extra.scaffold.auto` | `true` | `false` disables the Composer hooks; apply the providers with `vendor/bin/scaffold sync` instead. |

Providers choose a mode per file: `replace` (provider-owned, skipped once you edit it), `preserve` (seeded once, then
yours), `append` (format-aware merge for `.editorconfig`, `.gitignore` and similar files) or `prepend`. The lock records
the owner, the mode and two hashes per file:

```json
{
"require": {
"php-forge/scaffold": "^0.3"
},
"config": {
"allow-plugins": {
"php-forge/scaffold": true
"providers": {
"php-forge/baseline": {
"version": "0.2.0",
"path": "vendor/php-forge/baseline"
}
},
"extra": {
"scaffold": {
"allowed-packages": [
"php-forge/baseline",
"php-forge/coding-standard"
]
"files": {
".styleci.yml": {
"hash": "sha256:825f8c744ffbd2bc2369712e7192b8694129a8ecbc3fd91dc9300fccecf827bd",
"provider": "php-forge/baseline",
"source": "metadata/.styleci.yml",
"mode": "replace",
"stub-hash": "sha256:825f8c744ffbd2bc2369712e7192b8694129a8ecbc3fd91dc9300fccecf827bd"
}
}
}
```

`hash` is the file as scaffold last left it and `stub-hash` the provider source at that moment, so scaffold can tell
your edits apart from provider updates.

## Console commands

After `composer install`, the plugin ships a standalone Symfony Console CLI at `vendor/bin/scaffold` that works in any
PHP project (Yii2, Yii3, Laravel, Symfony, plain PHP).
The plugin installs a standalone console application at `vendor/bin/scaffold`. Every command finds the project root by
walking up to the nearest `composer.json`; the global `--working-dir` (`-d`) option starts the search elsewhere.

| Command | What it does |
| ------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------ |
| `vendor/bin/scaffold status` | Prints a table comparing every tracked file's on-disk hash to the one recorded in `scaffold-lock.json` (`synced` / `modified` / `missing`). |
| `vendor/bin/scaffold providers` | Lists every provider recorded in `scaffold-lock.json` and how many files each one contributed. |
| `vendor/bin/scaffold diff <file>` | Shows a line-by-line diff between the provider stub and the current on-disk file. |
| `vendor/bin/scaffold reapply [file] [--force] [--provider=<name>]` | Re-copies stubs from `vendor/` to the project, updating lock hashes on success. Without `--force`, user-modified files are reported and skipped. |
| `vendor/bin/scaffold eject <file> [--yes]` | Removes a file entry from `scaffold-lock.json` without deleting the file from disk. Without `--yes` only previews the change. |
| Command | What it does |
| -------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------- |
| `status [--format=table\|json] [--exit-code]` | Shows each file as `synced`, `pending`, `outdated`, `modified`, `conflict`, `missing`, `orphan`, `ejected` or `error`. |
| `diff <file>\|--all [--exit-code]` | Shows what applying the providers would change, as a unified diff from the current file. |
| `reapply [<file>] [--provider=<name>] [--force] [--dry-run] [--exit-code]` | Applies the stubs of tracked files again; `--force` also takes user-modified, `preserve` and ejected files. |
| `eject <file> [--yes]` | Marks a file as yours; no run writes it again until `reapply <file> --force`. |
| `prune [--force] [--delete-modified] [--exit-code]` | Lists files no allowed provider ships anymore; `--force` deletes the unmodified ones and drops the entries. |
| `sync [--dry-run] [--exit-code] [--force]` | Applies every allowed provider outside Composer, for `auto: false`, `--no-plugins` runs and bots. |
| `providers` | Lists the providers recorded in `scaffold-lock.json` with their file counts. |

Typical post-install workflow:
Typical workflow after `composer install` or `composer update`:

```bash
vendor/bin/scaffold status # what changed
vendor/bin/scaffold diff config/params.php # review one file
vendor/bin/scaffold reapply config/params.php --force # accept stub version
vendor/bin/scaffold status # what needs attention
vendor/bin/scaffold diff --all # what applying the providers would change
vendor/bin/scaffold reapply .styleci.yml --force # take the provider version of a file you edited
vendor/bin/scaffold eject .styleci.yml --yes # or keep yours for good
vendor/bin/scaffold prune # review files the providers no longer ship
```

# or
vendor/bin/scaffold eject config/params.php --yes # keep yours, stop tracking
Gate CI on drift between the committed files and the providers:

```bash
vendor/bin/scaffold status --exit-code
```

See [`docs/console.md`](docs/console.md) for the full reference.
Upgrading from `yii2-extensions/scaffold` `0.2`? Read [UPGRADE.md](UPGRADE.md).

## Documentation

Expand All @@ -132,6 +148,7 @@ See [`docs/console.md`](docs/console.md) for the full reference.
- 🔀 [File Modes](docs/modes.md)
- 🖥️ [Console Commands](docs/console.md)
- 🧪 [Testing Guide](docs/testing.md)
- ⬆️ [Upgrade Guide](UPGRADE.md)

## Package information

Expand All @@ -141,10 +158,17 @@ See [`docs/console.md`](docs/console.md) for the full reference.

## Project status

[![Codecov](https://img.shields.io/codecov/c/github/php-forge/scaffold.svg?style=for-the-badge&logo=codecov&logoColor=white&label=Coverage)](https://codecov.io/github/php-forge/scaffold)
[![PHPStan Level Max](https://img.shields.io/badge/PHPStan-Level%20Max-4F5D95.svg?style=for-the-badge&logo=github&logoColor=white)](https://github.com/php-forge/scaffold/actions/workflows/static.yml)
[![Quality](https://img.shields.io/github/actions/workflow/status/php-forge/scaffold/quality.yml?style=for-the-badge&label=Quality&logo=github)](https://github.com/php-forge/scaffold/actions/workflows/quality.yml)
[![StyleCI](https://img.shields.io/badge/StyleCI-Passed-44CC11.svg?style=for-the-badge&logo=github&logoColor=white)](https://github.styleci.io/repos/1212894073?branch=main)

## Built with AI

[![Built with Claude Code](https://img.shields.io/badge/Built%20with-Claude%20Code-D97757.svg?style=for-the-badge&logo=claude&logoColor=white)](https://claude.com/claude-code)
[![Reviewed by Codex](https://img.shields.io/badge/Reviewed%20by-Codex-10A37F.svg?style=for-the-badge&logo=openaigym&logoColor=white)](https://openai.com/codex)
[![Reviewed by CodeRabbit](https://img.shields.io/badge/Reviewed%20by-CodeRabbit-FF570A.svg?style=for-the-badge&logo=coderabbit&logoColor=white)](https://www.coderabbit.ai)

## Our social networks

[![Follow on X](https://img.shields.io/badge/-Follow%20on%20X-1DA1F2.svg?style=for-the-badge&logo=x&logoColor=white&labelColor=000000)](https://x.com/Terabytesoftw)
Expand Down
Loading
Loading