16453725530

Committed 22 Jul 2025 07:30PM UTC coverage: 85.185% (-6.8%) from 91.935%

Build # 16453725530

Build Type

push

github

Committed by

dakujem

Commit Message

Dev server "tell" file detector

Run Details

3 of 13 new or added lines in 1 file covered. (23.08%)

115 of 135 relevant lines covered (85.19%)

5.93 hits per line

Source File
Press 'n' to go to next uncovered line, 'b' for previous

73.17

/src/ViteBridge.php

<?php

declare(strict_types=1);

namespace Dakujem\Peat;

use LogicException;
use RuntimeException;

/**
 * A factory service providing Vite entry locators.
 * Also provides an ability to populate a PHP cache file for performance improvement.
 *
 * @author Andrej Rypak <xrypak@gmail.com>
 */
final class ViteBridge
{
    private string $manifestFile;
    private ?string $cacheFile;
    private string $assetPathPrefix;
    private ?string $devServerUrl;
    private bool $strict;

    /**
     * The $assetPath can be used to force absolute paths or set the base path. Ignored by the dev server.
     *
     * @param string $manifestFile Path to the Vite-generated manifest json file.
     * @param string|null $cacheFile This is where this locator stores (and reads from) its cache file. Must be writable.
     * @param string $assetPathPrefix This will typically be relative path from the public dir to the dir with assets, or empty string ''.
     * @param ?string $devServerUrl Vite's dev server URL (development only).
     * @param bool $strict Locators throw exceptions in strict mode, silently fail in lax mode.
     */
    public function __construct(
        string $manifestFile,
        ?string $cacheFile = null,
        string $assetPathPrefix = '',
        ?string $devServerUrl = null,
        bool $strict = false
    ) {
        $this->manifestFile = $manifestFile;
        $this->cacheFile = $cacheFile;
        $this->assetPathPrefix = $assetPathPrefix;
        $this->devServerUrl = $devServerUrl;
        $this->strict = $strict;
    }

    /**
     * Returns a preconfigured asset entry locator.
     * The method attempts to tell if the dev server is running by detecting the presence of a "tell" file.
     * Vite should be configured to create such a file when starting the dev server.
     *
     * @param bool $detectServer Set this to `false` in production or when the assets should always be located from a bundle.
     * @param string $tellFileName The location of the "tell" file.
     * @param bool $readContentsAsUrl Decide whether the contents of the tell file should be used as the URL of the dev server or set to `false` to use the constructor argument.
     */
    public function makeServerTellEntryLocator(
        bool $detectServer,
        string $tellFileName,
        bool $readContentsAsUrl = true
    ): ViteLocatorContract {
        if (!$detectServer) {
            // When the server detection is off, the assets are served from a bundle (build).
            return $this->makeBundleEntryLocator();
        }

        // The dev server is detected by the presence of a "tell" file.
        if (!file_exists($tellFileName)) {
            return $this->makeBundleEntryLocator();
        }

        // If the dev server is running, it serves all the assets.
        $url = null;

        // The "tell" file may optionally contain a URL the dev server is listening to.
        if ($readContentsAsUrl) {
            $url = file_get_contents($tellFileName);
            if (!filter_var($url, FILTER_VALIDATE_URL)) {
                $url = null;
            }
        }

        return $this->makeDevServerEntryLocator($url);
    }

    /**
     * Returns a preconfigured asset entry locator.
     * The locator reads the manifest file (or cache file) and serves asset objects.
     *
     * If the $useDevServer is `true`, links to Vite dev server are returned by the locator.
     *
     * This call does not detect whether the dev server is actually running or not (hence "passive").
     *
     * @param bool $useDevServer Set this to `false` in production or when the assets should be located from a bundle.
     */
    public function makePassiveEntryLocator(
        bool $useDevServer = false
    ): ViteLocatorContract {
        // If the dev server is used, it serves all the assets.
        if ($useDevServer) {
            return $this->makeDevServerEntryLocator();
        }
        // Otherwise, the assets are served from a bundle (build).
        return $this->makeBundleEntryLocator();
    }

