@runtimestudio/tailwind-sort-php 0.2.0 → 0.3.0

package/README.md

@@ -18,19 +18,28 @@ 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
 
-- **Bun**, or **Node ≥ 22.18** (native TypeScript type-stripping) — both run the CLI and the programmatic API.
+- **Node ≥ 22.18**, or **Bun** — both run the CLI and the programmatic API.
 - `prettier` ≥ 3 and `prettier-plugin-tailwindcss` ≥ 0.8 (peer dependencies).
 
 ## Install
 
 ```sh
-# Bun
-bun add -D @runtimestudio/tailwind-sort-php prettier prettier-plugin-tailwindcss
-
 # npm
 npm install -D @runtimestudio/tailwind-sort-php prettier prettier-plugin-tailwindcss
+
+# Bun
+bun add -D @runtimestudio/tailwind-sort-php prettier prettier-plugin-tailwindcss
 ```
 
 pnpm and yarn work the same (`pnpm add -D …` / `yarn add -D …`).
@@ -38,12 +47,14 @@ pnpm and yarn work the same (`pnpm add -D …` / `yarn add -D …`).
 ## Setup
 
 Point Prettier at your Tailwind v4 entry stylesheet so both `prettier-plugin-tailwindcss` and this tool share one
-vocabulary. In `prettier.config.mjs`:
+vocabulary. Any config format Prettier supports works (`.prettierrc`, `prettier.config.js`, a `package.json`
+`"prettier"` key, …) — the tool reads the resolved config, exactly like the plugin does. For example, in
+`prettier.config.mjs`:
 
 ```js
 export default {
-  plugins: ['prettier-plugin-tailwindcss'],
-  tailwindStylesheet: './resources/css/main.css',
+    plugins: ['prettier-plugin-tailwindcss'],
+    tailwindStylesheet: './resources/css/main.css',
 };
 ```
 
@@ -52,39 +63,43 @@ this in place, the CLI needs no flags.
 
 ## Usage
 
-Run with `bunx` (Bun) or `npx` (Node ≥ 22.18):
+Run with `npx` (Node ≥ 22.18) or `bunx` (Bun):
 
 ```sh
 # sort every .php file under the cwd (stylesheet read from your Prettier config)
-bunx tailwind-sort-php
+npx tailwind-sort-php
 
 # specific globs
-bunx tailwind-sort-php "template-parts/**/*.php" "*.php"
+npx tailwind-sort-php "template-parts/**/*.php" "*.php"
 
 # CI / pre-commit — write nothing, exit 1 if anything is unsorted
-bunx tailwind-sort-php --check
+npx tailwind-sort-php --check
 
 # explicit stylesheet (overrides the Prettier config)
-bunx tailwind-sort-php --stylesheet ./resources/css/main.css
+npx tailwind-sort-php --stylesheet ./resources/css/main.css
 
 # one-time: install the pre-commit hook (see "Pre-commit gate" below)
-bunx tailwind-sort-php init
+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.                                                                                                                                                       |
 
 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)
 
@@ -105,14 +120,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}"
+            }
+        ]
+    }
 }
 ```
 
@@ -144,11 +159,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">
@@ -171,8 +278,10 @@ 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)
+- `<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
 
@@ -188,6 +297,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.
@@ -195,17 +307,19 @@ const out = transform(source, sortFn);
   classes).
 - Whitespace inside multi-line class attributes is normalized to single spaces (matches Prettier behavior).
 
+</details>
+
 ## Development
 
 ```sh
-bun test                       # or: node --test "test/*.test.ts"
-bun run build                  # compile src → dist (tsc); the published artifact
+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.
+74 tests: 59 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.
 
 ## License
 

package/dist/cli.d.ts

@@ -9,10 +9,11 @@
  * 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` (`"**" + "/*.php"`) when no globs are given.
+ * 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`.
  */
 export {};

package/dist/cli.js

@@ -9,10 +9,11 @@
  * 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` (`"**" + "/*.php"`) when no globs are given.
+ * 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`.
  */
 import { readFile, writeFile } from 'node:fs/promises';
