@jts-studios/vite-plugin-php

vite-plugin-php is an all-in-one solution for PHP projects with Vite.

How It Works

The plugin automatically manages your PHP workflow across three phases:

• Dev server: Automatically starts a PHP server, picks an available port, proxies requests to it, and injects the Vite HMR client.
• Hot update — triggers full-page reloads on .php changes and CSS hot-swaps on stylesheet changes
• Build — processes each PHP entry: minifies HTML, restores tokenised PHP blocks from .json fragments, outputs final .php files to dist/

Installation

npm install @jts-studios/vite-plugin-php

Usage

// vite.config.js
import { PHP } from "@jts-studios/vite-plugin-php"

export default {
    plugins: [
        PHP({
            entries: ["pages/index.php", "pages/about.php"],
            verbose: false,
            minifyHtml: true,
            hotReload: true,
        }),
    ],
}

Options

| Option | Type | Default | Description | |---|---|---|---| | entries | string[] | required | PHP entry files or folders to process | | verbose | boolean | false | Enable detailed build logging | | minifyHtml | boolean | true | Minify HTML output via html-minifier-terser | | hotReload | boolean | true | Enable hot reload for PHP and CSS changes | | autoStartPhp | boolean | true | Start the PHP built-in server automatically in dev | | phpHost | string | "127.0.0.1" | Host used by the auto-started PHP server | | phpPort | number | auto (starts at 3000) | Port for PHP server; if omitted, first free port is chosen | | phpCommand | string | "php" | PHP executable command used to start the server | | router | string \| null | null | Front controller to route dev requests through, e.g. "index.php". See below | | redirects | {from,to}[] | [] | Permanent redirects your web server does, replayed in dev. Needs router |

Routing in dev

Without router, the dev server only resolves paths that exist on disk. /pages/about.php works; /about does not — even though that is the URL production serves, and the one every link in your markup points at.

Set router to your front controller and dev behaves like the real thing:

PHP({
    entries: ["pages"],
    router: "index.php",
})

Two things change. PHP starts with a generated router script that defers to your front controller, so a URL resolves in dev exactly the way it resolves live — not through a second copy of your routing rules that has to be kept in step. And Vite switches to appType: "custom", so anything Vite does not recognise goes to PHP instead of being answered with index.html.

That covers POST as well, which the prefix proxy never forwarded: form handlers, JSON endpoints and webhook receivers all work.

redirects is for rules that live in your web server rather than your application — a renamed route still forwarding its old path, say. The front controller never sees those, so dev would 404 what production forwards:

redirects: [{ from: "^/old_name/?$", to: "/new-name" }]

from is a regex against the path, $1 in to works, and the query string is carried over.

Both are off by default, because turning them on changes what every unmatched path does — a surprise in a project that already works.