Skip to content

Commit 5734f46

Browse files
github-actions[bot]dunglas
github-actions[bot]
and
dunglas
authored
docs: update translations (#2263)
Translation updates for: hot-reload.md . Co-authored-by: dunglas <57224+dunglas@users.noreply.github.com>
1 parent 03c26ec commit 5734f46

File tree

5 files changed

+744
-0
lines changed

5 files changed

+744
-0
lines changed

‎docs/cn/hot-reload.md‎

Lines changed: 149 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,149 @@
1+
# 热重载
2+
3+
FrankenPHP 包含一个内置的**热重载**功能，旨在极大改善开发者的体验。
4+
5+
![Hot Reload](hot-reload.png)
6+
7+
此功能提供了类似于现代 JavaScript 工具（如 Vite 或 webpack）中的 **热模块替换 (HMR)** 的工作流程。
8+
无需在每次文件更改（PHP 代码、模板、JavaScript 和 CSS 文件等）后手动刷新浏览器，FrankenPHP 会实时更新页面内容。
9+
10+
热重载原生支持 WordPress、Laravel、Symfony 以及任何其他 PHP 应用程序或框架。
11+
12+
启用后，FrankenPHP 会监控您当前工作目录的文件系统变化。
13+
当文件被修改时，它会将 [Mercure](mercure.md) 更新推送到浏览器。
14+
15+
根据您的设置，浏览器将：
16+
17+
- 如果加载了 [Idiomorph](https://github.com/bigskysoftware/idiomorph)，则**修改 DOM**（保留滚动位置和输入状态）。
18+
- 如果 Idiomorph 不存在，则**重新加载页面**（标准实时重载）。
19+
20+
## 配置
21+
22+
要启用热重载，请先启用 Mercure，然后在 `Caddyfile` 的 `php_server` 指令中添加 `hot_reload` 子指令。
23+
24+
> [!WARNING]
25+
>
26+
> 此功能仅适用于**开发环境**。
27+
> 请勿在生产环境中启用 `hot_reload`，因为此功能不安全（会暴露敏感的内部细节）并且会降低应用程序的速度。
28+
>
29+
```caddyfile
30+
localhost
31+
32+
mercure {
33+
anonymous
34+
}
35+
36+
root public/
37+
php_server {
38+
hot_reload
39+
}
40+
```
41+
42+
默认情况下，FrankenPHP 会监控当前工作目录中匹配此全局模式的所有文件：`./**/*.{css,env,gif,htm,html,jpg,jpeg,js,mjs,php,png,svg,twig,webp,xml,yaml,yml}`
43+
44+
可以通过全局语法显式设置要监控的文件：
45+
46+
```caddyfile
47+
localhost
48+
49+
mercure {
50+
anonymous
51+
}
52+
53+
root public/
54+
php_server {
55+
hot_reload src/**/*{.php,.js} config/**/*.yaml
56+
}
57+
```
58+
59+
使用 `hot_reload` 的长格式来指定要使用的 Mercure 主题以及要监控的目录或文件：
60+
61+
```caddyfile
62+
localhost
63+
64+
mercure {
65+
anonymous
66+
}
67+
68+
root public/
69+
php_server {
70+
hot_reload {
71+
topic hot-reload-topic
72+
watch src/**/*.php
73+
watch assets/**/*.{ts,json}
74+
watch templates/
75+
watch public/css/
76+
}
77+
}
78+
```
79+
80+
## 客户端集成
81+
82+
尽管服务器检测到更改，但浏览器需要订阅这些事件才能更新页面。
83+
FrankenPHP 通过 `$_SERVER['FRANKENPHP_HOT_RELOAD']` 环境变量公开用于订阅文件更改的 Mercure Hub URL。
84+
85+
还提供了一个方便的 JavaScript 库 [frankenphp-hot-reload](https://www.npmjs.com/package/frankenphp-hot-reload) 来处理客户端逻辑。
86+
要使用它，请将以下内容添加到您的主布局中：
87+
88+
```php
89+
<!DOCTYPE html>
90+
<title>FrankenPHP Hot Reload</title>
91+
<?php if (isset($_SERVER['FRANKENPHP_HOT_RELOAD'])): ?>
92+
<meta name="frankenphp-hot-reload:url" content="<?=$_SERVER['FRANKENPHP_HOT_RELOAD']?>">
93+
<script src="https://cdn.jsdelivr.net/npm/idiomorph"></script>
94+
<script src="https://cdn.jsdelivr.net/npm/frankenphp-hot-reload/+esm" type="module"></script>
95+
<?php endif ?>
96+
```
97+
98+
该库将自动订阅 Mercure hub，在检测到文件更改时在后台获取当前 URL，并修改 DOM。
99+
它作为 [npm](https://www.npmjs.com/package/frankenphp-hot-reload) 包和在 [GitHub](https://github.com/dunglas/frankenphp-hot-reload) 上提供。
100+
101+
或者，您可以通过使用 `EventSource` 原生 JavaScript 类直接订阅 Mercure hub 来实现自己的客户端逻辑。
102+
103+
### 保留现有 DOM 节点
104+
105+
在极少数情况下，例如使用开发工具（[如 Symfony web 调试工具栏](https://github.com/symfony/symfony/pull/62970)）时，
106+
您可能希望保留特定的 DOM 节点。
107+
为此，请将 `data-frankenphp-hot-reload-preserve` 属性添加到相关的 HTML 元素：
108+
109+
```html
110+
<div data-frankenphp-hot-reload-preserve><!-- 我的调试栏 --></div>
111+
```
112+
113+
## Worker 模式
114+
115+
如果您的应用程序在 [Worker 模式](https://frankenphp.dev/docs/worker/)下运行，您的应用程序脚本会保留在内存中。
116+
这意味着即使浏览器重新加载，您对 PHP 代码的更改也不会立即反映。
117+
118+
为了获得最佳的开发者体验，您应该将 `hot_reload` 与 [worker 指令中的 `watch` 子指令](config.md#watching-for-file-changes)结合使用。
119+
120+
- `hot_reload`：文件更改时刷新**浏览器**
121+
- `worker.watch`：文件更改时重启 worker
122+
123+
```caddy
124+
localhost
125+
126+
mercure {
127+
anonymous
128+
}
129+
130+
root public/
131+
php_server {
132+
hot_reload
133+
worker {
134+
file /path/to/my_worker.php
135+
watch
136+
}
137+
}
138+
```
139+
140+
## 工作原理
141+
142+
1. **监控**：FrankenPHP 使用底层 [e-dant/watcher 库](https://github.com/e-dant/watcher)（我们贡献了 Go 绑定）监控文件系统中的修改。
143+
2. **重启 (Worker 模式)**：如果 worker 配置中启用了 `watch`，PHP worker 将重新启动以加载新代码。
144+
3. **推送**：包含更改文件列表的 JSON 有效载荷被发送到内置的 [Mercure hub](https://mercure.rocks)。
145+
4. **接收**：浏览器通过 JavaScript 库监听，接收 Mercure 事件。
146+
5. **更新**：
147+
148+
- 如果检测到 **Idiomorph**，它会获取更新的内容并修改当前的 HTML 以匹配新状态，即时应用更改而不会丢失状态。
149+
- 否则，将调用 `window.location.reload()` 来刷新页面。

‎docs/ja/hot-reload.md‎

Lines changed: 149 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,149 @@
1+
# ホットリロード
2+
3+
FrankenPHPには、開発者のエクスペリエンスを大幅に向上させるために設計された組み込みの**ホットリロード**機能が含まれています。
4+
5+
![Hot Reload](hot-reload.png)
6+
7+
この機能は、ViteやwebpackなどのモダンなJavaScriptツールにおける**ホットモジュールリプレースメント (HMR)** に似たワークフローを提供します。
8+
ファイルの変更（PHPコード、テンプレート、JavaScript、CSSファイルなど）のたびに手動でブラウザをリフレッシュする代わりに、
9+
FrankenPHPはページの内容をリアルタイムで更新します。
10+
11+
ホットリロードは、WordPress、Laravel、Symfony、その他すべてのPHPアプリケーションやフレームワークでネイティブに動作します。
12+
13+
有効にすると、FrankenPHPは現在の作業ディレクトリにおけるファイルシステムの変更を監視します。
14+
ファイルが変更されると、[Mercure](mercure.md)の更新をブラウザにプッシュします。
15+
16+
設定に応じて、ブラウザは以下のいずれかを実行します。
17+
18+
- [Idiomorph](https://github.com/bigskysoftware/idiomorph)がロードされている場合、**DOMをモーフィング**します（スクロール位置と入力状態を保持）。
19+
- Idiomorphが存在しない場合、**ページをリロード**します（標準のライブリロード）。
20+
21+
## 設定
22+
23+
ホットリロードを有効にするには、Mercureを有効にしてから、`Caddyfile`の`php_server`ディレクティブに`hot_reload`サブディレクティブを追加します。
24+
25+
> [!WARNING]
26+
>
27+
> この機能は**開発環境のみ**を対象としています。
28+
> `hot_reload`を本番環境で有効にしないでください。この機能は安全ではなく（機密性の高い内部詳細を公開します）、アプリケーションの速度を低下させます。
29+
>
30+
```caddyfile
31+
localhost
32+
33+
mercure {
34+
anonymous
35+
}
36+
37+
root public/
38+
php_server {
39+
hot_reload
40+
}
41+
```
42+
43+
デフォルトでは、FrankenPHPは現在の作業ディレクトリ内の以下のグロブパターンに一致するすべてのファイルを監視します: `./**/*.{css,env,gif,htm,html,jpg,jpeg,js,mjs,php,png,svg,twig,webp,xml,yaml,yml}`
44+
45+
グロブ構文を使用して、監視するファイルを明示的に設定することも可能です。
46+
47+
```caddyfile
48+
localhost
49+
50+
mercure {
51+
anonymous
52+
}
53+
54+
root public/
55+
php_server {
56+
hot_reload src/**/*{.php,.js} config/**/*.yaml
57+
}
58+
```
59+
60+
使用するMercureトピック、および監視するディレクトリまたはファイルを指定するには、`hot_reload`のロングフォームを使用します。
61+
62+
```caddyfile
63+
localhost
64+
65+
mercure {
66+
anonymous
67+
}
68+
69+
root public/
70+
php_server {
71+
hot_reload {
72+
topic hot-reload-topic
73+
watch src/**/*.php
74+
watch assets/**/*.{ts,json}
75+
watch templates/
76+
watch public/css/
77+
}
78+
}
79+
```
80+
81+
## クライアントサイドの統合
82+
83+
サーバーは変更を検出しますが、ブラウザはこれらのイベントを購読してページを更新する必要があります。
84+
FrankenPHPは、ファイル変更を購読するために使用するMercure HubのURLを、`$_SERVER['FRANKENPHP_HOT_RELOAD']`環境変数を通じて公開します。
85+
86+
クライアントサイドのロジックを処理するための便利なJavaScriptライブラリ、[frankenphp-hot-reload](https://www.npmjs.com/package/frankenphp-hot-reload)も利用可能です。
87+
これを使用するには、メインレイアウトに以下を追加します。
88+
89+
```php
90+
<!DOCTYPE html>
91+
<title>FrankenPHP Hot Reload</title>
92+
<?php if (isset($_SERVER['FRANKENPHP_HOT_RELOAD'])): ?>
93+
<meta name="frankenphp-hot-reload:url" content="<?=$_SERVER['FRANKENPHP_HOT_RELOAD']?>">
94+
<script src="https://cdn.jsdelivr.net/npm/idiomorph"></script>
95+
<script src="https://cdn.jsdelivr.net/npm/frankenphp-hot-reload/+esm" type="module"></script>
96+
<?php endif ?>
97+
```
98+
99+
このライブラリは自動的にMercureハブを購読し、ファイル変更が検出されるとバックグラウンドで現在のURLをフェッチし、DOMをモーフィングします。
100+
[npm](https://www.npmjs.com/package/frankenphp-hot-reload)パッケージとして、また[GitHub](https://github.com/dunglas/frankenphp-hot-reload)で利用できます。
101+
102+
または、`EventSource`ネイティブJavaScriptクラスを使用してMercureハブに直接購読することで、独自のクライアントサイドロジックを実装することもできます。
103+
104+
### 既存のDOMノードを保持する
105+
106+
まれに、[Symfonyのウェブデバッグツールバーなどの開発ツール](https://github.com/symfony/symfony/pull/62970)を使用している場合など、特定のDOMノードを保持したいことがあります。
107+
そのためには、関連するHTML要素に`data-frankenphp-hot-reload-preserve`属性を追加します。
108+
109+
```html
110+
<div data-frankenphp-hot-reload-preserve><!-- My debug bar --></div>
111+
```
112+
113+
## ワーカーモード
114+
115+
アプリケーションを[ワーカーモード](https://frankenphp.dev/docs/worker/)で実行している場合、アプリケーションスクリプトはメモリに常駐します。
116+
これは、ブラウザがリロードされても、PHPコードの変更がすぐに反映されないことを意味します。
117+
118+
最高の開発者エクスペリエンスのためには、`hot_reload`を[ワーカーディレクティブ内の`watch`サブディレクティブ](config.md#watching-for-file-changes)と組み合わせるべきです。
119+
120+
- `hot_reload`: ファイルが変更されたときに**ブラウザ**をリフレッシュします
121+
- `worker.watch`: ファイルが変更されたときにワーカーを再起動します
122+
123+
```caddy
124+
localhost
125+
126+
mercure {
127+
anonymous
128+
}
129+
130+
root public/
131+
php_server {
132+
hot_reload
133+
worker {
134+
file /path/to/my_worker.php
135+
watch
136+
}
137+
}
138+
```
139+
140+
## 仕組み
141+
142+
1. **監視**: FrankenPHPは、内部で[`e-dant/watcher`ライブラリ](https://github.com/e-dant/watcher)を使用してファイルシステムの変更を監視します（私たちはGoバインディングに貢献しました）。
143+
2. **再起動 (ワーカーモード)**: ワーカー設定で`watch`が有効になっている場合、新しいコードをロードするためにPHPワーカーが再起動されます。
144+
3. **プッシュ**: 変更されたファイルのリストを含むJSONペイロードが、組み込みの[Mercureハブ](https://mercure.rocks)に送信されます。
145+
4. **受信**: JavaScriptライブラリを介してリッスンしているブラウザがMercureイベントを受信します。
146+
5. **更新**:
147+
148+
- **Idiomorph**が検出された場合、更新されたコンテンツをフェッチし、現在のHTMLを新しい状態に合わせてモーフィングし、状態を失うことなく即座に変更を適用します。
149+
- それ以外の場合、`window.location.reload()`が呼び出されてページがリフレッシュされます。

0 commit comments

Comments
 (0)