    /**
     * Returns a preconfigured asset entry locator for development.
     * The locator returns entries pointing to the Vite development server for any asset being resolved.
     */
    public function makeDevServerEntryLocator(?string $devServerUrl = null): ViteLocatorContract
    {
        $devServerUrl ??= $this->devServerUrl;
        if ($devServerUrl === null) {
            throw new LogicException('The development server URL has not been provided.');
        }

        return new ViteServerLocator($devServerUrl);
    }

    /**
     * Returns a preconfigured asset entry locator for production builds.
     * The locator reads the manifest file (or cache file) and serves asset objects.
     */
    public function makeBundleEntryLocator(): ViteLocatorContract
    {
        $bundleLocator = new ViteBuildLocator(
            $this->manifestFile,
            $this->cacheFile,
            $this->assetPathPrefix,
            $this->strict,
        );
        if (!$this->strict) {
            return $bundleLocator;
        }
        // In strict mode, the final step is to throw an exception.
        return new CollectiveLocator(
            $bundleLocator,
            function (string $name) {
                throw new RuntimeException('Not found: ' . $name);
            },
        );
    }

    /**
     * Populates a cache file to be included instead of parsing the Vite bundle's JSON manifest file.
     * Should be called during the deployment/CI process as one of the build steps.
     */
    public function populateCache(): void
    {
        (new ViteBuildLocator(
            $this->manifestFile,
            $this->cacheFile,
            $this->assetPathPrefix,
            $this->strict,
        ))
            ->populateCache();
    }
}

