@dialekt/adapter-laravel 0.1.0

package/TESTING.md

@@ -0,0 +1,29 @@
+# @dialekt/adapter-laravel Testing Guide
+
+## Tested Areas Map
+
+| Export | Test File | Status |
+|--------|-----------|--------|
+| `laravel()` adapter | `src/adapter.test.ts` | ✅ |
+| `renderPhpArray` / `renderPhpFile` | `src/php-array-writer.test.ts` | ✅ |
+| `listLaravelLocales` / `listLaravelResources` | `src/resources.test.ts` | ✅ |
+| `findUnusedLaravelKeys` | `src/unused-keys.test.ts` | ✅ |
+
+## Known Coverage Gaps
+
+- Corrupted PHP file handling (PHP syntax error) — `readResource` returns `PhpExecutionError` but no explicit test for malformed PHP
+- JSON locale file with invalid JSON — no explicit test for corrupted `en.json`
+- `phpBinary` option in `LaravelAdapterOptions` — not tested with custom PHP binary path
+
+## Specialties & Watch-Outs
+
+- **PHP-dependent tests** use `it.skipIf(!hasPhpBinary())` to skip when `php` is not installed.
+- Tests create real temp directories via `node:fs` and clean up with `rmSync` in `afterEach` pattern.
+- The adapter's `findUnusedKeys!` requires `capabilities.unusedKeyDetection: true`.
+- `writeResource` for PHP domains produces actual `.php` files with `<?php return [...];` syntax.
+
+## Running Tests
+
+```bash
+pnpm --filter @dialekt/adapter-laravel test
+```

package/dist/index.d.mts

@@ -0,0 +1,11 @@
+import { TranslationAdapter } from "dialekt";
+
+//#region src/adapter.d.ts
+interface LaravelAdapterOptions {
+  readonly langDir: string;
+  readonly phpBinary?: string;
+  readonly scanPaths?: readonly string[];
+}
+declare function laravel(options: LaravelAdapterOptions): TranslationAdapter;
+//#endregion
+export { type LaravelAdapterOptions, laravel };

package/dist/index.mjs