@@ -30,6 +31,7 @@ function parseArgs(argv) {
     const cli = {
         globs: [],
         attrs: ['class', 'className'],
+        phpSources: [],
         check: false,
         shortTags: true,
     };
@@ -43,6 +45,8 @@ function parseArgs(argv) {
             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}`);
             process.exit(2);
@@ -60,7 +64,6 @@ function parseArgs(argv) {
  * @param globs Glob patterns relative to `cwd`.
  */
 async function* scanFiles(globs) {
-    // Use `Bun.Glob` when available, fall back to `node:fs` glob (Node 22+).
     if (typeof globalThis.Bun !== 'undefined') {
         const { Glob } = await import('bun');
         for (const pattern of globs) {
@@ -84,11 +87,10 @@ async function* scanFiles(globs) {
  */
 const ignored = (file) => IGNORE.some((d) => file.includes(`${d}/`) || file.startsWith(d));
 /**
- * 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 {
@@ -107,6 +109,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 {
@@ -136,24 +141,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.d.ts

@@ -8,7 +8,7 @@
  *   - islands inside a quoted attribute value read as opaque atoms
  *
  * Skips HTML comments, doctype/CDATA, and the raw-text content of `script`/`style`/`textarea`/`title` elements —
- * their `script`/`style` content may contain strings like `class="..."` that must not be touched.
+ * their content may contain strings like `class="..."` that must not be touched.
  *
  * @see islands.ts - first pass; produces the islands consumed here.
  */

package/dist/html.js

@@ -8,7 +8,7 @@
  *   - islands inside a quoted attribute value read as opaque atoms
  *
  * Skips HTML comments, doctype/CDATA, and the raw-text content of `script`/`style`/`textarea`/`title` elements —
- * their `script`/`style` content may contain strings like `class="..."` that must not be touched.
+ * their content may contain strings like `class="..."` that must not be touched.
  *
  * @see islands.ts - first pass; produces the islands consumed here.
  */

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

@@ -13,9 +13,8 @@ const HOOK_PATH = `${HOOKS_DIR}/pre-commit`;
  * Check-and-fail hook (default): names the unsorted files and blocks the commit; never writes.
  */
 const HOOK_CHECK = `#!/bin/sh
-# Block commits with unsorted Tailwind classes in staged PHP files.
-# Installed by \`tailwind-sort-php init\`. Note: checks working-tree file
-# contents, so partial staging (git add -p) can mis-report; see README.
+# Block commits with unsorted Tailwind classes in staged PHP files. Installed by \`tailwind-sort-php init\`.
+# Note: checks working-tree file contents, so partial staging (\`git add -p\`) can mis-report; see README.
 sorter=./node_modules/.bin/tailwind-sort-php
 [ -x "$sorter" ] || exit 0
 git diff --cached --name-only --diff-filter=ACMR -- '*.php' | grep -q . || exit 0
@@ -31,10 +30,9 @@ exit 1
  * Auto-fix hook (--fix): sorts the staged files in place, then blocks the commit for review.
  */
 const HOOK_FIX = `#!/bin/sh
-# Sort Tailwind classes in staged PHP files, then abort the commit so the
-# changes can be reviewed and re-staged. Rewrites working-tree files.
-# Installed by \`tailwind-sort-php init --fix\`. Note: with partial staging
-# (git add -p), re-staging can pull in unrelated unstaged hunks; see README.
+# Sort Tailwind classes in staged PHP files, then abort the commit so the changes can be reviewed and re-staged.
+# Rewrites working-tree files. Installed by \`tailwind-sort-php init --fix\`.
+# Note: with partial staging (\`git add -p\`), re-staging can pull in unrelated unstaged hunks; see README.
 sorter=./node_modules/.bin/tailwind-sort-php
 [ -x "$sorter" ] || exit 0
 git diff --cached --name-only --diff-filter=ACMR -- '*.php' | grep -q . || exit 0
@@ -134,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;
@@ -150,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)

package/dist/islands.js

@@ -73,7 +73,7 @@ function scanPhpBody(src, i) {
             continue;
         }
         // Double-quoted string.
-        // Limitation: nested double quotes in complex `{$a["k"]}` interpolation can desync the lexer (documented).
+        // Limitation: nested double quotes in complex `{$a["k"]}` interpolation can desync the lexer; see README.
         if (c === '"') {
             i = scanQuoted(src, i + 1, '"');
             continue;

package/dist/php-strings.d.ts

@@ -0,0 +1,47 @@
+/**
+ * PHP string-literal harvester — the optional third pass.
+ *
+ * Given the source and the PHP islands already found by `findIslands()`, this locates the byte ranges of every
+ * string literal *value* inside PHP code that is eligible for class sorting, applying these structural rules:
+ *
+ *   - Only the *value* of a `key => value` pair is eligible; array keys are never sorted.
+ *   - Bare list-style elements (`['a', 'b']`) and scalar assignments (`const X = '...'`) are values.
+ *   - Strings that are part of a concatenation expression (`'btn-' . $v`) are skipped — a literal joined to dynamic
+ *     code may be a partial class fragment, and reordering it would corrupt the rendered string.
+ *   - Double-quoted strings containing interpolation (`"p-4 {$x}"`) are skipped, mirroring the HTML side's
+ *     conservatism around dynamic content.
+ *   - Strings whose body contains a backslash escape are skipped, so escape sequences can never be mangled.
+ *   - Heredoc/nowdoc and backtick (shell-exec) strings are never harvested.
+ *
+ * This pass is opt-in per file (the caller decides which files are class-string holders); it does NOT judge whether
+ * a given string "looks like" Tailwind classes — within a matched file, every eligible value is sorted.
+ *
+ * @see islands.ts   - first pass; produces the islands consumed here.
+ * @see transform.ts - splices the sorted strings back via the shared byte-replacement path.
+ */
+import type { Island } from './islands.ts';
+/**
+ * Inner byte range of a sortable string literal — the span *between* the quotes, in original-source offsets.
+ */
+export interface PhpStringRange {
+    /**
+     * Offset of the first character inside the quotes.
+     */
+    start: number;
+    /**
+     * Offset just past the last character inside the quotes (exclusive).
+     */
+    end: number;
+}
+/**
+ * Find every sortable string-literal value within the given PHP islands.
+ *
+ * @param src     Original template source.
+ * @param islands Island ranges from `findIslands()`.
+ * @returns Inner ranges of eligible string values, in document order.
+ *
+ * @example
+ * const islands = findIslands(`<?php $x = 'z a'; ?>`);
+ * findSortablePhpStrings(`<?php $x = 'z a'; ?>`, islands); // [{ start: 11, end: 14 }]
+ */
+export declare function findSortablePhpStrings(src: string, islands: Island[]): PhpStringRange[];