Skip to content

Commit b2ecc44

Browse files
driadedriade
committed
feat - add llms.md info por ai - first version
1 parent 9bc9f79 commit b2ecc44

1 file changed

Lines changed: 119 additions & 0 deletions

File tree

‎llms.md‎

Lines changed: 119 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,119 @@
1+
# phpfmt (PHP formatter)
2+
3+
## Purpose
4+
5+
- **Sublime Text 4 package** that formats PHP code by invoking a PHP-based formatting engine.
6+
- The engine is a pipeline of **passes** (transformations) applied over PHP tokens.
7+
- Includes a fixture-based test harness (`.in`/`.out`) and a PHPUnit test suite.
8+
9+
## Repository layout
10+
11+
- `fmt.stub.php`
12+
- Main formatter implementation (pass classes, `CodeFormatter`, helpers).
13+
- Also acts as the PHP CLI script that Sublime Text calls (it prints a usage message when run without the expected args).
14+
- The fixture test harness loads this file and instantiates `CodeFormatter` directly.
15+
- `phpfmt.py`
16+
- **Sublime Text plugin entrypoint** (`sublime_plugin`) that:
17+
- Reads `phpfmt.sublime-settings`.
18+
- Builds a PHP command line.
19+
- Executes PHP against `fmt.stub.php` with the configured options.
20+
- When documenting “how the editor integration works”, this is the key file.
21+
- `php.tools.ini`
22+
- Default configuration file passed to the PHP formatter from the Sublime plugin.
23+
- `phpfmt.sublime-settings`
24+
- Sublime package settings (php binary path, passes, excludes, PSR/WP toggles, etc.).
25+
- `tests/`
26+
- `run_all_tests.php`: fixture test harness.
27+
- `Original/`: non-PSR fixtures.
28+
- `PSR/`: PSR-style fixtures (PSR decorator applied by the harness).
29+
- `Unit/`: PHPUnit unit tests (if present/used).
30+
- `vendor/`
31+
- Composer dependencies, including PHPUnit.
32+
33+
## Running tests
34+
35+
### 1) Fixture tests (`.in`/`.out`)
36+
37+
- Run the full fixture suite:
38+
- From `tests/`: `php ./run_all_tests.php`
39+
- Run a subset by test number prefix:
40+
- `php ./run_all_tests.php --testNumber 525`
41+
- Show diffs (verbose):
42+
- `php ./run_all_tests.php -v`
43+
- `php ./run_all_tests.php --testNumber 525 -v`
44+
45+
### Harness notes
46+
47+
- The harness supports a few special `//...` comments inside `.in` fixtures (parsed via `token_get_all()` in `tests/run_all_tests.php`).
48+
49+
- `//passes:PassA,PassB,...`
50+
- Forces a specific list of passes for that test.
51+
- Example: `//passes:AutoSemicolon`
52+
- `Default` is a special value: `//passes:Default` enables a default set plus PSR decoration.
53+
- Pass parameters are supported via `PassName|argument`.
54+
55+
- `//excludes:PassA,PassB,...`
56+
- Disables specific passes for that test.
57+
58+
- `//version:X.Y.Z`
59+
- Skips the test when the running PHP version is **lower** than `X.Y.Z`.
60+
61+
- `//versionup:X.Y.Z`
62+
- Skips the test when the running PHP version is **higher** than `X.Y.Z`.
63+
64+
- `//skipShortTag`
65+
- If `short_open_tag` is disabled in the current runtime and the fixture contains `//skipShortTag` in inline HTML, the test is skipped.
66+
67+
- If there is **no** `//passes:...` or `//excludes:...`, the harness applies a baseline set and calls `PsrDecorator::decorate($fmt)`.
68+
69+
- Some tests may be skipped depending on PHP version or `short_open_tag` settings (see the logic in `tests/run_all_tests.php`).
70+
71+
### 2) PHPUnit
72+
73+
- Run from the repository root:
74+
- `./vendor/bin/phpunit`
75+
76+
## Creating a new fixture test (`.in`/`.out`)
77+
78+
1) Pick a new number
79+
80+
- In `tests/Original/` or `tests/PSR/`, use the next available number to avoid collisions.
81+
- Example: if the current max is `524`, create `525-some-case.in` and `525-some-case.out`.
82+
83+
2) Write the `.in`
84+
85+
- The `.in` should reproduce the formatting case.
86+
- Optional: specify passes explicitly:
87+
- `//passes:AutoSemicolon,ResizeSpaces` (comma-separated)
88+
89+
3) Produce the `.out`
90+
91+
- Run the harness in verbose mode to see the diff and adjust the expected output:
92+
- `php tests/run_all_tests.php --testNumber 525 -v`
93+
- Edit the `.out` until the test passes.
94+
95+
4) Validate
96+
97+
- Run the specific fixture test:
98+
- `php tests/run_all_tests.php --testNumber 525`
99+
- Run the full fixture suite and PHPUnit before finishing a change:
100+
- `php tests/run_all_tests.php`
101+
- `./vendor/bin/phpunit`
102+
103+
## Debugging tips
104+
105+
- To see which passes execute, use `FMTDEBUG` (see conditions in `fmt.stub.php`).
106+
107+
- Example (prints the formatter output after each executed pass):
108+
- `export FMTDEBUG=1; php tests/run_all_tests.php --testNumber 525 -v`
109+
110+
- Step mode (waits for Enter between passes):
111+
- `export FMTDEBUG=step; php tests/run_all_tests.php --testNumber 525 -v`
112+
113+
- Disable afterwards:
114+
- `unset FMTDEBUG`
115+
116+
Notes:
117+
- This mode is intentionally noisy; use it with a single test number.
118+
- `FMTDEBUG` changes the `CodeFormatter` subclass used at runtime to print intermediate states after each pass.
119+
- If a change touches whitespace or special token sequences (e.g., heredoc/nowdoc), review passes like `ResizeSpaces` and any code that uses `printUntil(...)` or otherwise skips ranges of tokens.

0 commit comments

Comments
 (0)