@@ -0,0 +1,173 @@
+import { Effect } from "effect";
+import { Path } from "@effect/platform/Path";
+import { AdapterReadError, AdapterWriteError, NodePlatformLayer, flattenObject, readFileIfExists, readPhpArrayAsJson, unflattenObject, writeFileEnsuringDir } from "dialekt";
+import { FileSystem, Path as Path$1 } from "@effect/platform";
+//#region src/php-array-writer.ts
+function phpVarExport(value) {
+	return `'${value.replace(/\\/g, "\\\\").replace(/'/g, "\\'")}'`;
+}
+function renderPhpArray(value, indent = 0) {
+	const entries = Object.entries(value);
+	if (entries.length === 0) return "[]";
+	const pad = "    ".repeat(indent);
+	const innerPad = "    ".repeat(indent + 1);
+	const lines = ["["];
+	for (const [key, val] of entries) {
+		const renderedKey = /^\d+$/.test(key) ? key : phpVarExport(key);
+		const renderedValue = typeof val === "object" && val !== null && !Array.isArray(val) ? renderPhpArray(val, indent + 1) : typeof val === "string" ? phpVarExport(val) : String(val);
+		lines.push(`${innerPad}${renderedKey} => ${renderedValue},`);
+	}
+	lines.push(`${pad}]`);
+	return lines.join("\n");
+}
+function renderPhpFile(value) {
+	return `<?php\n\nreturn ${renderPhpArray(value, 0)};\n`;
+}
+//#endregion
+//#region src/resources.ts
+function listLaravelLocales(langDir) {
+	return Effect.gen(function* () {
+		const fs = yield* FileSystem.FileSystem;
+		const path = yield* Path$1.Path;
+		const entries = yield* fs.readDirectory(langDir).pipe(Effect.orElseSucceed(() => []));
+		const locales = [];
+		for (const entry of entries) {
+			const fullPath = path.join(langDir, entry);
+			const stat = yield* fs.stat(fullPath).pipe(Effect.option);
+			if (stat._tag === "Some" && stat.value.type === "Directory" && entry !== "vendor" && entry !== "lang") locales.push(entry);
+		}
+		return locales;
+	}).pipe(Effect.mapError((cause) => new AdapterReadError({
+		adapter: "laravel",
+		locale: "",
+		resource: "",
+		cause
+	})));
+}
+function listLaravelResources(langDir, locale) {
+	return Effect.gen(function* () {
+		const fs = yield* FileSystem.FileSystem;
+		const path = yield* Path$1.Path;
+		const localeDir = path.join(langDir, locale);
+		const refs = [];
+		const entries = yield* fs.readDirectory(localeDir).pipe(Effect.orElseSucceed(() => []));
+		for (const entry of entries) if (entry.endsWith(".php")) {
+			const domain = entry.replace(/\.php$/, "");
+			refs.push({
+				key: domain,
+				label: domain
+			});
+		}
+		const jsonPath = path.join(langDir, `${locale}.json`);
+		if (yield* fs.exists(jsonPath).pipe(Effect.orElseSucceed(() => false))) refs.push({
+			key: "json",
+			label: `${locale}.json`
+		});
+		return refs;
+	}).pipe(Effect.mapError((cause) => new AdapterReadError({
+		adapter: "laravel",
+		locale,
+		resource: "",
+		cause
+	})));
+}
+//#endregion
+//#region src/unused-keys.ts
+function findUnusedLaravelKeys(scanPaths, domain, keys) {
+	return Effect.gen(function* () {
+		const fs = yield* FileSystem.FileSystem;
+		const path = yield* Path$1.Path;
+		const referenced = /* @__PURE__ */ new Set();
+		for (const scanPath of scanPaths) {
+			if (!(yield* fs.exists(scanPath).pipe(Effect.orElseSucceed(() => false)))) continue;
+			const entries = yield* fs.readDirectory(scanPath, { recursive: true }).pipe(Effect.orElseSucceed(() => []));
+			for (const relativePath of entries) {
+				if (!relativePath.endsWith(".php") && !relativePath.endsWith(".blade.php")) continue;
+				const filePath = path.join(scanPath, relativePath);
+				const content = yield* fs.readFileString(filePath).pipe(Effect.orElseSucceed(() => ""));
+				const quotedStrings = [];
+				for (const pattern of [/'((?:[^'\\]|\\.)*)'/g, /"((?:[^"\\]|\\.)*)"/g]) {
+					let m;
+					while ((m = pattern.exec(content)) !== null) if (m[1] !== void 0) quotedStrings.push(m[1]);
+				}
+				for (const str of quotedStrings) for (const key of keys) if (str === `${domain}.${key}`) referenced.add(key);
+			}
+		}
+		return keys.filter((key) => !referenced.has(key));
+	}).pipe(Effect.mapError((cause) => new AdapterReadError({
+		adapter: "laravel",
+		locale: "",
+		resource: domain,
+		cause
+	})));
+}
+//#endregion
+//#region src/adapter.ts
+function laravel(options) {
+	const { langDir, scanPaths = [] } = options;
+	return {
+		name: "laravel",
+		capabilities: {
+			canCreateResource: true,
+			unusedKeyDetection: true
+		},
+		listLocales: () => listLaravelLocales(langDir).pipe(Effect.provide(NodePlatformLayer)),
+		listResources: (locale) => listLaravelResources(langDir, locale).pipe(Effect.provide(NodePlatformLayer)),
+		readResource: (locale, resource) => Effect.gen(function* () {
+			const path = yield* Path;
+			if (resource.key === "json") {
+				const content = yield* readFileIfExists(path.join(langDir, `${locale}.json`)).pipe(Effect.mapError((cause) => new AdapterReadError({
+					adapter: "laravel",
+					locale,
+					resource: resource.key,
+					cause
+				})));
+				if (content === null) return {};
+				return yield* Effect.try({
+					try: () => JSON.parse(content),
+					catch: (cause) => new AdapterReadError({
+						adapter: "laravel",
+						locale,
+						resource: resource.key,
+						cause
+					})
+				});
+			}
+			return flattenObject(yield* readPhpArrayAsJson(path.join(langDir, locale, `${resource.key}.php`)).pipe(Effect.catchTag("PhpExecutionError", () => Effect.succeed({})), Effect.mapError((cause) => new AdapterReadError({
+				adapter: "laravel",
+				locale,
+				resource: resource.key,
+				cause
+			}))));
+		}).pipe(Effect.provide([NodePlatformLayer])),
+		writeResource: (locale, resource, entries) => Effect.gen(function* () {
+			const path = yield* Path;
+			if (resource.key === "json") {
+				yield* writeFileEnsuringDir(path.join(langDir, `${locale}.json`), JSON.stringify(entries, null, 2)).pipe(Effect.mapError((cause) => new AdapterWriteError({
+					adapter: "laravel",
+					locale,
+					resource: resource.key,
+					cause
+				})));
+				return;
+			}
+			yield* writeFileEnsuringDir(path.join(langDir, locale, `${resource.key}.php`), renderPhpFile(unflattenObject(entries))).pipe(Effect.mapError((cause) => new AdapterWriteError({
+				adapter: "laravel",
+				locale,
+				resource: resource.key,
+				cause
+			})));
+		}).pipe(Effect.provide([NodePlatformLayer])),
+		findUnusedKeys: (locale, resource) => Effect.gen(function* () {
+			const path = yield* Path;
+			const adapterScanPaths = scanPaths.length > 0 ? scanPaths : [path.resolve(langDir, "..")];
+			const keys = yield* Effect.gen(function* () {
+				const map = yield* laravel(options).readResource(locale, resource);
+				return Object.keys(map);
+			});
+			return yield* findUnusedLaravelKeys(adapterScanPaths, resource.key, keys);
+		}).pipe(Effect.provide([NodePlatformLayer]))
+	};
+}
+//#endregion
+export { laravel };