1	<?php
2
3	declare(strict_types=1);
4
5	namespace Dakujem\Peat;
6
7	use LogicException;
8	use RuntimeException;
9
10	/**
11	* A factory service providing Vite entry locators.
12	* Also provides an ability to populate a PHP cache file for performance improvement.
13	*
14	* @author Andrej Rypak <xrypak@gmail.com>
15	*/
16	final class ViteBridge
17	{
18	private string $manifestFile;
19	private ?string $cacheFile;
20	private string $assetPathPrefix;
21	private ?string $devServerUrl;
22	private bool $strict;
23
24	/**
25	* The $assetPath can be used to force absolute paths or set the base path. Ignored by the dev server.
26	*
27	* @param string $manifestFile Path to the Vite-generated manifest json file.
28	* @param string\|null $cacheFile This is where this locator stores (and reads from) its cache file. Must be writable.
29	* @param string $assetPathPrefix This will typically be relative path from the public dir to the dir with assets, or empty string ''.
30	* @param ?string $devServerUrl Vite's dev server URL (development only).
31	* @param bool $strict Locators throw exceptions in strict mode, silently fail in lax mode.
32	*/
33	public function __construct(
34	string $manifestFile,
35	?string $cacheFile = null,
36	string $assetPathPrefix = '',
37	?string $devServerUrl = null,
38	bool $strict = false
39	) {
40	$this->manifestFile = $manifestFile;	7✔
41	$this->cacheFile = $cacheFile;	7✔
42	$this->assetPathPrefix = $assetPathPrefix;	7✔
43	$this->devServerUrl = $devServerUrl;	7✔
44	$this->strict = $strict;	7✔
45	}	7✔
46
47	/**
48	* Returns a preconfigured asset entry locator.
49	* The method attempts to tell if the dev server is running by detecting the presence of a "tell" file.
50	* Vite should be configured to create such a file when starting the dev server.
51	*
52	* @param bool $detectServer Set this to `false` in production or when the assets should always be located from a bundle.
53	* @param string $tellFileName The location of the "tell" file.
54	* @param bool $readContentsAsUrl Decide whether the contents of the tell file should be used as the URL of the dev server or set to `false` to use the constructor argument.
55	*/
56	public function makeServerTellEntryLocator(
57	bool $detectServer,
58	string $tellFileName,
59	bool $readContentsAsUrl = true
60	): ViteLocatorContract {
NEW 61	if (!$detectServer) {	×
62	// When the server detection is off, the assets are served from a bundle (build).
NEW 63	return $this->makeBundleEntryLocator();	×
64	}
65
66	// The dev server is detected by the presence of a "tell" file.
NEW 67	if (!file_exists($tellFileName)) {	×
NEW 68	return $this->makeBundleEntryLocator();	×
69	}
70
71	// If the dev server is running, it serves all the assets.
NEW 72	$url = null;	×
73
74	// The "tell" file may optionally contain a URL the dev server is listening to.
NEW 75	if ($readContentsAsUrl) {	×
NEW 76	$url = file_get_contents($tellFileName);	×
NEW 77	if (!filter_var($url, FILTER_VALIDATE_URL)) {	×
NEW 78	$url = null;	×
79	}
80	}
81
NEW 82	return $this->makeDevServerEntryLocator($url);	×
83	}
84
85	/**
86	* Returns a preconfigured asset entry locator.
87	* The locator reads the manifest file (or cache file) and serves asset objects.
88	*
89	* If the $useDevServer is `true`, links to Vite dev server are returned by the locator.
90	*
91	* This call does not detect whether the dev server is actually running or not (hence "passive").
92	*
93	* @param bool $useDevServer Set this to `false` in production or when the assets should be located from a bundle.
94	*/
95	public function makePassiveEntryLocator(
96	bool $useDevServer = false
97	): ViteLocatorContract {
98	// If the dev server is used, it serves all the assets.
99	if ($useDevServer) {	7✔
100	return $this->makeDevServerEntryLocator();	7✔
101	}
102	// Otherwise, the assets are served from a bundle (build).
103	return $this->makeBundleEntryLocator();	7✔
104	}
105
106	/**
107	* Returns a preconfigured asset entry locator for development.
108	* The locator returns entries pointing to the Vite development server for any asset being resolved.
109	*/
110	public function makeDevServerEntryLocator(?string $devServerUrl = null): ViteLocatorContract
111	{
112	$devServerUrl ??= $this->devServerUrl;	7✔
113	if ($devServerUrl === null) {	7✔
114	throw new LogicException('The development server URL has not been provided.');	7✔
115	}
116
117	return new ViteServerLocator($devServerUrl);	7✔
118	}
119
120	/**
121	* Returns a preconfigured asset entry locator for production builds.
122	* The locator reads the manifest file (or cache file) and serves asset objects.
123	*/
124	public function makeBundleEntryLocator(): ViteLocatorContract
125	{
126	$bundleLocator = new ViteBuildLocator(	7✔
127	$this->manifestFile,	7✔
128	$this->cacheFile,	7✔
129	$this->assetPathPrefix,	7✔
130	$this->strict,	7✔
131	);
132	if (!$this->strict) {	7✔
133	return $bundleLocator;	7✔
134	}
135	// In strict mode, the final step is to throw an exception.
136	return new CollectiveLocator(	7✔
137	$bundleLocator,
138	function (string $name) {	7✔
139	throw new RuntimeException('Not found: ' . $name);	×
140	},	7✔
141	);
142	}
143
144	/**
145	* Populates a cache file to be included instead of parsing the Vite bundle's JSON manifest file.
146	* Should be called during the deployment/CI process as one of the build steps.
147	*/
148	public function populateCache(): void
149	{
150	(new ViteBuildLocator(	7✔
151	$this->manifestFile,	7✔
152	$this->cacheFile,	7✔
153	$this->assetPathPrefix,	7✔
154	$this->strict,	7✔
155	))
156	->populateCache();	7✔
157	}	7✔
158	}

dakujem / peat / 16453725530

Source File Press 'n' to go to next uncovered line, 'b' for previous

Source File
Press 'n' to go to next uncovered line, 'b' for previous