@runtimestudio/tailwind-sort-php 0.2.1 → 0.4.0

package/LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2026 The Trustee for G&J Sevastos Family Trust t/a Runtime Studio
+Copyright (c) 2026 G&J Sevastos Family Trust t/a Runtime Studio
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

package/README.md

@@ -18,6 +18,15 @@ values, using a real PHP-aware lexer, and leaves everything else byte-identical.
 - **Zero-config** — reads `tailwindStylesheet` from your Prettier config, the same source of truth that
   `prettier-plugin-tailwindcss` uses.
 
+## Contents
+
+- [Requirements](#requirements) · [Install](#install) · [Setup](#setup) · [Usage](#usage)
+- [Editor integration](#editor-integration) — sort-on-save & pre-commit gate
+- [Sorting classes in PHP declarations](#sorting-classes-in-php-declarations) — the per-file opt-in
+- [WordPress themes & plugins](#wordpress-themes--plugins)
+- [How it handles mixed templates](#how-it-handles-mixed-templates) · [Programmatic API](#programmatic-api) · [Known limitations](#known-limitations)
+- [Development](#development) · [License](#license)
+
 ## Requirements
 
 - **Node ≥ 22.18**, or **Bun** — both run the CLI and the programmatic API.
@@ -44,8 +53,8 @@ vocabulary. Any config format Prettier supports works (`.prettierrc`, `prettier.
 
 ```js
 export default {
-  plugins: ['prettier-plugin-tailwindcss'],
-  tailwindStylesheet: './resources/css/main.css',
+    plugins: ['prettier-plugin-tailwindcss'],
+    tailwindStylesheet: './resources/css/main.css',
 };
 ```
 
@@ -75,18 +84,24 @@ npx tailwind-sort-php init
 
 ### Options
 
-| Flag                  | Description                                                                                       |
-|-----------------------|---------------------------------------------------------------------------------------------------|
-| `--stylesheet <path>` | Tailwind v4 CSS entry. Defaults to `tailwindStylesheet` from your Prettier config.                |
-| `--attr <name>`       | Extra attribute to sort (repeatable). Merged with `tailwindAttributes` from your Prettier config. |
-| `--check`             | Don't write; exit 1 if any file needs sorting.                                                    |
-| `--no-short-tags`     | Don't treat bare `<?` as a PHP open tag.                                                          |
+| Flag                  | Description                                                                                                                                                                                    |
+|-----------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
+| `--stylesheet <path>` | Tailwind v4 CSS entry. Defaults to `tailwindStylesheet` from your Prettier config.                                                                                                             |
+| `--attr <name>`       | Extra attribute to sort (repeatable). Merged with `tailwindAttributes` from your Prettier config.                                                                                              |
+| `--php-source <glob>` | Also sort class strings in PHP declarations in matching files (repeatable). Merged with `tailwindPhpSources`. See [Sorting classes in PHP declarations](#sorting-classes-in-php-declarations). |
+| `--check`             | Don't write; exit 1 if any file needs sorting.                                                                                                                                                 |
+| `--no-short-tags`     | Don't treat bare `<?` as a PHP open tag.                                                                                                                                                       |
+| `-h, --help`          | Show usage.                                                                                                                                                                                    |
+| `--version`           | Print the version.                                                                                                                                                                             |
 
 Default globs are all `.php` files under the cwd; `node_modules`, `vendor`, `dist`, and `.git` are always skipped.
 
 ## Editor integration
 
-No IDE plugin is needed — two small setups cover the common workflows.
+No IDE plugin is needed — two small setups cover the common workflows: sort-on-save and a pre-commit gate.
+
+<details>
+<summary><b>Sort on save</b> (PhpStorm / IntelliJ, VS Code) and a <b>pre-commit gate</b> — click to expand</summary>
 
 ### Sort on save (PhpStorm / IntelliJ)
 
@@ -107,14 +122,14 @@ to `.vscode/settings.json`:
 
 ```json
 {
-  "emeraldwalk.runonsave": {
-    "commands": [
-      {
-        "match": "\\.php$",
-        "cmd": "${workspaceFolder}/node_modules/.bin/tailwind-sort-php ${relativeFile}"
-      }
-    ]
-  }
+    "emeraldwalk.runonsave": {
+        "commands": [
+            {
+                "match": "\\.php$",
+                "cmd": "${workspaceFolder}/node_modules/.bin/tailwind-sort-php ${relativeFile}"
+            }
+        ]
+    }
 }
 ```
 
@@ -146,11 +161,103 @@ git diff --cached --name-only -z --diff-filter=ACMR -- '*.php' | xargs -0 ./node
 
 In CI there's no staged diff — just sweep the whole project with `npx tailwind-sort-php --check`.
 
+</details>
+
+## Sorting classes in PHP declarations
+
+By default, the tool only sorts classes inside HTML `class="..."` attributes. Class strings declared in **PHP itself** —
+constants, static properties, config arrays — sit inside PHP code the tool treats as opaque, so they're left alone.
+
+Opt in **per file** by listing the files whose PHP string values are Tailwind class lists, via `tailwindPhpSources` in
+your Prettier config (or the repeatable `--php-source <glob>` flag):
+
+```js
+export default {
+    plugins: ['prettier-plugin-tailwindcss'],
+    tailwindStylesheet: './resources/css/main.css',
+    tailwindPhpSources: ['src/classes/*.php'],
+};
+```
+
+With this set, every **string value** in a matched file is sorted with the exact same engine and order as the HTML
+side. In `key => value` arrays only the **value** is sorted — keys are never touched:
+
+```php
+// before
+public const array VARIANTS = array(
+    'primary'   => 'text-white px-4 bg-blue-600 rounded py-2',
+    'secondary' => 'text-gray-900 px-4 bg-gray-100 rounded py-2',
+);
+
+// after
+public const array VARIANTS = array(
+    'primary'   => 'rounded bg-blue-600 px-4 py-2 text-white',
+    'secondary' => 'rounded bg-gray-100 px-4 py-2 text-gray-900',
+);
+```
+
+Scalar declarations work the same way (`const string CARD = '...'`, `static $x = '...'`, `$x = '...'`), as do nested
+and list-style arrays.
+
+> **⚠️ Point `tailwindPhpSources` only at files whose string values are all Tailwind class lists.** The tool does
+> **not** guess whether a string "looks like" classes — within a matched file it sorts **every** eligible string value.
+> Aimed at a general file, it **will** reorder the words inside non-class strings (labels, URLs, SQL). This is a
+> deliberate design contract, not a bug: safety comes from your file-level opt-in, which is why a dedicated
+> directory of class-holder files (e.g. `src/classes/`) is the intended target.
+
+The opt-in is **inert at runtime** — it lives in formatter config only, never in your source. Your PHP stays vanilla,
+with zero coupling to this tool (no marker comments, no helper functions, no attributes).
+
+**Skipped automatically** (left byte-identical, even in a matched file):
+
+- Concatenated literals (`'btn-' . $variant`) — a fragment joined to dynamic code, unsafe to reorder.
+- Interpolated double-quoted strings (`"p-4 {$dynamic} flex"`).
+- Heredoc/nowdoc and backtick (shell-exec) strings, and strings containing escape sequences.
+
+**Off by default:** without `tailwindPhpSources` (and `--php-source`), behavior is identical to 0.2.x — no PHP
+declaration is ever touched.
+
+## WordPress themes & plugins
+
+Most WordPress sorting needs **no opt-in at all**. Template files and partials output markup, and the `class="..."`
+in that markup is sorted by the default HTML pass — even when the value is interrupted by PHP:
+
+```php
+<article <?php post_class( 'z-10 flex' ); ?>>
+  <h2 class="text-2xl font-bold <?= $featured ? 'text-amber-600' : '' ?> tracking-tight">
+```
+
+`tailwindPhpSources` is only for classes you store in **PHP values** — a variant map, a config array, theme defaults.
+For that, **don't opt in a general partial.** Partials are full of non-class strings — `__()` translations,
+`get_template_part()` names, query args, URLs — and an opted-in file sorts _every_ multi-word string value. The Tailwind
+sorter leaves most prose alone (unknown words keep their order), but it **will** reorder any string containing words
+that are also utilities (`grid`, `block`, `flex`, `hidden`, `container`, `table`, …), so `'Switch to grid view'`
+becomes `'Switch to view grid'`.
+
+Instead, keep class maps in a **dedicated file** whose every value is a class list, and opt in only that file:
+
+```php
+// inc/ui-classes.php   →   tailwindPhpSources: ['inc/ui-classes.php']
+return array(
+    'button' => array(
+        'primary'   => 'rounded bg-blue-600 px-4 py-2 text-white',
+        'secondary' => 'rounded bg-gray-100 px-4 py-2 text-gray-900',
+    ),
+    'card'   => 'rounded-lg border bg-white p-6 shadow-sm',
+);
+```
+
+`require` that map from your partials. The map file is 100% class strings (safe to sort); the partials stay out of
+`tailwindPhpSources` and get their markup sorted by the HTML pass as usual.
+
 ## How it handles mixed templates
 
 PHP islands inside a class attribute are treated as opaque atoms that never move. Static text between islands is sorted
 independently — the same model the official plugin uses for `${}` interpolations in template literals.
 
+<details>
+<summary>Glued-fragment pinning, whitespace handling, and the full edge-case list — click to expand</summary>
+
 ```php
 <!-- before -->
 <h2 class="text-2xl font-bold <?= $featured ? 'text-amber-600' : '' ?> tracking-tight leading-snug">
@@ -173,8 +280,12 @@ Also handled correctly:
 - `?>` inside `//` and `#` line comments (island ends — genuine PHP behavior)
 - `#[Attributes]`, `<?PHP` case-insensitivity, `<?xml` exclusion, files ending in PHP mode
 - PHP islands as standalone attributes: `<div <?php post_class(); ?> class="...">`
-- `<script>`/`<style>` content, HTML comments, and `echo '<div class="...">'` strings are left alone (sorting
-  `class="..."` inside PHP string literals could be added later as an opt-in)
+- With `tailwindPhpSources`, string values inside an island in a class attribute
+  (`class="p-4 <?= $on ? 'flex z-10' : '' ?>"`) sort in the same single pass
+- `<script>`/`<style>` content, HTML comments, and `echo '<div class="...">'` strings are left alone (to sort class
+  strings declared in PHP, see [Sorting classes in PHP declarations](#sorting-classes-in-php-declarations))
+
+</details>
 
 ## Programmatic API
 
@@ -190,6 +301,9 @@ const out = transform(source, sortFn);
 
 ## Known limitations
 
+<details>
+<summary>Edge cases and unsupported syntax — click to expand</summary>
+
 - Complex string interpolation containing double quotes (`"{$arr["key"]}"`) can desync the PHP string lexer in rare
   cases. Use `{$arr['key']}` style or extract to a variable.
 - Unquoted attribute values (`class=foo`) are skipped.
@@ -197,6 +311,8 @@ const out = transform(source, sortFn);
   classes).
 - Whitespace inside multi-line class attributes is normalized to single spaces (matches Prettier behavior).
 
+</details>
+
 ## Development
 
 ```sh
@@ -204,10 +320,11 @@ bun test      # or: node --test "test/*.test.ts"
 bun run build # compile src → dist (tsc); the published artifact
 ```
 
-54 tests: 41 core tests that are dependency-free (the sorter is injected, so they run against a mock `SortFn`), 5
-integration tests that exercise the real `prettier-plugin-tailwindcss` sorter and skip automatically when the Tailwind
-toolchain isn't installed, and 8 `init` tests that run against throwaway git repositories and skip when `git` is
-unavailable.
+84 tests: 63 core tests that are dependency-free (the sorter is injected, so they run against a mock `SortFn`),
+7 integration tests that exercise the real `prettier-plugin-tailwindcss` sorter and skip automatically when the
+Tailwind toolchain isn't installed, 8 `init` tests that run against throwaway git repositories and skip when
+`git` is unavailable, and 6 CLI tests covering argument validation, help/version output, and file-scanning rules
+(the scan test also skips without the Tailwind toolchain).
 
 ## License
 

package/dist/cli.d.ts

@@ -1,18 +1,9 @@
 #!/usr/bin/env node
 /**
- * tailwind-sort-php CLI
+ * tailwind-sort-php CLI — see `USAGE` for the flag reference.
  *
- * Usage:
- *   tailwind-sort-php [options] [glob ...]
- *   tailwind-sort-php init [--fix] [--force] [--dry-run]
- *
- * Options:
- *   --stylesheet <path> Tailwind v4 CSS entry
- *   --attr <name> Extra attribute to sort (repeatable)
- *   --check Don't write; exit 1 if any file needs sorting
- *   --no-short-tags Don't treat bare `<?` as a PHP open tag
- *
- * Defaults to all `.php` files under `cwd` when no globs are given.
- * Skips `node_modules`, `vendor`, `dist` and `.git`. The `init` subcommand installs the pre-commit hook; see `init.ts`.
+ * Option values fall back to the resolved Prettier config — the same source of truth `prettier-plugin-tailwindcss`
+ * uses; see `fromPrettierConfig()`.
+ * The `init` subcommand installs the pre-commit hook; see `init.ts`.
  */
 export {};

package/dist/cli.js

@@ -1,24 +1,31 @@
 #!/usr/bin/env node
 /**
- * tailwind-sort-php CLI
+ * tailwind-sort-php CLI — see `USAGE` for the flag reference.
  *
- * Usage:
- *   tailwind-sort-php [options] [glob ...]
- *   tailwind-sort-php init [--fix] [--force] [--dry-run]
- *
- * Options:
- *   --stylesheet <path> Tailwind v4 CSS entry
- *   --attr <name> Extra attribute to sort (repeatable)
- *   --check Don't write; exit 1 if any file needs sorting
- *   --no-short-tags Don't treat bare `<?` as a PHP open tag
- *
- * Defaults to all `.php` files under `cwd` when no globs are given.
- * Skips `node_modules`, `vendor`, `dist` and `.git`. The `init` subcommand installs the pre-commit hook; see `init.ts`.
+ * Option values fall back to the resolved Prettier config — the same source of truth `prettier-plugin-tailwindcss`
+ * uses; see `fromPrettierConfig()`.
+ * The `init` subcommand installs the pre-commit hook; see `init.ts`.
  */
 import { readFile, writeFile } from 'node:fs/promises';
 import { transform } from "./transform.js";
 import { createTailwindSortFn } from "./sorter.js";
 import { runInit } from "./init.js";
+const USAGE = `Usage:
+  tailwind-sort-php [options] [glob ...]
+  tailwind-sort-php init [--fix] [--force] [--dry-run]
+
+Options:
+  --stylesheet <path>  Tailwind v4 CSS entry (default: tailwindStylesheet from your Prettier config)
+  --attr <name>        Extra attribute to sort (repeatable; merged with tailwindAttributes)
+  --php-source <glob>  Also sort class strings in PHP declarations in matching files
+                       (repeatable; merged with tailwindPhpSources)
+  --check              Don't write; exit 1 if any file needs sorting
+  --no-short-tags      Don't treat bare <? as a PHP open tag
+  -h, --help           Show this help
+  --version            Print the version
+
+Defaults to all .php files under the cwd when no globs are given;
+node_modules, vendor, dist and .git are always skipped.`;
 const IGNORE = ['node_modules', 'vendor', 'dist', '.git'];
 /**
  * Parse command-line arguments.
@@ -30,21 +37,24 @@ function parseArgs(argv) {
     const cli = {
         globs: [],
         attrs: ['class', 'className'],
+        phpSources: [],
         check: false,
         shortTags: true,
     };
     for (let i = 0; i < argv.length; i++) {
         const a = argv[i];
-        if (a === '--check')
+        if (a === '--stylesheet')
+            cli.stylesheet = requireValue(argv, ++i, a);
+        else if (a === '--attr')
+            cli.attrs.push(requireValue(argv, ++i, a));
+        else if (a === '--php-source')
+            cli.phpSources.push(requireValue(argv, ++i, a));
+        else if (a === '--check')
             cli.check = true;
         else if (a === '--no-short-tags')
             cli.shortTags = false;
-        else if (a === '--stylesheet')
-            cli.stylesheet = argv[++i];
-        else if (a === '--attr')
-            cli.attrs.push(argv[++i]);
         else if (a.startsWith('--')) {
-            console.error(`Unknown option: ${a}`);
+            console.error(`Unknown option: ${a}\n\n${USAGE}`);
             process.exit(2);
         }
         else
@@ -54,6 +64,17 @@ function parseArgs(argv) {
         cli.globs.push('**/*.php');
     return cli;
 }
+/**
+ * Return a flag's value argument or exit with a usage error when it is missing or is itself a flag.
+ */
+function requireValue(argv, i, flag) {
+    const v = argv[i];
+    if (v === undefined || v.startsWith('--')) {
+        console.error(`Missing value for ${flag}`);
+        process.exit(2);
+    }
+    return v;
+}
 /**
  * Yield file paths matching the given globs, using `Bun.Glob` under Bun and `node:fs` glob (Node >= 22) otherwise.
  *
@@ -69,8 +90,10 @@ async function* scanFiles(globs) {
     }
     else {
         const { glob } = await import('node:fs/promises');
+        // Prunes ignored directories during traversal; newer Node versions pass a Dirent instead of a path string.
+        const exclude = (entry) => ignored(typeof entry === 'string' ? entry : entry.name);
         for (const pattern of globs) {
-            for await (const f of glob(pattern))
+            for await (const f of glob(pattern, { exclude }))
                 yield f;
         }
     }
@@ -81,13 +104,12 @@ async function* scanFiles(globs) {
  * @param file Path to test, relative to `cwd`.
  * @returns True when the path is inside an ignored directory and should be skipped.
  */
-const ignored = (file) => IGNORE.some((d) => file.includes(`${d}/`) || file.startsWith(d));
+const ignored = (file) => file.split(/[\\/]/).some((seg) => IGNORE.includes(seg));
 /**
- * Best-effort read of the project's resolved Prettier config, so this tool shares one source of truth with
- * `prettier-plugin-tailwindcss`. Picks up `tailwindStylesheet` (resolved relative to the config file) and
- * `tailwindAttributes` (merged into the attribute list).
+ * Best-effort read of the resolved Prettier config — the shared source of truth with `prettier-plugin-tailwindcss`.
+ * Picks up `tailwindStylesheet`, `tailwindAttributes`, and `tailwindPhpSources`.
  *
- * @returns The resolved stylesheet path and attributes, or an empty object if none are available.
+ * @returns The found settings, or an empty object if none are available.
  */
 async function fromPrettierConfig() {
     try {
@@ -106,6 +128,9 @@ async function fromPrettierConfig() {
         if (Array.isArray(cfg.tailwindAttributes)) {
             out.attributes = cfg.tailwindAttributes.filter((a) => typeof a === 'string' && !a.startsWith('/'));
         }
+        if (Array.isArray(cfg.tailwindPhpSources)) {
+            out.phpSources = cfg.tailwindPhpSources.filter((p) => typeof p === 'string');
+        }
         return out;
     }
     catch {
@@ -114,6 +139,16 @@ async function fromPrettierConfig() {
 }
 async function main() {
     const argv = process.argv.slice(2);
+    // Help/version take precedence everywhere, including after `init`.
+    if (argv.includes('--help') || argv.includes('-h')) {
+        console.log(USAGE);
+        return;
+    }
+    if (argv.includes('--version')) {
+        const pkg = JSON.parse(await readFile(new URL('../package.json', import.meta.url), 'utf8'));
+        console.log(pkg.version);
+        return;
+    }
     if (argv[0] === 'init')
         return runInit(argv.slice(1));
     const cli = parseArgs(argv);
@@ -135,24 +170,32 @@ async function main() {
         attributes: cli.attrs,
         shortOpenTags: cli.shortTags,
     };
+    // Pre-scan the opt-in `tailwindPhpSources` globs; a file gets `sortPhpStrings` only if it matches one.
+    const phpSources = [...cli.phpSources, ...(pc.phpSources ?? [])];
+    const phpSourceFiles = new Set();
+    for await (const file of scanFiles(phpSources)) {
+        if (!ignored(file))
+            phpSourceFiles.add(file);
+    }
     let scanned = 0;
     let changed = 0;
-    for (const pattern of cli.globs) {
-        for await (const file of scanFiles([pattern])) {
-            if (ignored(file))
-                continue;
-            scanned++;
-            const src = await readFile(file, 'utf8');
-            const out = transform(src, sortFn, opts);
-            if (out !== src) {
-                changed++;
-                if (cli.check) {
-                    console.log(`needs sorting: ${file}`);
-                }
-                else {
-                    await writeFile(file, out);
-                    console.log(`sorted: ${file}`);
-                }
+    const seen = new Set();
+    // Include php-source files so a designated holder is sorted even outside the main globs; `seen` dedupes.
+    for await (const file of scanFiles([...cli.globs, ...phpSources])) {
+        if (ignored(file) || seen.has(file))
+            continue;
+        seen.add(file);
+        scanned++;
+        const src = await readFile(file, 'utf8');
+        const out = transform(src, sortFn, { ...opts, sortPhpStrings: phpSourceFiles.has(file) });
+        if (out !== src) {
+            changed++;
+            if (cli.check) {
+                console.log(`needs sorting: ${file}`);
+            }
+            else {
+                await writeFile(file, out);
+                console.log(`sorted: ${file}`);
             }
         }
     }

package/dist/html.js

@@ -47,6 +47,7 @@ export function findClassAttributes(masked, opts = {}) {
     const wanted = new Set((opts.attributes ?? ['class', 'classname']).map((a) => a.toLowerCase()));
     const out = [];
     const len = masked.length;
+    const lower = masked.toLowerCase();
     let i = 0;
     while (i < len) {
         const lt = masked.indexOf('<', i);
@@ -75,12 +76,12 @@ export function findClassAttributes(masked, opts = {}) {
             let j = lt + 1;
             while (j < len && /[A-Za-z0-9:-]/.test(masked[j]))
                 j++;
-            const tagName = masked.slice(lt + 1, j).toLowerCase();
+            const tagName = lower.slice(lt + 1, j);
             j = scanTagAttributes(masked, j, wanted, out);
             // Skip raw-text element content up to its closing tag.
             if (RAW_TEXT_TAGS.has(tagName)) {
                 const closer = `</${tagName}`;
-                const idx = masked.toLowerCase().indexOf(closer, j);
+                const idx = lower.indexOf(closer, j);
                 j = idx === -1 ? len : idx;
             }
             i = j;

package/dist/index.d.ts

@@ -10,4 +10,5 @@
 export { transform, type SortFn, type TransformOptions } from './transform.ts';
 export { findIslands, type Island, type IslandOptions } from './islands.ts';
 export { maskIslands, findClassAttributes, type ClassAttr, type HtmlScanOptions } from './html.ts';
+export { findSortablePhpStrings, type PhpStringRange } from './php-strings.ts';
 export { createTailwindSortFn, type SorterOptions } from './sorter.ts';

package/dist/index.js

@@ -10,4 +10,5 @@
 export { transform } from "./transform.js";
 export { findIslands } from "./islands.js";
 export { maskIslands, findClassAttributes } from "./html.js";
+export { findSortablePhpStrings } from "./php-strings.js";
 export { createTailwindSortFn } from "./sorter.js";

package/dist/init.js

@@ -132,7 +132,11 @@ export async function runInit(argv) {
     let repairMode = false;
     if (current !== null && current !== hookBody) {
         if (!cli.force) {
-            const installed = current === HOOK_CHECK ? 'the check variant' : current === HOOK_FIX ? 'the --fix variant' : 'a custom hook';
+            const installed = current === HOOK_CHECK
+                ? 'the check variant'
+                : current === HOOK_FIX
+                    ? 'the --fix variant'
+                    : 'a custom hook';
             fail(`${HOOK_PATH} already exists and differs (${installed} is installed). Re-run with --force to overwrite.`);
         }
         writeHook = true;
@@ -148,7 +152,9 @@ export async function runInit(argv) {
             await writeFile(hookAbs, hookBody);
             await chmod(hookAbs, 0o755);
         }
-        done.push(cli.dryRun ? `would install ${HOOK_PATH} (${variant} variant)` : `installed ${HOOK_PATH} (${variant} variant)`);
+        done.push(cli.dryRun
+            ? `would install ${HOOK_PATH} (${variant} variant)`
+            : `installed ${HOOK_PATH} (${variant} variant)`);
     }
     if (repairMode) {
         if (!cli.dryRun)