package/package.json

@@ -0,0 +1,27 @@
+{
+  "name": "@dialekt/adapter-laravel",
+  "version": "0.1.0",
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.mts",
+      "import": "./dist/index.mjs"
+    }
+  },
+  "dependencies": {
+    "@effect/platform": "^0.96.0",
+    "effect": "^3.21.0",
+    "dialekt": "0.1.0"
+  },
+  "devDependencies": {
+    "@types/node": "^26.0.1",
+    "tsdown": "^0.22.3",
+    "typescript": "^5.8.0",
+    "vitest": "^4.0.0"
+  },
+  "scripts": {
+    "build": "tsdown",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run"
+  }
+}

package/src/adapter.test.ts

@@ -0,0 +1,179 @@
+import { describe, expect, it } from 'vitest';
+import { Effect, Either } from 'effect';
+import { NodePlatformLayer } from 'dialekt';
+import { laravel } from './adapter.js';
+import { mkdirSync, writeFileSync, rmSync } from 'node:fs';
+import { join } from 'node:path';
+import { tmpdir } from 'node:os';
+import { execSync } from 'node:child_process';
+
+function hasPhpBinary(): boolean {
+  try {
+    execSync('php -v', { stdio: 'ignore' });
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+describe('laravel adapter', () => {
+  const testDir = join(tmpdir(), `laravel-adapter-test-${Date.now()}`);
+
+  it.skipIf(!hasPhpBinary())('reads a PHP domain resource', async () => {
+    mkdirSync(join(testDir, 'en'), { recursive: true });
+    writeFileSync(
+      join(testDir, 'en', 'validation.php'),
+      "<?php return ['email' => 'Email address'];",
+    );
+
+    const adapter = laravel({ langDir: testDir, scanPaths: [testDir] });
+    const program = adapter.readResource('en', { key: 'validation', label: 'validation' }).pipe(
+      Effect.provide(NodePlatformLayer),
+    );
+    const result = await Effect.runPromise(program);
+    expect(result).toEqual({ email: 'Email address' });
+
+    rmSync(testDir, { recursive: true, force: true });
+  });
+
+  it.skipIf(!hasPhpBinary())('returns {} for a missing resource', async () => {
+    mkdirSync(join(testDir, 'en'), { recursive: true });
+
+    const adapter = laravel({ langDir: testDir, scanPaths: [testDir] });
+    const program = adapter.readResource('en', { key: 'missing', label: 'missing' }).pipe(
+      Effect.provide(NodePlatformLayer),
+    );
+    const result = await Effect.runPromise(program);
+    expect(result).toEqual({});
+
+    rmSync(testDir, { recursive: true, force: true });
+  });
+
+  it.skipIf(!hasPhpBinary())('round-trips write and read', async () => {
+    mkdirSync(join(testDir, 'de'), { recursive: true });
+
+    const adapter = laravel({ langDir: testDir, scanPaths: [testDir] });
+    const writeProgram = adapter
+      .writeResource('de', { key: 'auth', label: 'auth' }, { login: 'Anmelden' })
+      .pipe(Effect.provide(NodePlatformLayer));
+    await Effect.runPromise(writeProgram);
+
+    const readProgram = adapter.readResource('de', { key: 'auth', label: 'auth' }).pipe(
+      Effect.provide(NodePlatformLayer),
+    );
+    const result = await Effect.runPromise(readProgram);
+    expect(result).toEqual({ login: 'Anmelden' });
+
+    rmSync(testDir, { recursive: true, force: true });
+  });
+
+  it('reads a JSON locale resource', async () => {
+    mkdirSync(testDir, { recursive: true });
+    writeFileSync(join(testDir, 'en.json'), JSON.stringify({ greeting: 'Hello' }));
+
+    const adapter = laravel({ langDir: testDir, scanPaths: [testDir] });
+    const program = adapter.readResource('en', { key: 'json', label: 'en.json' }).pipe(
+      Effect.provide(NodePlatformLayer),
+    );
+    const result = await Effect.runPromise(program);
+    expect(result).toEqual({ greeting: 'Hello' });
+
+    rmSync(testDir, { recursive: true, force: true });
+  });
+
+  it('lists locales and resources', async () => {
+    mkdirSync(join(testDir, 'en'), { recursive: true });
+    mkdirSync(join(testDir, 'de'), { recursive: true });
+    writeFileSync(join(testDir, 'en', 'validation.php'), '<?php return [];');
+
+    const adapter = laravel({ langDir: testDir, scanPaths: [testDir] });
+    const locales = await Effect.runPromise(adapter.listLocales().pipe(Effect.provide(NodePlatformLayer)));
+    expect(locales).toContain('en');
+    expect(locales).toContain('de');
+
+    const resources = await Effect.runPromise(
+      adapter.listResources('en').pipe(Effect.provide(NodePlatformLayer)),
+    );
+    expect(resources.map((r) => r.key)).toContain('validation');
+
+    rmSync(testDir, { recursive: true, force: true });
+  });
+
+  it('finds unused keys', async () => {
+    mkdirSync(join(testDir, 'en'), { recursive: true });
+    writeFileSync(join(testDir, 'en', 'validation.php'), "<?php return ['email' => 'Email'];");
+    mkdirSync(join(testDir, 'views'), { recursive: true });
+    writeFileSync(join(testDir, 'views', 'page.blade.php'), "__('validation.email')");
+
+    const adapter = laravel({ langDir: testDir, scanPaths: [join(testDir, 'views')] });
+    const program = adapter
+      .findUnusedKeys!('en', { key: 'validation', label: 'validation' })
+      .pipe(Effect.provide(NodePlatformLayer));
+    const result = await Effect.runPromise(program);
+    expect(result).toEqual([]);
+
+    rmSync(testDir, { recursive: true, force: true });
+  });
+
+  it.skipIf(!hasPhpBinary())('reads nested PHP arrays', async () => {
+    mkdirSync(join(testDir, 'en'), { recursive: true });
+    writeFileSync(
+      join(testDir, 'en', 'nested.php'),
+      "<?php return ['validation' => ['email' => 'Email', 'required' => 'Required']];",
+    );
+
+    const adapter = laravel({ langDir: testDir, scanPaths: [testDir] });
+    const program = adapter.readResource('en', { key: 'nested', label: 'nested' }).pipe(
+      Effect.provide(NodePlatformLayer),
+    );
+    const result = await Effect.runPromise(program);
+    expect(result).toEqual({
+      'validation.email': 'Email',
+      'validation.required': 'Required',
+    });
+
+    rmSync(testDir, { recursive: true, force: true });
+  });
+
+  it('returns empty for missing JSON locale file', async () => {
+    mkdirSync(testDir, { recursive: true });
+
+    const adapter = laravel({ langDir: testDir, scanPaths: [testDir] });
+    const program = adapter.readResource('en', { key: 'json', label: 'en.json' }).pipe(
+      Effect.provide(NodePlatformLayer),
+    );
+    const result = await Effect.runPromise(program);
+    expect(result).toEqual({});
+
+    rmSync(testDir, { recursive: true, force: true });
+  });
+
+  it('handles capabilities flags', () => {
+    const adapter = laravel({ langDir: testDir });
+    expect(adapter.capabilities.canCreateResource).toBe(true);
+    expect(adapter.capabilities.unusedKeyDetection).toBe(true);
+  });
+
+  it('reports adapter name', () => {
+    const adapter = laravel({ langDir: testDir });
+    expect(adapter.name).toBe('laravel');
+  });
+
+  it.skipIf(!hasPhpBinary())('writes JSON locale files', async () => {
+    mkdirSync(testDir, { recursive: true });
+
+    const adapter = laravel({ langDir: testDir, scanPaths: [testDir] });
+    const writeProgram = adapter
+      .writeResource('en', { key: 'json', label: 'en.json' }, { greeting: 'Hello' })
+      .pipe(Effect.provide(NodePlatformLayer));
+    await Effect.runPromise(writeProgram);
+
+    const readProgram = adapter.readResource('en', { key: 'json', label: 'en.json' }).pipe(
+      Effect.provide(NodePlatformLayer),
+    );
+    const result = await Effect.runPromise(readProgram);
+    expect(result).toEqual({ greeting: 'Hello' });
+
+    rmSync(testDir, { recursive: true, force: true });
+  });
+});

package/src/adapter.ts

@@ -0,0 +1,140 @@
+import { Effect } from 'effect';
+import { Path } from '@effect/platform/Path';
+import type {
+  ResourceRef,
+  TranslationAdapter,
+  AdapterReadError,
+  AdapterWriteError,
+} from 'dialekt';
+import {
+  AdapterReadError as AdapterReadErrorClass,
+  AdapterWriteError as AdapterWriteErrorClass,
+  NodePlatformLayer,
+  flattenObject,
+  unflattenObject,
+  readPhpArrayAsJson,
+  readFileIfExists,
+  writeFileEnsuringDir,
+} from 'dialekt';
+import { renderPhpFile } from './php-array-writer.js';
+import { listLaravelLocales, listLaravelResources } from './resources.js';
+import { findUnusedLaravelKeys } from './unused-keys.js';
+
+export interface LaravelAdapterOptions {
+  readonly langDir: string;
+  readonly phpBinary?: string;
+  readonly scanPaths?: readonly string[];
+}
+
+export function laravel(options: LaravelAdapterOptions): TranslationAdapter {
+  const { langDir, scanPaths = [] } = options;
+
+  return {
+    name: 'laravel',
+    capabilities: {
+      canCreateResource: true,
+      unusedKeyDetection: true,
+    },
+
+    listLocales: () => listLaravelLocales(langDir).pipe(Effect.provide(NodePlatformLayer)),
+
+    listResources: (locale) => listLaravelResources(langDir, locale).pipe(Effect.provide(NodePlatformLayer)),
+
+    readResource: (locale, resource) =>
+      Effect.gen(function* () {
+        const path = yield* Path;
+
+        if (resource.key === 'json') {
+          // JSON locale file
+          const filePath = path.join(langDir, `${locale}.json`);
+          const content = yield* readFileIfExists(filePath).pipe(
+            Effect.mapError(
+              (cause) =>
+                new AdapterReadErrorClass({
+                  adapter: 'laravel',
+                  locale,
+                  resource: resource.key,
+                  cause,
+                }) as AdapterReadError,
+            ),
+          );
+          if (content === null) return {};
+          return yield* Effect.try({
+            try: () => JSON.parse(content) as Record<string, string>,
+            catch: (cause) =>
+              new AdapterReadErrorClass({
+                adapter: 'laravel',
+                locale,
+                resource: resource.key,
+                cause,
+              }),
+          });
+        }
+
+        // PHP domain file
+        const filePath = path.join(langDir, locale, `${resource.key}.php`);
+        const result = yield* readPhpArrayAsJson(filePath).pipe(
+          Effect.catchTag('PhpExecutionError', () => Effect.succeed({})),
+          Effect.mapError(
+            (cause) =>
+              new AdapterReadErrorClass({
+                adapter: 'laravel',
+                locale,
+                resource: resource.key,
+                cause,
+              }) as AdapterReadError,
+          ),
+        );
+        return flattenObject(result);
+      }).pipe(Effect.provide([NodePlatformLayer])) as Effect.Effect<Record<string, string>, AdapterReadError, never>,
+
+    writeResource: (locale, resource, entries) =>
+      Effect.gen(function* () {
+        const path = yield* Path;
+
+        if (resource.key === 'json') {
+          // JSON locale file
+          const filePath = path.join(langDir, `${locale}.json`);
+          yield* writeFileEnsuringDir(filePath, JSON.stringify(entries, null, 2)).pipe(
+            Effect.mapError(
+              (cause) =>
+                new AdapterWriteErrorClass({
+                  adapter: 'laravel',
+                  locale,
+                  resource: resource.key,
+                  cause,
+                }) as AdapterWriteError,
+            ),
+          );
+          return;
+        }
+
+        // PHP domain file
+        const filePath = path.join(langDir, locale, `${resource.key}.php`);
+        const nested = unflattenObject(entries);
+        yield* writeFileEnsuringDir(filePath, renderPhpFile(nested)).pipe(
+          Effect.mapError(
+            (cause) =>
+              new AdapterWriteErrorClass({
+                adapter: 'laravel',
+                locale,
+                resource: resource.key,
+                cause,
+              }) as AdapterWriteError,
+          ),
+        );
+      }).pipe(Effect.provide([NodePlatformLayer])) as Effect.Effect<void, AdapterWriteError, never>,
+
+    findUnusedKeys: (locale, resource) =>
+      Effect.gen(function* () {
+        const path = yield* Path;
+        const adapterScanPaths =
+          scanPaths.length > 0 ? scanPaths : [path.resolve(langDir, '..')];
+        const keys = yield* Effect.gen(function* () {
+          const map = yield* laravel(options).readResource(locale, resource);
+          return Object.keys(map);
+        });
+        return yield* findUnusedLaravelKeys(adapterScanPaths, resource.key, keys);
+      }).pipe(Effect.provide([NodePlatformLayer])) as Effect.Effect<readonly string[], AdapterReadError, never>,
+  };
+}

package/src/index.ts

@@ -0,0 +1,2 @@
+export { laravel } from './adapter.js';
+export type { LaravelAdapterOptions } from './adapter.js';

package/src/php-array-writer.test.ts

@@ -0,0 +1,58 @@
+import { describe, expect, it } from 'vitest';
+import { renderPhpArray, renderPhpFile } from './php-array-writer.js';
+
+describe('renderPhpArray', () => {
+  it('renders an empty array', () => {
+    expect(renderPhpArray({})).toBe('[]');
+  });
+
+  it('renders flat key-value pairs', () => {
+    const result = renderPhpArray({ hello: 'Hello' });
+    expect(result).toContain("'hello' => 'Hello'");
+  });
+
+  it('renders nested objects', () => {
+    const result = renderPhpArray({ validation: { email: 'Email address' } });
+    expect(result).toContain("'validation' => [");
+    expect(result).toContain("    'email' => 'Email address',");
+  });
+
+  it('escapes single quotes', () => {
+    const result = renderPhpArray({ key: "it's" });
+    expect(result).toContain("'it\\'s'");
+  });
+
+  it('escapes backslashes', () => {
+    const result = renderPhpArray({ key: 'a\\b' });
+    expect(result).toContain("'a\\\\b'");
+  });
+
+  it('preserves unicode literally', () => {
+    const result = renderPhpArray({ key: 'Héllo 🌍 — 日本語' });
+    expect(result).toContain('Héllo 🌍 — 日本語');
+  });
+
+  it('preserves empty string', () => {
+    const result = renderPhpArray({ key: '' });
+    expect(result).toContain("'key' => '',");
+  });
+
+  it('preserves double quotes without escaping', () => {
+    const result = renderPhpArray({ key: 'He said "hi"' });
+    expect(result).toContain('"hi"');
+  });
+
+  it('renders numeric keys without quotes', () => {
+    const result = renderPhpArray({ 0: 'first', 1: 'second' });
+    expect(result).toContain("0 => 'first'");
+    expect(result).toContain("1 => 'second'");
+  });
+});
+
+describe('renderPhpFile', () => {
+  it('wraps in PHP tags', () => {
+    const result = renderPhpFile({ hello: 'World' });
+    expect(result.startsWith('<?php\n\nreturn ')).toBe(true);
+    expect(result.endsWith(';\n')).toBe(true);
+  });
+});

package/src/php-array-writer.ts

@@ -0,0 +1,38 @@
+function phpVarExport(value: string): string {
+  // Wrap in single quotes; escape backslashes and single quotes only.
+  // This matches PHP var_export() semantics for plain strings.
+  const escaped = value.replace(/\\/g, '\\\\').replace(/'/g, "\\'");
+  return `'${escaped}'`;
+}
+
+export function renderPhpArray(
+  value: Record<string, unknown>,
+  indent = 0,
+): string {
+  const entries = Object.entries(value);
+  if (entries.length === 0) {
+    return '[]';
+  }
+
+  const pad = '    '.repeat(indent);
+  const innerPad = '    '.repeat(indent + 1);
+  const lines: string[] = ['['];
+
+  for (const [key, val] of entries) {
+    const renderedKey = /^\d+$/.test(key) ? key : phpVarExport(key);
+    const renderedValue =
+      typeof val === 'object' && val !== null && !Array.isArray(val)
+        ? renderPhpArray(val as Record<string, unknown>, indent + 1)
+        : typeof val === 'string'
+          ? phpVarExport(val)
+          : String(val);
+    lines.push(`${innerPad}${renderedKey} => ${renderedValue},`);
+  }
+
+  lines.push(`${pad}]`);
+  return lines.join('\n');
+}
+
+export function renderPhpFile(value: Record<string, unknown>): string {
+  return `<?php\n\nreturn ${renderPhpArray(value, 0)};\n`;
+}