=== Embed JavaScript File Content ===
Contributors: palasthotel, greatestview
Donate link: https://palasthotel.de/
Tags: javascript, scripts, enqueue, embed, inline, head, critical, performance, filter, hook
Requires at least: 4.1
Tested up to: 7.0.2
Stable tag: 1.0.2
Requires PHP: 5.4
License: GPL-3.0-or-later
License URI: https://www.gnu.org/licenses/gpl-3.0.html

RETIRED — no longer maintained. Please deactivate and remove this plugin; the description explains what to use instead.

== Description ==

**This plugin is retired and no longer maintained. Please deactivate and remove it.**

Version 1.0.2 exists only to carry this notice and to repair a fatal error: the
plugin called `DOMDocument::loadHTML()` statically, which PHP 8 rejects. Any site
that actually configured the filter has been showing "There has been a critical
error on this website" since its PHP 8 upgrade. Sites that installed the plugin
without configuring the filter were unaffected, because it does nothing until a
handle is passed to it.

= What to do instead =

If you wrote the script yourself, do not inline the file — write the code inline
in the first place. WordPress has supported that since 4.5:

`wp_add_inline_script( 'my-handle', 'if (!("localStorage" in window)) { /* ... */ }', 'before' );`

or, for code that has to run before anything else paints, print it in `wp_head`
directly. Both are simpler than routing a file through a plugin, and neither
breaks a Content Security Policy the way an inlined file does — this plugin sets
neither a nonce nor a hash, so a strict `script-src` blocks its output.

For a script you do not control there is no drop-in replacement, and our older
Inline JavaScript in Head plugin is not one either — it was deprecated in 2020 in
favour of this plugin, so both are dead ends now. What is left is to dequeue the
foreign script yourself and re-add its content inline:

`add_action( 'wp_enqueue_scripts', function () {
	$handle = 'some-foreign-handle';
	$src    = wp_scripts()->registered[ $handle ]->src ?? null;
	if ( ! $src ) {
		return;
	}
	$path = ABSPATH . ltrim( wp_make_link_relative( $src ), '/' );
	if ( ! is_readable( $path ) ) {
		return;
	}
	wp_dequeue_script( $handle );
	wp_add_inline_script( 'some-handle-you-own', file_get_contents( $path ) );
}, 20 );`

That is roughly what this plugin did, minus the URL-to-path guessing — you decide
how the file is located, so it cannot break on a subdirectory install or a CDN.

= Why it is being retired =

The benefit it was written for has largely gone. Under HTTP/2 and HTTP/3 requests
are multiplexed, so the per-file cost that made inlining worthwhile is mostly
gone, and inlining still costs you browser caching — the code travels with every
single HTML response. What remains is a narrow case: inlining a file you cannot
edit. That is not enough to keep a plugin for.

= How it used to work =

In some critical cases you cannot wait for a JavaScript file to load. Then you can benefit from better performance, if you embed the JavaScript code directly into the `<script>` tag. This is where this plugin comes in: It provides a filter `embed_javascript_file_content_handles`, which takes JavaScript handles and echos their code content into the DOM instead of linking to a file.

Please beware that placing lots of embedded JavaScript code can be critical! First you lose caching benefits and second the document size can increase easily. A general rule of thumb is that you should only consider JavaScript files for inline placement, which are critical and which have a file size lower than ~500 Bytes.

= Example =

`
add_action( 'wp_enqueue_scripts', 'my_scripts' );
function my_scripts() {
	// Some critical script is enqueued
	wp_enqueue_script( 'js-detection', get_template_directory_uri() . '/js/js-detection.js' );
}

/**
 * Define JavaScript handles to be echoed inline in the html head section.
 */
add_filter( 'embed_javascript_file_content_handles', 'my_embed_javascript_file_content_handles' );
function my_embed_javascript_file_content_handles( $handles ) {
	$scripts = [ 'js-detection' ];

	return array_merge( $handles, $scripts );
}
`


== Installation ==

Please do not install this plugin any more — it is retired. See the description
for what to use instead.

To remove it: drop the `embed_javascript_file_content_handles` filter from your
theme or plugin, then deactivate and delete the plugin. It stores no options and
creates no database tables, so nothing is left behind.

== Upgrade Notice ==

= 1.0.2 =
This plugin is retired. This release repairs a fatal error on PHP 8 and carries the
retirement notice. Please deactivate and remove it; the description explains what
to use instead.

== Changelog ==

= 1.0.2 =
* Final release. The plugin is retired and no longer maintained. Fixes a fatal error on PHP 8, where DOMDocument::loadHTML() was called statically. The readme explains what to use instead.

= 1.0.1 =
* Small stabilization fix

= 1.0 =
* First release
