@runtimestudio/tailwind-sort-php 0.3.0 → 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

@@ -91,6 +91,8 @@ npx tailwind-sort-php init
 | `--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.
 
@@ -278,6 +280,8 @@ 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="...">`
+- 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))
 
@@ -316,10 +320,11 @@ bun test      # or: node --test "test/*.test.ts"
 bun run build # compile src → dist (tsc); the published artifact
 ```
 
-74 tests: 59 core tests that are dependency-free (the sorter is injected, so they run against a mock `SortFn`),
+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, and 8 `init` tests that run against throwaway git repositories and skip when
-`git` is unavailable.
+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,19 +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)
- *   --php-source <glob> Also sort class strings in PHP declarations in matching files (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,25 +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)
- *   --php-source <glob> Also sort class strings in PHP declarations in matching files (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.
@@ -37,18 +43,18 @@ function parseArgs(argv) {
     };
     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 === '--php-source')
-            cli.phpSources.push(argv[++i]);
         else if (a.startsWith('--')) {
-            console.error(`Unknown option: ${a}`);
+            console.error(`Unknown option: ${a}\n\n${USAGE}`);
             process.exit(2);
         }
         else
@@ -58,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.
  *
@@ -73,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;
         }
     }
@@ -85,7 +104,7 @@ 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 resolved Prettier config — the shared source of truth with `prettier-plugin-tailwindcss`.
  * Picks up `tailwindStylesheet`, `tailwindAttributes`, and `tailwindPhpSources`.
@@ -120,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);

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/islands.js

@@ -9,8 +9,7 @@
  *
  * @see html.ts - second pass; consumes islands via `maskIslands()`.
  */
-const isIdentStart = (c) => /[A-Za-z_\u0080-\uffff]/.test(c);
-const isIdent = (c) => /[A-Za-z0-9_\u0080-\uffff]/.test(c);
+import { isIdent, scanHeredoc, scanLineComment, scanQuoted } from "./php-lexer.js";
 /**
  * Find every PHP island in a mixed PHP/HTML template source.
  *
@@ -69,23 +68,23 @@ function scanPhpBody(src, i) {
             return i + 2;
         // Single-quoted string.
         if (c === "'") {
-            i = scanQuoted(src, i + 1, "'");
+            i = Math.min(scanQuoted(src, i + 1, "'", len) + 1, len);
             continue;
         }
         // Double-quoted string.
         // Limitation: nested double quotes in complex `{$a["k"]}` interpolation can desync the lexer; see README.
         if (c === '"') {
-            i = scanQuoted(src, i + 1, '"');
+            i = Math.min(scanQuoted(src, i + 1, '"', len) + 1, len);
             continue;
         }
         // Backtick (shell exec) string — same escaping rules.
         if (c === '`') {
