vite-plugin-php 1.0.71 → 2.0.0

package/README.md

@@ -1,9 +1,21 @@
-# vite-plugin-php
-
-[![npm](https://img.shields.io/npm/dt/vite-plugin-php?style=for-the-badge)](https://www.npmjs.com/package/vite-plugin-php) [![GitHub Repo stars](https://img.shields.io/github/stars/donnikitos/vite-plugin-php?label=GitHub%20Stars&style=for-the-badge)](https://github.com/donnikitos/vite-plugin-php) [![GitHub](https://img.shields.io/github/license/donnikitos/vite-plugin-php?color=blue&style=for-the-badge)](https://github.com/donnikitos/vite-plugin-php/blob/master/LICENSE)
-![GitHub last commit](https://img.shields.io/github/last-commit/donnikitos/vite-plugin-php?style=for-the-badge) [![Issues](https://img.shields.io/github/issues/donnikitos/vite-plugin-php?style=for-the-badge)](https://github.com/donnikitos/vite-plugin-php/issues)
-
-Use Vite's speed and tooling to process PHP-files!
+<p align="center" style="text-align: center;">
+	<img
+	src="https://vite-php.nititech.de/assets/vite-php.logo.svg"
+	alt="vite-plugin-php logo"
+	style="width: 250px; max-width: 100%;" />
+</p>
+
+<div style="display: grid; grid-template-columns: max-content max-content; column-gap: 10px;">
+	<a href="https://github.com/donnikitos/vite-plugin-php/blob/master/LICENSE" target="_blank"><img src="https://img.shields.io/github/license/donnikitos/vite-plugin-php?color=blue&style=for-the-badge" alt="License" /></a>
+	<div></div>
+	<a href="https://www.npmjs.com/package/vite-plugin-php" target="_blank"><img src="https://img.shields.io/npm/dt/vite-plugin-php?style=for-the-badge" alt="NPM" /></a>
+	<a href="https://github.com/donnikitos/vite-plugin-php" target="_blank"><img src="https://img.shields.io/github/stars/donnikitos/vite-plugin-php?label=GitHub%20Stars&style=for-the-badge" alt="GitHub Stars" /></a>
+	<a href="https://github.com/donnikitos/vite-plugin-php/issues" target="_blank"><img src="https://img.shields.io/github/issues/donnikitos/vite-plugin-php?style=for-the-badge" alt="Issues" /></a>
+	<img src="https://img.shields.io/github/last-commit/donnikitos/vite-plugin-php?style=for-the-badge" alt="Last Commit" />
+</div>
+
+\
+Use Vite's speed and tooling to work with PHP!
 
 ```js
 // vite.config.js
@@ -15,23 +27,28 @@ export default defineConfig({
 });
 ```
 
-Check out the [starter repo](https://github.com/nititech/php-vite-starter) for an easy and convenient start:
-<a href="https://github.com/nititech/php-vite-starter" target="_blank"><img src="https://nititech.de/kosmo-starter-button.png" alt="Starter Repo"></a>
+<p align="center" style="text-align: center;">
+	<b>
+		<a href="https://vite-php.nititech.de/">Wiki</a> | <a href="https://github.com/donnikitos/vite-plugin-php/discussions">Discussions</a> | <a href="https://github.com/nititech/php-vite-starter">Starter-Repo</a>
+	</b>
+</p>
 
 ## ⚡ Latest changes
 
-| Version | Feature                                                                                                     |
-| ------- | ----------------------------------------------------------------------------------------------------------- |
-| 1.0.71  | Fixed assets prepending for namespaced PHP-files                                                            |
-| 1.0.70  | Added include path override for relative PHP imports in dev mode                                            |
-| 1.0.69  | Using new token format to escape PHP in HTML                                                                |
-| 1.0.68  | Improved transpiled code evaluation (removed native `eval()`)                                               |
-| 1.0.67  | Removed whitespaces from PHP responses in dev mode                                                          |
-| 1.0.66  | Fixed file monitoring on Windows                                                                            |
-| 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 |
-| ...     | ...                                                                                                         |
+##### Major Release 2.0.0 !!!
+
+Including full _PHP error logging_ into console, rewritten code for _better performance_, bug fixes, etc.\
+[See changelog](https://vite-php.nititech.de/changelog).
+
+##### Releases >= 1.0.0
+
+| Version | Feature                                                          |
+| ------- | ---------------------------------------------------------------- |
+| 1.0.71  | Fixed assets prepending for namespaced PHP-files                 |
+| 1.0.70  | Added include path override for relative PHP imports in dev mode |
+| 1.0.69  | Using new token format to escape PHP in HTML                     |
+| 1.0.68  | Improved transpiled code evaluation (removed native `eval()`)    |
+| ...     | ...                                                              |
 
 ## Write some PHP code in your `index.php`
 
@@ -45,11 +62,15 @@ Check out the [starter repo](https://github.com/nititech/php-vite-starter) for a
 		<meta name="viewport" content="width=device-width, initial-scale=1.0" />
 	</head>
 	<body>
-		<?="Render some text with PHP!";?>
+		<div id="root">
+			<?="Render some text with PHP!"; ?>
+		</div>
+
+		<?php if(isset($_GET['show_hello'])): ?>
+			Hello world!
+		<?php endif; ?>
 
-		<?php if(isset($_GET['dont_load'])) { ?>
-			<script src="./src/some_script.js" type="module"></script>
-		<?php } ?>
+		<script src="./src/react-app.tsx" type="module"></script>
 	</body>
 </html>
 ```
@@ -66,20 +87,44 @@ type UsePHPConfig = {
 	entry?: string | string[];
 	rewriteUrl?: (requestUrl: URL) => URL | undefined;
 	tempDir?: string;
-	cleanup?: {
-		dev?: boolean;
-		build?: boolean;
+	dev?: {
+		// Takes on either a bitmask, or named constants EPHPError
+		errorLevels?: number;
+		cleanup?: boolean;
 	};
 };
+
+// Detailed description on https://www.php.net/manual/en/errorfunc.constants.php
+const EPHPError = {
+	ERROR: 1,
+	WARNING: 2,
+	PARSE: 4,
+	NOTICE: 8,
+	CORE_ERROR: 16,
+	CORE_WARNING: 32,
+	COMPILE_ERROR: 64,
+	COMPILE_WARNING: 128,
+	USER_ERROR: 256,
+	USER_WARNING: 512,
+	USER_NOTICE: 1024,
+	STRICT: 2048,
+	RECOVERABLE_ERROR: 4096,
+	DEPRECATED: 8192,
+	USER_DEPRECATED: 16384,
+	ALL: 32767,
+};
 ```
 
 By default the plugin is trying to access the system `php`-binary and load the `index.php` file as the main entry point.
+
+#### Alternative entry points
+
 However you have the possibility to use an other binary or even compile multiple entry-points:
 
 ```js
 usePHP({
 	binary: '/opt/lampp/bin/php-8.1.10',
-	entry: ['index.php', 'about.php', 'contact.php'],
+	entry: ['index.php', 'index_alt.php', 'pages/contact.php'],
 });
 ```
 
@@ -94,7 +139,7 @@ Should you have multiple entry-points, you will be able to access each one accor
 | shop/index.php    | `/shop/` `/shop/index.php`            | `shop/index.php`    |
 | ...               | ...                                   | ...                 |
 
-Since version 1.0.6 you can specify wildcard entry points:
+You can also specify wildcard entry points:
 
 ```js
 usePHP({
@@ -111,7 +156,7 @@ usePHP({
 
 These entries will also render according to the routing table above.
 
-##### Rewrite urls
+#### 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:
@@ -134,6 +179,30 @@ usePHP({
 
 ⚠️ **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!
 
+#### Error logging
+
+Just like in native PHP you can specify what errors you want to see:
+
+```js
+// vite.config.js
+import { defineConfig } from 'vite';
+import usePHP, { EPHPError } from 'vite-plugin-php';
+
+export default defineConfig({
+	plugins: [
+		usePHP({
+			dev: {
+				errorLevels:
+					EPHPError.ERROR | EPHPError.WARNING | EPHPError.STRICT,
+			},
+		}),
+	],
+});
+```
+
+This log will be printed into your console, just like any other message about what is happening in Vite.\
+For more details about the meaning of the error level constants, visit the original [PHP-documentation](https://www.php.net/manual/en/errorfunc.constants.php).
+
 ## Specific oddities
 
 #### Inline modules
@@ -159,9 +228,27 @@ Same applies to other server variables like `$_GET`, `$_POST` and so on - they w
 Vite won't be able to process PHP-computed styles, scripts or images:
 
 ```php
-<script src="./src/<?='dynamic_script_name';?>.js" type="module"></script>
+<script src="./src/<?='dynamic_script_name'; ?>.js" type="module"></script>
 ```
 
+#### Conditional script and style loading
+
+The plugin won't be able to retain the position of some asset tags like `<script>` and `<link>`.
+
+```php
+<?php if($some_condition$) { ?>
+	<script src="./src/some_script.js" type="module"></script>
+<?php } ?>
+```
+
+Vite processes these independently and merges/ splits them dynamically.\
+These will be attached to the `<head>` tag or put right in the beginning of the file.
+
+If the file contains a PHP **namespace** the assets will be either\
+a) placed after the last closed tag\
+b) placed right before the last `<?` tag\
+c) placed at the end of the file
+
 ## Issues
 
 If you encounter any other bugs or need some other features feel free to open an [issue](https://github.com/donnikitos/vite-plugin-php/issues).