/vite-plugin-php

Vite's speed and tooling to preprocess PHP-files!

Primary LanguageTypeScriptMIT LicenseMIT

vite-plugin-php

npm GitHub Repo stars GitHub GitHub last commit Issues

Use Vite's speed and tooling to process PHP-files!

// vite.config.js
import { defineConfig } from 'vite';
import usePHP from 'vite-plugin-php';

export default defineConfig({
	plugins: [usePHP()],
});

Check out the starter repo for an easy and convenient start: Starter Repo

⚡ Latest changes

Version Feature
1.0.65 Fixed request body forwarding for all request methods
1.0.62 HTML transforms are now only applied to HTML contents during dev
1.0.60 Fixed inline module transpiling -> PHP code is being properly inserted into transpiled inline module chunks
1.0.55 Fixed pure PHP file processing
1.0.50 Using native Rollup pipeline to generate bundle -> proper error messages during build
1.0.40 Vite's "HTML Env Replacement" feature in transpiled PHP files
1.0.30 Proper PHP header forwarding during development
1.0.20 URL rewrite functionality to mimic mod_rewrite & friends
1.0.11 Improved Windows support

Write some PHP code in your index.php

<!-- index.php -->
<!DOCTYPE html>
<html lang="en">
	<head>
		<meta charset="UTF-8" />
		<meta http-equiv="X-UA-Compatible" content="IE=edge" />
		<meta name="viewport" content="width=device-width, initial-scale=1.0" />
	</head>
	<body>
		<?="Render some text with PHP!";?>

		<?php if(isset($_GET['dont_load'])) { ?>
			<script src="./src/some_script.js" type="module"></script>
		<?php } ?>
	</body>
</html>

The plugin will serve you the processed index.php as usual, including all imported and preprocessed files that are supported by Vite and other loaders.

Configuration

The configuration takes following properties:

type UsePHPConfig = {
	binary?: string;
	entry?: string | string[];
	rewriteUrl?: (requestUrl: URL) => URL | undefined;
	tempDir?: string;
	cleanup?: {
		dev?: boolean;
		build?: boolean;
	};
};

By default the plugin is trying to access the system php-binary and load the index.php file as the main entry point. However you have the possibility to use an other binary or even compile multiple entry-points:

usePHP({
	binary: '/opt/lampp/bin/php-8.1.10',
	entry: ['index.php', 'about.php', 'contact.php'],
});

Should you have multiple entry-points, you will be able to access each one according to this chart:

Entry file Accessible routes Build file
index.php / /index /index.php index.php
about.php /about /about.php about.php
about/details.php /about/details /about/details.php about/details.php
contact.php /contact /contact.php contact.php
shop/index.php /shop/ /shop/index.php shop/index.php
... ... ...

Since version 1.0.6 you can specify wildcard entry points:

usePHP({
	binary: '/opt/lampp/bin/php-8.1.10',
	entry: [
		'index.php',
		'about.php',
		'contact.php',
		'pages/**/*.php',
		'partials/*.php',
	],
});

These entries will also render according to the routing table above.

Rewrite urls

If you are using some sort of Apaches mod_rewrite magic or nginx rewrite rules you can simulate them with the newly added in rewriteUrl property. The rewriteUrl function has one parameter - the requested URL given as URL object - and return either a modified URL object or undefined:

usePHP({
	entry: ['index.php', 'partials/**/*.php'],
	rewriteUrl(requestUrl) {
		if (['.js', '.css'].some((s) => requestUrl.pathname.includes(s))) {
			return;
		}

		requestUrl.search = '_request_=' + requestUrl.pathname;
		requestUrl.pathname = 'index.php';

		return requestUrl;
	},
});

⚠️ Attention: If using the rewriteUrl property you will need to exclude (return undefined) assets like CSS, JavaScript, Images, etc.., that match your transpiled php file names, on your own!

Specific oddities

Inline modules

⚠️ PHP will work somehow unintuitive in inlined modules. E.g. you have a page with some variables:

<?php
$var = 'foo';
?>

<script type="module">
	console.log('<?=$var; ?>');
</script>

This will not work. $var will be undefined in the module since the script is being transpiled into a separate file and included separately. Same applies to other server variables like $_GET, $_POST and so on - they will not have the same value as the main PHP file.

Dynamically included asset processing

Vite won't be able to process PHP-computed styles, scripts or images:

<script src="./src/<?='dynamic_script_name';?>.js" type="module"></script>

Issues

If you encounter any other bugs or need some other features feel free to open an issue.

Support

Love open source? Enjoying my project?
Your support can keep the momentum going! Consider a donation to fuel the creation of more innovative open source software.

via Ko-Fi Buy me a coffee via PayPal
Ko-Fi Buy Me A Coffee PayPal