-            i = scanQuoted(src, i + 1, '`');
+            i = Math.min(scanQuoted(src, i + 1, '`', len) + 1, len);
             continue;
         }
         // Comments.
         if (c === '/' && src[i + 1] === '/') {
-            i = scanLineComment(src, i + 2);
+            i = scanLineComment(src, i + 2, len);
             if (src.startsWith('?>', i))
                 return i + 2;
             continue;
@@ -96,7 +95,7 @@ function scanPhpBody(src, i) {
                 i += 2;
                 continue;
             }
-            i = scanLineComment(src, i + 1);
+            i = scanLineComment(src, i + 1, len);
             if (src.startsWith('?>', i))
                 return i + 2;
             continue;
@@ -108,7 +107,7 @@ function scanPhpBody(src, i) {
         }
         // Heredoc / nowdoc.
         if (c === '<' && src[i + 1] === '<' && src[i + 2] === '<') {
-            const here = scanHeredoc(src, i + 3);
+            const here = scanHeredoc(src, i + 3, len);
             if (here !== -1) {
                 i = here;
                 continue;
@@ -118,89 +117,3 @@ function scanPhpBody(src, i) {
     }
     return len; // file ends while still in PHP mode
 }
-/**
- * Scan a quoted string body; `i` is just past the open quote.
- * Returns offset just past the closing quote (or EOF).
- */
-function scanQuoted(src, i, quote) {
-    const len = src.length;
-    while (i < len) {
-        const c = src[i];
-        if (c === '\\') {
-            i += 2;
-            continue;
-        }
-        if (c === quote)
-            return i + 1;
-        i++;
-    }
-    return len;
-}
-/**
- * Scan a `//` or `#` line comment body, which ends at a newline or at `?>`.
- * Returns the offset past a consumed newline, or the offset of an unconsumed `?>`
- * (left for the caller, since `?>` closes both the comment and the island).
- */
-function scanLineComment(src, i) {
-    const len = src.length;
-    while (i < len) {
-        if (src[i] === '\n')
-            return i + 1;
-        if (src[i] === '?' && src[i + 1] === '>')
-            return i;
-        i++;
-    }
-    return len;
-}
-/**
- * Scan a heredoc/nowdoc; `i` is just past `<<<`.
- * Returns the offset past the closing identifier line, or -1 if `<<<` isn't followed by a valid heredoc identifier.
- */
-function scanHeredoc(src, i) {
-    const len = src.length;
-    // Optional whitespace (PHP allows spaces/tabs after `<<<`).
-    while (i < len && (src[i] === ' ' || src[i] === '\t'))
-        i++;
-    // Optional quote around the identifier.
-    let quote = '';
-    if (src[i] === "'" || src[i] === '"') {
-        quote = src[i];
-        i++;
-    }
-    if (i >= len || !isIdentStart(src[i]))
-        return -1;
-    const idStart = i;
-    while (i < len && isIdent(src[i]))
-        i++;
-    const id = src.slice(idStart, i);
-    if (quote) {
-        if (src[i] !== quote)
-            return -1;
-        i++;
-    }
-    // After the identifier, the line must end immediately — PHP disallows trailing whitespace,
-    // but we tolerate `\r` so `\r\n` endings still work.
-    while (i < len && src[i] === '\r')
-        i++;
-    if (src[i] !== '\n')
-        return -1;
-    i++;
-    // Find a line that starts with optional indentation,
-    // then the identifier followed by a non-identifier character
-    // (PHP 7.3 flexible syntax).
-    while (i < len) {
-        let j = i;
-        while (j < len && (src[j] === ' ' || src[j] === '\t'))
-            j++;
-        if (src.startsWith(id, j)) {
-            const k = j + id.length;
-            if (k >= len || !isIdent(src[k]))
-                return k;
-        }
-        const nl = src.indexOf('\n', i);
-        if (nl === -1)
-            return len;
-        i = nl + 1;
-    }
-    return len;
-}

package/dist/php-lexer.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Shared low-level PHP lexing helpers.
+ *
+ * Used by both passes that read PHP code — island detection (`islands.ts`) and string harvesting (`php-strings.ts`)
+ * — so the two can never drift apart on string/comment/heredoc boundary rules.
+ *
+ * All scanners operate on the `[i, end)` window of the source and return offsets within it.
+ */
+export declare const isIdentStart: (c: string) => boolean;
+export declare const isIdent: (c: string) => boolean;
+/**
+ * Scan a quoted string body; `i` is just past the open quote.
+ *
+ * @returns The offset of the closing quote, or `end` when unterminated.
+ */
+export declare function scanQuoted(src: string, i: number, quote: string, end: number): number;
+/**
+ * Scan a `//` or `#` line comment body, which ends at a newline or at `?>`.
+ *
+ * @returns The offset past a consumed newline, or the offset of an unconsumed `?>`
+ *          (left for the caller, since `?>` closes both the comment and the island).
+ */
+export declare function scanLineComment(src: string, i: number, end: number): number;
+/**
+ * Scan a heredoc/nowdoc; `i` is just past `<<<`.
+ *
+ * @returns The offset past the closing identifier, or -1 if `<<<` isn't followed by a valid heredoc identifier.
+ */
+export declare function scanHeredoc(src: string, i: number, end: number): number;

package/dist/php-lexer.js

@@ -0,0 +1,96 @@
+/**
+ * Shared low-level PHP lexing helpers.
+ *
+ * Used by both passes that read PHP code — island detection (`islands.ts`) and string harvesting (`php-strings.ts`)
+ * — so the two can never drift apart on string/comment/heredoc boundary rules.
+ *
+ * All scanners operate on the `[i, end)` window of the source and return offsets within it.
+ */
+export const isIdentStart = (c) => /[A-Za-z_\u0080-\uffff]/.test(c);
+export const isIdent = (c) => /[A-Za-z0-9_\u0080-\uffff]/.test(c);
+/**
+ * Scan a quoted string body; `i` is just past the open quote.
+ *
+ * @returns The offset of the closing quote, or `end` when unterminated.
+ */
+export function scanQuoted(src, i, quote, end) {
+    while (i < end) {
+        const c = src[i];
+        if (c === '\\') {
+            i += 2;
+            continue;
+        }
+        if (c === quote)
+            return i;
+        i++;
+    }
+    return end;
+}
+/**
+ * Scan a `//` or `#` line comment body, which ends at a newline or at `?>`.
+ *
+ * @returns The offset past a consumed newline, or the offset of an unconsumed `?>`
+ *          (left for the caller, since `?>` closes both the comment and the island).
+ */
+export function scanLineComment(src, i, end) {
+    while (i < end) {
+        if (src[i] === '\n')
+            return i + 1;
+        if (src[i] === '?' && src[i + 1] === '>')
+            return i;
+        i++;
+    }
+    return end;
+}
+/**
+ * Scan a heredoc/nowdoc; `i` is just past `<<<`.
+ *
+ * @returns The offset past the closing identifier, or -1 if `<<<` isn't followed by a valid heredoc identifier.
+ */
+export function scanHeredoc(src, i, end) {
+    // Optional whitespace (PHP allows spaces/tabs after `<<<`).
+    while (i < end && (src[i] === ' ' || src[i] === '\t'))
+        i++;
+    // Optional quote around the identifier.
+    let quote = '';
+    if (src[i] === "'" || src[i] === '"') {
+        quote = src[i];
+        i++;
+    }
+    if (i >= end || !isIdentStart(src[i]))
+        return -1;
+    const idStart = i;
+    while (i < end && isIdent(src[i]))
+        i++;
+    const id = src.slice(idStart, i);
+    if (quote) {
+        if (src[i] !== quote)
+            return -1;
+        i++;
+    }
+    // After the identifier, the line must end immediately — PHP disallows trailing whitespace,
+    // but we tolerate `\r` so `\r\n` endings still work.
+    while (i < end && src[i] === '\r')
+        i++;
+    if (src[i] !== '\n')
+        return -1;
+    i++;
+    // Find a line that starts with optional indentation,
+    // then the identifier followed by a non-identifier character
+    // (PHP 7.3 flexible syntax).
+    while (i < end) {
+        let j = i;
+        while (j < end && (src[j] === ' ' || src[j] === '\t'))
+            j++;
+        if (src.startsWith(id, j)) {
+            const k = j + id.length;
+            if (k >= end || !isIdent(src[k]))
+                return k;
+        }
+        const nl = src.indexOf('\n', i);
+        if (nl === -1 || nl >= end)
+            return end;
+        i = nl + 1;
+    }
+    return end;
+}

package/dist/php-strings.js

@@ -19,8 +19,7 @@
  * @see islands.ts   - first pass; produces the islands consumed here.
  * @see transform.ts - splices the sorted strings back via the shared byte-replacement path.
  */
-const isIdentStart = (c) => /[A-Za-z_€-￿]/.test(c);
-const isIdent = (c) => /[A-Za-z0-9_€-￿]/.test(c);
+import { isIdent, isIdentStart, scanHeredoc, scanLineComment, scanQuoted } from "./php-lexer.js";
 /**
  * Find every sortable string-literal value within the given PHP islands.
  *
@@ -74,11 +73,11 @@ function tokenizeIsland(src, start, end) {
         }
         // Line comments (`//`, `#`) — but `#[` opens a PHP 8 attribute, which is code.
         if (c === '/' && src[i + 1] === '/') {
-            i = skipLineComment(src, i + 2, end);
+            i = scanLineComment(src, i + 2, end);
             continue;
         }
         if (c === '#' && src[i + 1] !== '[') {
-            i = skipLineComment(src, i + 1, end);
+            i = scanLineComment(src, i + 1, end);
             continue;
         }
         // Block comment.
@@ -89,7 +88,7 @@ function tokenizeIsland(src, start, end) {
         }
         // Heredoc / nowdoc — never harvested; skip the whole construct.
         if (c === '<' && src[i + 1] === '<' && src[i + 2] === '<') {
-            const here = skipHeredoc(src, i + 3, end);
+            const here = scanHeredoc(src, i + 3, end);
             if (here !== -1) {
                 i = here;
                 pushOther();
@@ -142,35 +141,6 @@ function tokenizeIsland(src, start, end) {
     }
     return tokens;
 }
-/**
- * Scan a quoted string body; `i` is just past the open quote. Returns the offset of the closing quote (or `end`).
- */
-function scanQuoted(src, i, quote, end) {
-    while (i < end) {
-        const c = src[i];
-        if (c === '\\') {
-            i += 2;
-            continue;
-        }
-        if (c === quote)
-            return i;
-        i++;
-    }
-    return end;
-}
-/**
- * Skip a `//`/`#` line comment body, ending at a newline or `?>`. Returns the offset to resume scanning from.
- */
-function skipLineComment(src, i, end) {
-    while (i < end) {
-        if (src[i] === '\n')
-            return i + 1;
-        if (src[i] === '?' && src[i + 1] === '>')
-            return i;
-        i++;
-    }
-    return end;
-}
 /**
  * True if a double-quoted body contains interpolation (an unescaped `$`) or any escape sequence.
  */
@@ -184,47 +154,3 @@ function hasInterpolationOrEscape(body) {
     }
     return false;
 }
-/**
- * Skip a heredoc/nowdoc; `i` is just past `<<<`. Returns the offset past the closing identifier line,
- * or -1 if `<<<` isn't followed by a valid heredoc identifier. Mirrors the boundary rules of the island lexer.
- */
-function skipHeredoc(src, i, end) {
-    while (i < end && (src[i] === ' ' || src[i] === '\t'))
-        i++;
-    let quote = '';
-    if (src[i] === "'" || src[i] === '"') {
-        quote = src[i];
-        i++;
-    }
-    if (i >= end || !isIdentStart(src[i]))
-        return -1;
-    const idStart = i;
-    while (i < end && isIdent(src[i]))
-        i++;
-    const id = src.slice(idStart, i);
-    if (quote) {
-        if (src[i] !== quote)
-            return -1;
-        i++;
-    }
-    while (i < end && src[i] === '\r')
-        i++;
-    if (src[i] !== '\n')
-        return -1;
-    i++;
-    while (i < end) {
-        let j = i;
-        while (j < end && (src[j] === ' ' || src[j] === '\t'))
-            j++;
-        if (src.startsWith(id, j)) {
-            const k = j + id.length;
-            if (k >= end || !isIdent(src[k]))
-                return k;
-        }
-        const nl = src.indexOf('\n', i);
-        if (nl === -1 || nl >= end)
-            return end;
-        i = nl + 1;
-    }
-    return end;
-}

package/dist/transform.js

@@ -36,43 +36,64 @@ export function transform(src, sortFn, opts = {}) {
     const islands = findIslands(src, opts);
     const masked = maskIslands(src, islands);
     const attrs = findClassAttributes(masked, opts);
-    // Collect every edit as a {start, end, text} range, then apply them back-to-front so offsets stay valid.
-    // HTML class-attribute values live outside islands; PHP string values live inside them, so the two sets of
-    // ranges never overlap.
-    const edits = [];
-    for (const { valueStart, valueEnd } of attrs) {
-        const original = src.slice(valueStart, valueEnd);
-        const inner = islands.filter((isl) => isl.start >= valueStart && isl.end <= valueEnd);
-        const rewritten = rewriteValue(original, valueStart, inner, sortFn);
-        if (rewritten !== original)
-            edits.push({ start: valueStart, end: valueEnd, text: rewritten });
-    }
+    // Computed before the attribute pass: an edit inside a class-attribute island must be folded into that
+    // attribute's rewrite, or the enclosing rewrite would overwrite it and a second pass would be needed.
+    const phpEdits = [];
     if (opts.sortPhpStrings) {
         for (const { start, end } of findSortablePhpStrings(src, islands)) {
             const original = src.slice(start, end);
             const tokens = original.split(/\s+/).filter(Boolean);
             if (tokens.length < 2)
                 continue; // nothing to reorder; leave byte-identical
-            const rewritten = sortFn(tokens).join(' ');
-            if (rewritten !== original)
-                edits.push({ start, end, text: rewritten });
+            const text = sortFn(tokens).join(' ');
+            if (text !== original)
+                phpEdits.push({ start, end, text });
         }
     }
+    // Collect every edit as a {start, end, text} range, then apply them back-to-front so offsets stay valid.
+    const edits = [];
+    const absorbed = new Set();
+    for (const { valueStart, valueEnd } of attrs) {
+        const original = src.slice(valueStart, valueEnd);
+        const inner = islands.filter((isl) => isl.start >= valueStart && isl.end <= valueEnd);
+        const innerEdits = phpEdits.filter((e) => e.start >= valueStart && e.end <= valueEnd);
+        const rewritten = rewriteValue(original, valueStart, inner, sortFn, innerEdits);
+        if (rewritten !== original)
+            edits.push({ start: valueStart, end: valueEnd, text: rewritten });
+        for (const e of innerEdits)
+            absorbed.add(e);
+    }
+    for (const e of phpEdits)
+        if (!absorbed.has(e))
+            edits.push(e);
     edits.sort((a, b) => b.start - a.start);
     let out = src;
     for (const e of edits)
         out = out.slice(0, e.start) + e.text + out.slice(e.end);
     return out;
 }
-function rewriteValue(value, base, islands, sortFn) {
-    // Build alternating static/island parts.
+/**
+ * Apply the edits that fall entirely within `[offset, offset + text.length)` to `text`.
+ * Edits arrive in document order and never overlap, so a back-to-front pass keeps offsets valid.
+ */
+function spliceEdits(text, offset, edits) {
+    for (let k = edits.length - 1; k >= 0; k--) {
+        const e = edits[k];
+        if (e.start < offset || e.end > offset + text.length)
+            continue;
+        text = text.slice(0, e.start - offset) + e.text + text.slice(e.end - offset);
+    }
+    return text;
+}
+function rewriteValue(value, base, islands, sortFn, phpEdits) {
+    // Build alternating static/island parts; island text carries any PHP-string edits it contains.
     const parts = [];
     let pos = 0;
     for (const isl of islands) {
         const s = isl.start - base;
         const e = isl.end - base;
         parts.push({ type: 'static', text: value.slice(pos, s) });
-        parts.push({ type: 'island', text: value.slice(s, e) });
+        parts.push({ type: 'island', text: spliceEdits(value.slice(s, e), isl.start, phpEdits) });
         pos = e;
     }
     parts.push({ type: 'static', text: value.slice(pos) });

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@runtimestudio/tailwind-sort-php",
-    "version": "0.3.0",
+    "version": "0.4.0",
     "description": "Tailwind CSS Class Sorter for PHP",
     "keywords": [
         "class-sorting",
@@ -39,9 +39,9 @@
     },
     "devDependencies": {
         "@types/bun": "latest",
-        "prettier": "^3.8",
+        "prettier": "^3.9",
         "prettier-plugin-tailwindcss": "^0.8",
-        "tailwindcss": "^4",
+        "tailwindcss": "^4.3",
         "typescript": ">=5.7"
     },
     "peerDependencies": {

package/src/cli.ts

@@ -1,20 +1,10 @@
 #!/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)
- *   --php-source <glob> Also sort class strings in PHP declarations in matching files (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';
@@ -22,6 +12,23 @@ import { transform, type TransformOptions } from './transform.ts';
 import { createTailwindSortFn } from './sorter.ts';
 import { runInit } from './init.ts';
 
+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'];
 
 interface Cli {
@@ -49,13 +56,13 @@ function parseArgs(argv: string[]): Cli {
     };
     for (let i = 0; i < argv.length; i++) {
         const a = argv[i];
-        if (a === '--check') cli.check = true;
+        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 === '--php-source') cli.phpSources.push(argv[++i]);
         else if (a.startsWith('--')) {
-            console.error(`Unknown option: ${a}`);
+            console.error(`Unknown option: ${a}\n\n${USAGE}`);
             process.exit(2);
         } else cli.globs.push(a);
     }
@@ -63,6 +70,18 @@ function parseArgs(argv: string[]): Cli {
     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: string[], i: number, flag: string): string {
+    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.
  *
@@ -76,8 +95,10 @@ async function* scanFiles(globs: string[]): AsyncGenerator<string> {
         }
     } 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: string | { name: string }) => ignored(typeof entry === 'string' ? entry : entry.name);
         for (const pattern of globs) {
-            for await (const f of glob(pattern)) yield f as string;
+            for await (const f of glob(pattern, { exclude })) yield f as string;
         }
     }
 }
@@ -88,7 +109,7 @@ async function* scanFiles(globs: string[]): AsyncGenerator<string> {
  * @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: string) => IGNORE.some((d) => file.includes(`${d}/`) || file.startsWith(d));
+const ignored = (file: string) => file.split(/[\\/]/).some((seg) => IGNORE.includes(seg));
 
 /**
  * Best-effort read of the resolved Prettier config — the shared source of truth with `prettier-plugin-tailwindcss`.
@@ -128,6 +149,18 @@ async function fromPrettierConfig(): Promise<{
 
 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);

package/src/html.ts

@@ -79,6 +79,7 @@ export function findClassAttributes(masked: string, opts: HtmlScanOptions = {}):
     const wanted = new Set((opts.attributes ?? ['class', 'classname']).map((a) => a.toLowerCase()));
     const out: ClassAttr[] = [];
     const len = masked.length;
+    const lower = masked.toLowerCase();
     let i = 0;
 
     while (i < len) {
@@ -110,14 +111,14 @@ export function findClassAttributes(masked: string, opts: HtmlScanOptions = {}):
         if (lt + 1 < len && /[A-Za-z]/.test(masked[lt + 1])) {
             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/src/islands.ts

@@ -10,6 +10,8 @@
  * @see html.ts - second pass; consumes islands via `maskIslands()`.
  */
 
+import { isIdent, scanHeredoc, scanLineComment, scanQuoted } from './php-lexer.ts';
+
 /**
  * A contiguous region of PHP code within a mixed template source.
  */
@@ -35,9 +37,6 @@ export interface IslandOptions {
     shortOpenTags?: boolean;
 }
 
-const isIdentStart = (c: string) => /[A-Za-z_\u0080-\uffff]/.test(c);
-const isIdent = (c: string) => /[A-Za-z0-9_\u0080-\uffff]/.test(c);
-
 /**
  * Find every PHP island in a mixed PHP/HTML template source.
  *
@@ -99,26 +98,26 @@ function scanPhpBody(src: string, i: number): number {
 
         // Single-quoted string.
         if (c === "'") {
-            i = scanQuoted(src, i + 1, "'");
+            i = Math.min(scanQuoted(src, i + 1, "'", len) + 1, len);
             continue;
         }
 
         // Double-quoted string.
         // Limitation: nested double quotes in complex `{$a["k"]}` interpolation can desync the lexer; see README.
         if (c === '"') {
-            i = scanQuoted(src, i + 1, '"');
+            i = Math.min(scanQuoted(src, i + 1, '"', len) + 1, len);
             continue;
         }
 
         // Backtick (shell exec) string — same escaping rules.
         if (c === '`') {
-            i = scanQuoted(src, i + 1, '`');
+            i = Math.min(scanQuoted(src, i + 1, '`', len) + 1, len);
             continue;
         }
 
         // Comments.
         if (c === '/' && src[i + 1] === '/') {
-            i = scanLineComment(src, i + 2);
+            i = scanLineComment(src, i + 2, len);
             if (src.startsWith('?>', i)) return i + 2;
             continue;
         }
@@ -128,7 +127,7 @@ function scanPhpBody(src: string, i: number): number {
                 i += 2;
                 continue;
             }
-            i = scanLineComment(src, i + 1);
+            i = scanLineComment(src, i + 1, len);
             if (src.startsWith('?>', i)) return i + 2;
             continue;
         }
@@ -140,7 +139,7 @@ function scanPhpBody(src: string, i: number): number {
 
         // Heredoc / nowdoc.
         if (c === '<' && src[i + 1] === '<' && src[i + 2] === '<') {
-            const here = scanHeredoc(src, i + 3);
+            const here = scanHeredoc(src, i + 3, len);
             if (here !== -1) {
                 i = here;
                 continue;
@@ -152,85 +151,3 @@ function scanPhpBody(src: string, i: number): number {
 
     return len; // file ends while still in PHP mode
 }
-
-/**
- * Scan a quoted string body; `i` is just past the open quote.
- * Returns offset just past the closing quote (or EOF).
- */
-function scanQuoted(src: string, i: number, quote: string): number {
-    const len = src.length;
-    while (i < len) {
-        const c = src[i];
-        if (c === '\\') {
-            i += 2;
-            continue;
-        }
-        if (c === quote) return i + 1;
-        i++;
-    }
-    return len;
-}
-
-/**
- * Scan a `//` or `#` line comment body, which ends at a newline or at `?>`.
- * Returns the offset past a consumed newline, or the offset of an unconsumed `?>`
- * (left for the caller, since `?>` closes both the comment and the island).
- */
-function scanLineComment(src: string, i: number): number {
-    const len = src.length;
-    while (i < len) {
-        if (src[i] === '\n') return i + 1;
-        if (src[i] === '?' && src[i + 1] === '>') return i;
-        i++;
-    }
-    return len;
-}
-
-/**
- * Scan a heredoc/nowdoc; `i` is just past `<<<`.
- * Returns the offset past the closing identifier line, or -1 if `<<<` isn't followed by a valid heredoc identifier.
- */
-function scanHeredoc(src: string, i: number): number {
-    const len = src.length;
-    // Optional whitespace (PHP allows spaces/tabs after `<<<`).
-    while (i < len && (src[i] === ' ' || src[i] === '\t')) i++;
-
-    // Optional quote around the identifier.
-    let quote = '';
-    if (src[i] === "'" || src[i] === '"') {
-        quote = src[i];
-        i++;
-    }
-
-    if (i >= len || !isIdentStart(src[i])) return -1;
-    const idStart = i;
-    while (i < len && isIdent(src[i])) i++;
-    const id = src.slice(idStart, i);
-
-    if (quote) {
-        if (src[i] !== quote) return -1;
-        i++;
-    }
-
-    // After the identifier, the line must end immediately — PHP disallows trailing whitespace,
-    // but we tolerate `\r` so `\r\n` endings still work.
-    while (i < len && src[i] === '\r') i++;
-    if (src[i] !== '\n') return -1;
-    i++;
-
-    // Find a line that starts with optional indentation,
-    // then the identifier followed by a non-identifier character
-    // (PHP 7.3 flexible syntax).
-    while (i < len) {
-        let j = i;
-        while (j < len && (src[j] === ' ' || src[j] === '\t')) j++;
-        if (src.startsWith(id, j)) {
-            const k = j + id.length;
-            if (k >= len || !isIdent(src[k])) return k;
-        }
-        const nl = src.indexOf('\n', i);
-        if (nl === -1) return len;
-        i = nl + 1;
-    }
-    return len;
-}

package/src/php-lexer.ts

@@ -0,0 +1,93 @@
+/**
+ * Shared low-level PHP lexing helpers.
+ *
+ * Used by both passes that read PHP code — island detection (`islands.ts`) and string harvesting (`php-strings.ts`)
+ * — so the two can never drift apart on string/comment/heredoc boundary rules.
+ *
+ * All scanners operate on the `[i, end)` window of the source and return offsets within it.
+ */
+
+export const isIdentStart = (c: string) => /[A-Za-z_\u0080-\uffff]/.test(c);
+export const isIdent = (c: string) => /[A-Za-z0-9_\u0080-\uffff]/.test(c);
+
+/**
+ * Scan a quoted string body; `i` is just past the open quote.
+ *
+ * @returns The offset of the closing quote, or `end` when unterminated.
+ */
+export function scanQuoted(src: string, i: number, quote: string, end: number): number {
+    while (i < end) {
+        const c = src[i];
+        if (c === '\\') {
+            i += 2;
+            continue;
+        }
+        if (c === quote) return i;
+        i++;
+    }
+    return end;
+}
+
+/**
+ * Scan a `//` or `#` line comment body, which ends at a newline or at `?>`.
+ *
+ * @returns The offset past a consumed newline, or the offset of an unconsumed `?>`
+ *          (left for the caller, since `?>` closes both the comment and the island).
+ */
+export function scanLineComment(src: string, i: number, end: number): number {
+    while (i < end) {
+        if (src[i] === '\n') return i + 1;
+        if (src[i] === '?' && src[i + 1] === '>') return i;
+        i++;
+    }
+    return end;
+}
+
+/**
+ * Scan a heredoc/nowdoc; `i` is just past `<<<`.
+ *
+ * @returns The offset past the closing identifier, or -1 if `<<<` isn't followed by a valid heredoc identifier.
+ */
+export function scanHeredoc(src: string, i: number, end: number): number {
+    // Optional whitespace (PHP allows spaces/tabs after `<<<`).
+    while (i < end && (src[i] === ' ' || src[i] === '\t')) i++;
+
+    // Optional quote around the identifier.
+    let quote = '';
+    if (src[i] === "'" || src[i] === '"') {
+        quote = src[i];
+        i++;
+    }
+
+    if (i >= end || !isIdentStart(src[i])) return -1;
+    const idStart = i;
+    while (i < end && isIdent(src[i])) i++;
+    const id = src.slice(idStart, i);
+
+    if (quote) {
+        if (src[i] !== quote) return -1;
+        i++;
+    }
+
+    // After the identifier, the line must end immediately — PHP disallows trailing whitespace,
+    // but we tolerate `\r` so `\r\n` endings still work.
+    while (i < end && src[i] === '\r') i++;
+    if (src[i] !== '\n') return -1;
+    i++;
+
+    // Find a line that starts with optional indentation,
+    // then the identifier followed by a non-identifier character
+    // (PHP 7.3 flexible syntax).
+    while (i < end) {
+        let j = i;
+        while (j < end && (src[j] === ' ' || src[j] === '\t')) j++;
+        if (src.startsWith(id, j)) {
+            const k = j + id.length;
+            if (k >= end || !isIdent(src[k])) return k;
+        }
+        const nl = src.indexOf('\n', i);
+        if (nl === -1 || nl >= end) return end;
+        i = nl + 1;
+    }
+    return end;
+}

package/src/php-strings.ts

@@ -21,6 +21,7 @@
  */
 
 import type { Island } from './islands.ts';
+import { isIdent, isIdentStart, scanHeredoc, scanLineComment, scanQuoted } from './php-lexer.ts';
 
 /**
  * Inner byte range of a sortable string literal — the span *between* the quotes, in original-source offsets.
@@ -36,9 +37,6 @@ export interface PhpStringRange {
     end: number;
 }
 
-const isIdentStart = (c: string) => /[A-Za-z_€-￿]/.test(c);
-const isIdent = (c: string) => /[A-Za-z0-9_€-￿]/.test(c);
-
 interface Token {
     kind: 'string' | 'arrow' | 'dot' | 'other';
     /**
@@ -105,11 +103,11 @@ function tokenizeIsland(src: string, start: number, end: number): Token[] {
 
         // Line comments (`//`, `#`) — but `#[` opens a PHP 8 attribute, which is code.
         if (c === '/' && src[i + 1] === '/') {
-            i = skipLineComment(src, i + 2, end);
+            i = scanLineComment(src, i + 2, end);
             continue;
         }
         if (c === '#' && src[i + 1] !== '[') {
-            i = skipLineComment(src, i + 1, end);
+            i = scanLineComment(src, i + 1, end);
             continue;
         }
 
@@ -122,7 +120,7 @@ function tokenizeIsland(src: string, start: number, end: number): Token[] {
 
         // Heredoc / nowdoc — never harvested; skip the whole construct.
         if (c === '<' && src[i + 1] === '<' && src[i + 2] === '<') {
-            const here = skipHeredoc(src, i + 3, end);
+            const here = scanHeredoc(src, i + 3, end);
             if (here !== -1) {
                 i = here;
                 pushOther();
@@ -178,34 +176,6 @@ function tokenizeIsland(src: string, start: number, end: number): Token[] {
     return tokens;
 }
 
-/**
- * Scan a quoted string body; `i` is just past the open quote. Returns the offset of the closing quote (or `end`).
- */
-function scanQuoted(src: string, i: number, quote: string, end: number): number {
-    while (i < end) {
-        const c = src[i];
-        if (c === '\\') {
-            i += 2;
-            continue;
-        }
-        if (c === quote) return i;
-        i++;
-    }
-    return end;
-}
-
-/**
- * Skip a `//`/`#` line comment body, ending at a newline or `?>`. Returns the offset to resume scanning from.
- */
-function skipLineComment(src: string, i: number, end: number): number {
-    while (i < end) {
-        if (src[i] === '\n') return i + 1;
-        if (src[i] === '?' && src[i + 1] === '>') return i;
-        i++;
-    }
-    return end;
-}
-
 /**
  * True if a double-quoted body contains interpolation (an unescaped `$`) or any escape sequence.
  */
@@ -217,44 +187,3 @@ function hasInterpolationOrEscape(body: string): boolean {
     }
     return false;
 }
-
-/**
- * Skip a heredoc/nowdoc; `i` is just past `<<<`. Returns the offset past the closing identifier line,
- * or -1 if `<<<` isn't followed by a valid heredoc identifier. Mirrors the boundary rules of the island lexer.
- */
-function skipHeredoc(src: string, i: number, end: number): number {
-    while (i < end && (src[i] === ' ' || src[i] === '\t')) i++;
-
-    let quote = '';
-    if (src[i] === "'" || src[i] === '"') {
-        quote = src[i];
-        i++;
-    }
-
-    if (i >= end || !isIdentStart(src[i])) return -1;
-    const idStart = i;
-    while (i < end && isIdent(src[i])) i++;
-    const id = src.slice(idStart, i);
-
-    if (quote) {
-        if (src[i] !== quote) return -1;
-        i++;
-    }
-
-    while (i < end && src[i] === '\r') i++;
-    if (src[i] !== '\n') return -1;
-    i++;
-
-    while (i < end) {
-        let j = i;
-        while (j < end && (src[j] === ' ' || src[j] === '\t')) j++;
-        if (src.startsWith(id, j)) {
-            const k = j + id.length;
-            if (k >= end || !isIdent(src[k])) return k;
-        }
-        const nl = src.indexOf('\n', i);
-        if (nl === -1 || nl >= end) return end;
-        i = nl + 1;
-    }
-    return end;
-}

package/src/transform.ts

@@ -55,27 +55,33 @@ export function transform(src: string, sortFn: SortFn, opts: TransformOptions =
     const masked = maskIslands(src, islands);
     const attrs = findClassAttributes(masked, opts);
 
+    // Computed before the attribute pass: an edit inside a class-attribute island must be folded into that
+    // attribute's rewrite, or the enclosing rewrite would overwrite it and a second pass would be needed.
+    const phpEdits: Edit[] = [];
+    if (opts.sortPhpStrings) {
+        for (const { start, end } of findSortablePhpStrings(src, islands)) {
+            const original = src.slice(start, end);
+            const tokens = original.split(/\s+/).filter(Boolean);
+            if (tokens.length < 2) continue; // nothing to reorder; leave byte-identical
+            const text = sortFn(tokens).join(' ');
+            if (text !== original) phpEdits.push({ start, end, text });
+        }
+    }
+
     // Collect every edit as a {start, end, text} range, then apply them back-to-front so offsets stay valid.
-    // HTML class-attribute values live outside islands; PHP string values live inside them, so the two sets of
-    // ranges never overlap.
-    const edits: { start: number; end: number; text: string }[] = [];
+    const edits: Edit[] = [];
+    const absorbed = new Set<Edit>();
 
     for (const { valueStart, valueEnd } of attrs) {
         const original = src.slice(valueStart, valueEnd);
         const inner = islands.filter((isl) => isl.start >= valueStart && isl.end <= valueEnd);
-        const rewritten = rewriteValue(original, valueStart, inner, sortFn);
+        const innerEdits = phpEdits.filter((e) => e.start >= valueStart && e.end <= valueEnd);
+        const rewritten = rewriteValue(original, valueStart, inner, sortFn, innerEdits);
         if (rewritten !== original) edits.push({ start: valueStart, end: valueEnd, text: rewritten });
+        for (const e of innerEdits) absorbed.add(e);
     }
 
-    if (opts.sortPhpStrings) {
-        for (const { start, end } of findSortablePhpStrings(src, islands)) {
-            const original = src.slice(start, end);
-            const tokens = original.split(/\s+/).filter(Boolean);
-            if (tokens.length < 2) continue; // nothing to reorder; leave byte-identical
-            const rewritten = sortFn(tokens).join(' ');
-            if (rewritten !== original) edits.push({ start, end, text: rewritten });
-        }
-    }
+    for (const e of phpEdits) if (!absorbed.has(e)) edits.push(e);
 
     edits.sort((a, b) => b.start - a.start);
     let out = src;
@@ -83,20 +89,39 @@ export function transform(src: string, sortFn: SortFn, opts: TransformOptions =
     return out;
 }
 
+interface Edit {
+    start: number;
+    end: number;
+    text: string;
+}
+
 interface Part {
     type: 'static' | 'island';
     text: string;
 }
 
-function rewriteValue(value: string, base: number, islands: Island[], sortFn: SortFn): string {
-    // Build alternating static/island parts.
+/**
+ * Apply the edits that fall entirely within `[offset, offset + text.length)` to `text`.
+ * Edits arrive in document order and never overlap, so a back-to-front pass keeps offsets valid.
+ */
+function spliceEdits(text: string, offset: number, edits: Edit[]): string {
+    for (let k = edits.length - 1; k >= 0; k--) {
+        const e = edits[k];
+        if (e.start < offset || e.end > offset + text.length) continue;
+        text = text.slice(0, e.start - offset) + e.text + text.slice(e.end - offset);
+    }
+    return text;
+}
+
+function rewriteValue(value: string, base: number, islands: Island[], sortFn: SortFn, phpEdits: Edit[]): string {
+    // Build alternating static/island parts; island text carries any PHP-string edits it contains.
     const parts: Part[] = [];
     let pos = 0;
     for (const isl of islands) {
         const s = isl.start - base;
         const e = isl.end - base;
         parts.push({ type: 'static', text: value.slice(pos, s) });
-        parts.push({ type: 'island', text: value.slice(s, e) });
+        parts.push({ type: 'island', text: spliceEdits(value.slice(s, e), isl.start, phpEdits) });
         pos = e;
     }
     parts.push({ type: 'static', text: value.slice(pos) });