mirror of
https://github.com/php/frankenphp.git
synced 2026-03-24 00:52:11 +01:00
docs: update translations (#2263)
Translation updates for: hot-reload.md . Co-authored-by: dunglas <57224+dunglas@users.noreply.github.com>
This commit is contained in:
github-actions[bot]
committed by
GitHub
GitHub
parent
03c26eca02
commit
5734f466bc
149
docs/cn/hot-reload.md
Normal file
149
docs/cn/hot-reload.md
Normal file
@@ -0,0 +1,149 @@
|
||||
# 热重载
|
||||
|
||||
FrankenPHP 包含一个内置的**热重载**功能，旨在极大改善开发者的体验。
|
||||
|
||||
|
||||
|
||||
此功能提供了类似于现代 JavaScript 工具（如 Vite 或 webpack）中的 **热模块替换 (HMR)** 的工作流程。
|
||||
无需在每次文件更改（PHP 代码、模板、JavaScript 和 CSS 文件等）后手动刷新浏览器，FrankenPHP 会实时更新页面内容。
|
||||
|
||||
热重载原生支持 WordPress、Laravel、Symfony 以及任何其他 PHP 应用程序或框架。
|
||||
|
||||
启用后，FrankenPHP 会监控您当前工作目录的文件系统变化。
|
||||
当文件被修改时，它会将 [Mercure](mercure.md) 更新推送到浏览器。
|
||||
|
||||
根据您的设置，浏览器将：
|
||||
|
||||
- 如果加载了 [Idiomorph](https://github.com/bigskysoftware/idiomorph)，则**修改 DOM**（保留滚动位置和输入状态）。
|
||||
- 如果 Idiomorph 不存在，则**重新加载页面**（标准实时重载）。
|
||||
|
||||
## 配置
|
||||
|
||||
要启用热重载，请先启用 Mercure，然后在 `Caddyfile` 的 `php_server` 指令中添加 `hot_reload` 子指令。
|
||||
|
||||
> [!WARNING]
|
||||
>
|
||||
> 此功能仅适用于**开发环境**。
|
||||
> 请勿在生产环境中启用 `hot_reload`，因为此功能不安全（会暴露敏感的内部细节）并且会降低应用程序的速度。
|
||||
>
|
||||
```caddyfile
|
||||
localhost
|
||||
|
||||
mercure {
|
||||
anonymous
|
||||
}
|
||||
|
||||
root public/
|
||||
php_server {
|
||||
hot_reload
|
||||
}
|
||||
```
|
||||
|
||||
默认情况下，FrankenPHP 会监控当前工作目录中匹配此全局模式的所有文件：`./**/*.{css,env,gif,htm,html,jpg,jpeg,js,mjs,php,png,svg,twig,webp,xml,yaml,yml}`
|
||||
|
||||
可以通过全局语法显式设置要监控的文件：
|
||||
|
||||
```caddyfile
|
||||
localhost
|
||||
|
||||
mercure {
|
||||
anonymous
|
||||
}
|
||||
|
||||
root public/
|
||||
php_server {
|
||||
hot_reload src/**/*{.php,.js} config/**/*.yaml
|
||||
}
|
||||
```
|
||||
|
||||
使用 `hot_reload` 的长格式来指定要使用的 Mercure 主题以及要监控的目录或文件：
|
||||
|
||||
```caddyfile
|
||||
localhost
|
||||
|
||||
mercure {
|
||||
anonymous
|
||||
}
|
||||
|
||||
root public/
|
||||
php_server {
|
||||
hot_reload {
|
||||
topic hot-reload-topic
|
||||
watch src/**/*.php
|
||||
watch assets/**/*.{ts,json}
|
||||
watch templates/
|
||||
watch public/css/
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## 客户端集成
|
||||
|
||||
尽管服务器检测到更改，但浏览器需要订阅这些事件才能更新页面。
|
||||
FrankenPHP 通过 `$_SERVER['FRANKENPHP_HOT_RELOAD']` 环境变量公开用于订阅文件更改的 Mercure Hub URL。
|
||||
|
||||
还提供了一个方便的 JavaScript 库 [frankenphp-hot-reload](https://www.npmjs.com/package/frankenphp-hot-reload) 来处理客户端逻辑。
|
||||
要使用它，请将以下内容添加到您的主布局中：
|
||||
|
||||
```php
|
||||
<!DOCTYPE html>
|
||||
<title>FrankenPHP Hot Reload</title>
|
||||
<?php if (isset($_SERVER['FRANKENPHP_HOT_RELOAD'])): ?>
|
||||
<meta name="frankenphp-hot-reload:url" content="<?=$_SERVER['FRANKENPHP_HOT_RELOAD']?>">
|
||||
<script src="https://cdn.jsdelivr.net/npm/idiomorph"></script>
|
||||
<script src="https://cdn.jsdelivr.net/npm/frankenphp-hot-reload/+esm" type="module"></script>
|
||||
<?php endif ?>
|
||||
```
|
||||
|
||||
该库将自动订阅 Mercure hub，在检测到文件更改时在后台获取当前 URL，并修改 DOM。
|
||||
它作为 [npm](https://www.npmjs.com/package/frankenphp-hot-reload) 包和在 [GitHub](https://github.com/dunglas/frankenphp-hot-reload) 上提供。
|
||||
|
||||
或者，您可以通过使用 `EventSource` 原生 JavaScript 类直接订阅 Mercure hub 来实现自己的客户端逻辑。
|
||||
|
||||
### 保留现有 DOM 节点
|
||||
|
||||
在极少数情况下，例如使用开发工具（[如 Symfony web 调试工具栏](https://github.com/symfony/symfony/pull/62970)）时，
|
||||
您可能希望保留特定的 DOM 节点。
|
||||
为此，请将 `data-frankenphp-hot-reload-preserve` 属性添加到相关的 HTML 元素：
|
||||
|
||||
```html
|
||||
<div data-frankenphp-hot-reload-preserve><!-- 我的调试栏 --></div>
|
||||
```
|
||||
|
||||
## Worker 模式
|
||||
|
||||
如果您的应用程序在 [Worker 模式](https://frankenphp.dev/docs/worker/)下运行，您的应用程序脚本会保留在内存中。
|
||||
这意味着即使浏览器重新加载，您对 PHP 代码的更改也不会立即反映。
|
||||
|
||||
为了获得最佳的开发者体验，您应该将 `hot_reload` 与 [worker 指令中的 `watch` 子指令](config.md#watching-for-file-changes)结合使用。
|
||||
|
||||
- `hot_reload`：文件更改时刷新**浏览器**
|
||||
- `worker.watch`：文件更改时重启 worker
|
||||
|
||||
```caddy
|
||||
localhost
|
||||
|
||||
mercure {
|
||||
anonymous
|
||||
}
|
||||
|
||||
root public/
|
||||
php_server {
|
||||
hot_reload
|
||||
worker {
|
||||
file /path/to/my_worker.php
|
||||
watch
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## 工作原理
|
||||
|
||||
1. **监控**：FrankenPHP 使用底层 [e-dant/watcher 库](https://github.com/e-dant/watcher)（我们贡献了 Go 绑定）监控文件系统中的修改。
|
||||
2. **重启 (Worker 模式)**：如果 worker 配置中启用了 `watch`，PHP worker 将重新启动以加载新代码。
|
||||
3. **推送**：包含更改文件列表的 JSON 有效载荷被发送到内置的 [Mercure hub](https://mercure.rocks)。
|
||||
4. **接收**：浏览器通过 JavaScript 库监听，接收 Mercure 事件。
|
||||
5. **更新**：
|
||||
|
||||
- 如果检测到 **Idiomorph**，它会获取更新的内容并修改当前的 HTML 以匹配新状态，即时应用更改而不会丢失状态。
|
||||
- 否则，将调用 `window.location.reload()` 来刷新页面。
|
||||
149
docs/ja/hot-reload.md
Normal file
149
docs/ja/hot-reload.md
Normal file
@@ -0,0 +1,149 @@
|
||||
# ホットリロード
|
||||
|
||||
FrankenPHPには、開発者のエクスペリエンスを大幅に向上させるために設計された組み込みの**ホットリロード**機能が含まれています。
|
||||
|
||||
|
||||
|
||||
この機能は、ViteやwebpackなどのモダンなJavaScriptツールにおける**ホットモジュールリプレースメント (HMR)** に似たワークフローを提供します。
|
||||
ファイルの変更（PHPコード、テンプレート、JavaScript、CSSファイルなど）のたびに手動でブラウザをリフレッシュする代わりに、
|
||||
FrankenPHPはページの内容をリアルタイムで更新します。
|
||||
|
||||
ホットリロードは、WordPress、Laravel、Symfony、その他すべてのPHPアプリケーションやフレームワークでネイティブに動作します。
|
||||
|
||||
有効にすると、FrankenPHPは現在の作業ディレクトリにおけるファイルシステムの変更を監視します。
|
||||
ファイルが変更されると、[Mercure](mercure.md)の更新をブラウザにプッシュします。
|
||||
|
||||
設定に応じて、ブラウザは以下のいずれかを実行します。
|
||||
|
||||
- [Idiomorph](https://github.com/bigskysoftware/idiomorph)がロードされている場合、**DOMをモーフィング**します（スクロール位置と入力状態を保持）。
|
||||
- Idiomorphが存在しない場合、**ページをリロード**します（標準のライブリロード）。
|
||||
|
||||
## 設定
|
||||
|
||||
ホットリロードを有効にするには、Mercureを有効にしてから、`Caddyfile`の`php_server`ディレクティブに`hot_reload`サブディレクティブを追加します。
|
||||
|
||||
> [!WARNING]
|
||||
>
|
||||
> この機能は**開発環境のみ**を対象としています。
|
||||
> `hot_reload`を本番環境で有効にしないでください。この機能は安全ではなく（機密性の高い内部詳細を公開します）、アプリケーションの速度を低下させます。
|
||||
>
|
||||
```caddyfile
|
||||
localhost
|
||||
|
||||
mercure {
|
||||
anonymous
|
||||
}
|
||||
|
||||
root public/
|
||||
php_server {
|
||||
hot_reload
|
||||
}
|
||||
```
|
||||
|
||||
デフォルトでは、FrankenPHPは現在の作業ディレクトリ内の以下のグロブパターンに一致するすべてのファイルを監視します: `./**/*.{css,env,gif,htm,html,jpg,jpeg,js,mjs,php,png,svg,twig,webp,xml,yaml,yml}`
|
||||
|
||||
グロブ構文を使用して、監視するファイルを明示的に設定することも可能です。
|
||||
|
||||
```caddyfile
|
||||
localhost
|
||||
|
||||
mercure {
|
||||
anonymous
|
||||
}
|
||||
|
||||
root public/
|
||||
php_server {
|
||||
hot_reload src/**/*{.php,.js} config/**/*.yaml
|
||||
}
|
||||
```
|
||||
|
||||
使用するMercureトピック、および監視するディレクトリまたはファイルを指定するには、`hot_reload`のロングフォームを使用します。
|
||||
|
||||
```caddyfile
|
||||
localhost
|
||||
|
||||
mercure {
|
||||
anonymous
|
||||
}
|
||||
|
||||
root public/
|
||||
php_server {
|
||||
hot_reload {
|
||||
topic hot-reload-topic
|
||||
watch src/**/*.php
|
||||
watch assets/**/*.{ts,json}
|
||||
watch templates/
|
||||
watch public/css/
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## クライアントサイドの統合
|
||||
|
||||
サーバーは変更を検出しますが、ブラウザはこれらのイベントを購読してページを更新する必要があります。
|
||||
FrankenPHPは、ファイル変更を購読するために使用するMercure HubのURLを、`$_SERVER['FRANKENPHP_HOT_RELOAD']`環境変数を通じて公開します。
|
||||
|
||||
クライアントサイドのロジックを処理するための便利なJavaScriptライブラリ、[frankenphp-hot-reload](https://www.npmjs.com/package/frankenphp-hot-reload)も利用可能です。
|
||||
これを使用するには、メインレイアウトに以下を追加します。
|
||||
|
||||
```php
|
||||
<!DOCTYPE html>
|
||||
<title>FrankenPHP Hot Reload</title>
|
||||
<?php if (isset($_SERVER['FRANKENPHP_HOT_RELOAD'])): ?>
|
||||
<meta name="frankenphp-hot-reload:url" content="<?=$_SERVER['FRANKENPHP_HOT_RELOAD']?>">
|
||||
<script src="https://cdn.jsdelivr.net/npm/idiomorph"></script>
|
||||
<script src="https://cdn.jsdelivr.net/npm/frankenphp-hot-reload/+esm" type="module"></script>
|
||||
<?php endif ?>
|
||||
```
|
||||
|
||||
このライブラリは自動的にMercureハブを購読し、ファイル変更が検出されるとバックグラウンドで現在のURLをフェッチし、DOMをモーフィングします。
|
||||
[npm](https://www.npmjs.com/package/frankenphp-hot-reload)パッケージとして、また[GitHub](https://github.com/dunglas/frankenphp-hot-reload)で利用できます。
|
||||
|
||||
または、`EventSource`ネイティブJavaScriptクラスを使用してMercureハブに直接購読することで、独自のクライアントサイドロジックを実装することもできます。
|
||||
|
||||
### 既存のDOMノードを保持する
|
||||
|
||||
まれに、[Symfonyのウェブデバッグツールバーなどの開発ツール](https://github.com/symfony/symfony/pull/62970)を使用している場合など、特定のDOMノードを保持したいことがあります。
|
||||
そのためには、関連するHTML要素に`data-frankenphp-hot-reload-preserve`属性を追加します。
|
||||
|
||||
```html
|
||||
<div data-frankenphp-hot-reload-preserve><!-- My debug bar --></div>
|
||||
```
|
||||
|
||||
## ワーカーモード
|
||||
|
||||
アプリケーションを[ワーカーモード](https://frankenphp.dev/docs/worker/)で実行している場合、アプリケーションスクリプトはメモリに常駐します。
|
||||
これは、ブラウザがリロードされても、PHPコードの変更がすぐに反映されないことを意味します。
|
||||
|
||||
最高の開発者エクスペリエンスのためには、`hot_reload`を[ワーカーディレクティブ内の`watch`サブディレクティブ](config.md#watching-for-file-changes)と組み合わせるべきです。
|
||||
|
||||
- `hot_reload`: ファイルが変更されたときに**ブラウザ**をリフレッシュします
|
||||
- `worker.watch`: ファイルが変更されたときにワーカーを再起動します
|
||||
|
||||
```caddy
|
||||
localhost
|
||||
|
||||
mercure {
|
||||
anonymous
|
||||
}
|
||||
|
||||
root public/
|
||||
php_server {
|
||||
hot_reload
|
||||
worker {
|
||||
file /path/to/my_worker.php
|
||||
watch
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## 仕組み
|
||||
|
||||
1. **監視**: FrankenPHPは、内部で[`e-dant/watcher`ライブラリ](https://github.com/e-dant/watcher)を使用してファイルシステムの変更を監視します（私たちはGoバインディングに貢献しました）。
|
||||
2. **再起動 (ワーカーモード)**: ワーカー設定で`watch`が有効になっている場合、新しいコードをロードするためにPHPワーカーが再起動されます。
|
||||
3. **プッシュ**: 変更されたファイルのリストを含むJSONペイロードが、組み込みの[Mercureハブ](https://mercure.rocks)に送信されます。
|
||||
4. **受信**: JavaScriptライブラリを介してリッスンしているブラウザがMercureイベントを受信します。
|
||||
5. **更新**:
|
||||
|
||||
- **Idiomorph**が検出された場合、更新されたコンテンツをフェッチし、現在のHTMLを新しい状態に合わせてモーフィングし、状態を失うことなく即座に変更を適用します。
|
||||
- それ以外の場合、`window.location.reload()`が呼び出されてページがリフレッシュされます。
|
||||
147
docs/pt-br/hot-reload.md
Normal file
147
docs/pt-br/hot-reload.md
Normal file
@@ -0,0 +1,147 @@
|
||||
# Recarregamento Instantâneo
|
||||
|
||||
FrankenPHP inclui um recurso de **recarregamento instantâneo** embutido, projetado para melhorar drasticamente a experiência do desenvolvedor.
|
||||
|
||||
|
||||
|
||||
Este recurso oferece um fluxo de trabalho semelhante ao **Hot Module Replacement (HMR)** em ferramentas modernas de JavaScript, como Vite ou webpack.
|
||||
Em vez de atualizar o navegador manualmente após cada alteração de arquivo (código PHP, templates, arquivos JavaScript e CSS...), o FrankenPHP atualiza o conteúdo da página em tempo real.
|
||||
|
||||
O Recarregamento Instantâneo funciona nativamente com WordPress, Laravel, Symfony e qualquer outra aplicação ou framework PHP.
|
||||
|
||||
Quando ativado, o FrankenPHP monitora seu diretório de trabalho atual em busca de alterações no sistema de arquivos. Quando um arquivo é modificado, ele envia uma atualização [Mercure](mercure.md) para o navegador.
|
||||
|
||||
Dependendo da sua configuração, o navegador irá:
|
||||
|
||||
- **Transformar o DOM** (preservando a posição de rolagem e o estado dos inputs) se o [Idiomorph](https://github.com/bigskysoftware/idiomorph) estiver carregado.
|
||||
- **Recarregar a página** (recarregamento ao vivo padrão) se o Idiomorph não estiver presente.
|
||||
|
||||
## Configuração
|
||||
|
||||
Para ativar o recarregamento instantâneo, habilite o Mercure e, em seguida, adicione a subdiretiva `hot_reload` à diretiva `php_server` no seu `Caddyfile`.
|
||||
|
||||
> [!WARNING]
|
||||
>
|
||||
> Este recurso é destinado **apenas para ambientes de desenvolvimento**.
|
||||
> Não ative `hot_reload` em produção, pois este recurso não é seguro (expõe detalhes internos sensíveis) e desacelera a aplicação.
|
||||
>
|
||||
```caddyfile
|
||||
localhost
|
||||
|
||||
mercure {
|
||||
anonymous
|
||||
}
|
||||
|
||||
root public/
|
||||
php_server {
|
||||
hot_reload
|
||||
}
|
||||
```
|
||||
|
||||
Por padrão, o FrankenPHP monitorará todos os arquivos no diretório de trabalho atual que correspondem a este padrão glob: `./**/*.{css,env,gif,htm,html,jpg,jpeg,js,mjs,php,png,svg,twig,webp,xml,yaml,yml}`
|
||||
|
||||
É possível definir os arquivos a serem monitorados usando a sintaxe glob explicitamente:
|
||||
|
||||
```caddyfile
|
||||
localhost
|
||||
|
||||
mercure {
|
||||
anonymous
|
||||
}
|
||||
|
||||
root public/
|
||||
php_server {
|
||||
hot_reload src/**/*{.php,.js} config/**/*.yaml
|
||||
}
|
||||
```
|
||||
|
||||
Use a forma longa de `hot_reload` para especificar o tópico Mercure a ser usado, bem como quais diretórios ou arquivos monitorar:
|
||||
|
||||
```caddyfile
|
||||
localhost
|
||||
|
||||
mercure {
|
||||
anonymous
|
||||
}
|
||||
|
||||
root public/
|
||||
php_server {
|
||||
hot_reload {
|
||||
topic hot-reload-topic
|
||||
watch src/**/*.php
|
||||
watch assets/**/*.{ts,json}
|
||||
watch templates/
|
||||
watch public/css/
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Integração no Lado do Cliente
|
||||
|
||||
Enquanto o servidor detecta as alterações, o navegador precisa se inscrever nesses eventos para atualizar a página.
|
||||
O FrankenPHP expõe a URL do Hub Mercure a ser usada para se inscrever em alterações de arquivo através da variável de ambiente `$_SERVER['FRANKENPHP_HOT_RELOAD']`.
|
||||
|
||||
Uma biblioteca JavaScript de conveniência, [frankenphp-hot-reload](https://www.npmjs.com/package/frankenphp-hot-reload), também está disponível para lidar com a lógica do lado do cliente.
|
||||
Para usá-la, adicione o seguinte ao seu layout principal:
|
||||
|
||||
```php
|
||||
<!DOCTYPE html>
|
||||
<title>FrankenPHP Hot Reload</title>
|
||||
<?php if (isset($_SERVER['FRANKENPHP_HOT_RELOAD'])): ?>
|
||||
<meta name="frankenphp-hot-reload:url" content="<?=$_SERVER['FRANKENPHP_HOT_RELOAD']?>">
|
||||
<script src="https://cdn.jsdelivr.net/npm/idiomorph"></script>
|
||||
<script src="https://cdn.jsdelivr.net/npm/frankenphp-hot-reload/+esm" type="module"></script>
|
||||
<?php endif ?>
|
||||
```
|
||||
|
||||
A biblioteca se inscreverá automaticamente no hub Mercure, buscará a URL atual em segundo plano quando uma alteração de arquivo for detectada e transformará o DOM.
|
||||
Está disponível como um pacote [npm](https://www.npmjs.com/package/frankenphp-hot-reload) e no [GitHub](https://github.com/dunglas/frankenphp-hot-reload).
|
||||
|
||||
Alternativamente, você pode implementar sua própria lógica do lado do cliente inscrevendo-se diretamente no hub Mercure usando a classe nativa `EventSource` do JavaScript.
|
||||
|
||||
### Preservando Nós DOM Existentes
|
||||
|
||||
Em casos raros, como ao usar ferramentas de desenvolvimento [como a barra de depuração da web do Symfony](https://github.com/symfony/symfony/pull/62970), você pode querer preservar nós DOM específicos.
|
||||
Para fazer isso, adicione o atributo `data-frankenphp-hot-reload-preserve` ao elemento HTML relevante:
|
||||
|
||||
```html
|
||||
<div data-frankenphp-hot-reload-preserve><!-- My debug bar --></div>
|
||||
```
|
||||
|
||||
## Modo Worker
|
||||
|
||||
Se você estiver executando sua aplicação em [Modo Worker](https://frankenphp.dev/docs/worker/), seu script de aplicação permanece na memória.
|
||||
Isso significa que as alterações no seu código PHP não serão refletidas imediatamente, mesmo que o navegador recarregue.
|
||||
|
||||
Para a melhor experiência do desenvolvedor, você deve combinar `hot_reload` com [a subdiretiva `watch` na diretiva `worker`](config.md#observando-alteracoes-de-arquivos).
|
||||
|
||||
- `hot_reload`: atualiza o **navegador** quando os arquivos são alterados
|
||||
- `worker.watch`: reinicia o worker quando os arquivos são alterados
|
||||
|
||||
```caddy
|
||||
localhost
|
||||
|
||||
mercure {
|
||||
anonymous
|
||||
}
|
||||
|
||||
root public/
|
||||
php_server {
|
||||
hot_reload
|
||||
worker {
|
||||
file /path/to/my_worker.php
|
||||
watch
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Como Funciona
|
||||
|
||||
1. **Monitoramento**: O FrankenPHP monitora o sistema de arquivos em busca de modificações usando a biblioteca [`e-dant/watcher`](https://github.com/e-dant/watcher) por baixo dos panos (contribuímos com o binding Go).
|
||||
2. **Reiniciar (Modo Worker)**: se `watch` estiver habilitado na configuração do worker, o worker PHP é reiniciado para carregar o novo código.
|
||||
3. **Envio**: Um payload JSON contendo a lista de arquivos alterados é enviado para o [hub Mercure](https://mercure.rocks) embutido.
|
||||
4. **Recebimento**: O navegador, ouvindo através da biblioteca JavaScript, recebe o evento Mercure.
|
||||
5. **Atualização**:
|
||||
|
||||
- Se o **Idiomorph** for detectado, ele busca o conteúdo atualizado e transforma o HTML atual para corresponder ao novo estado, aplicando as alterações instantaneamente sem perder o estado.
|
||||
- Caso contrário, `window.location.reload()` é chamado para recarregar a página.
|
||||
149
docs/ru/hot-reload.md
Normal file
149
docs/ru/hot-reload.md
Normal file
@@ -0,0 +1,149 @@
|
||||
# Горячая перезагрузка
|
||||
|
||||
FrankenPHP включает встроенную функцию **горячей перезагрузки**, разработанную для значительного улучшения опыта разработчика.
|
||||
|
||||
|
||||
|
||||
Эта функция обеспечивает рабочий процесс, похожий на **Hot Module Replacement (HMR)** в современных инструментах JavaScript, таких как Vite или webpack.
|
||||
Вместо ручного обновления браузера после каждого изменения файла (PHP-код, шаблоны, файлы JavaScript и CSS...), FrankenPHP обновляет содержимое страницы в реальном времени.
|
||||
|
||||
Горячая перезагрузка нативно работает с WordPress, Laravel, Symfony и любым другим PHP-приложением или фреймворком.
|
||||
|
||||
Когда функция включена, FrankenPHP отслеживает изменения файловой системы в вашем текущем рабочем каталоге.
|
||||
При изменении файла он отправляет обновление [Mercure](mercure.md) в браузер.
|
||||
|
||||
В зависимости от вашей настройки, браузер будет либо:
|
||||
|
||||
- **Морфировать DOM** (сохраняя позицию прокрутки и состояние ввода), если загружен [Idiomorph](https://github.com/bigskysoftware/idiomorph).
|
||||
- **Перезагружать страницу** (стандартная живая перезагрузка), если Idiomorph отсутствует.
|
||||
|
||||
## Конфигурация
|
||||
|
||||
Чтобы включить горячую перезагрузку, включите Mercure, затем добавьте поддирективу `hot_reload` в директиву `php_server` в вашем `Caddyfile`.
|
||||
|
||||
> [!WARNING]
|
||||
>
|
||||
> Эта функция предназначена **только для сред разработки**.
|
||||
> Не включайте `hot_reload` в продакшене, так как эта функция небезопасна (раскрывает конфиденциальные внутренние детали) и замедляет работу приложения.
|
||||
>
|
||||
```caddyfile
|
||||
localhost
|
||||
|
||||
mercure {
|
||||
anonymous
|
||||
}
|
||||
|
||||
root public/
|
||||
php_server {
|
||||
hot_reload
|
||||
}
|
||||
```
|
||||
|
||||
По умолчанию FrankenPHP будет отслеживать все файлы в текущем рабочем каталоге, соответствующие следующему глобальному шаблону: `./**/*.{css,env,gif,htm,html,jpg,jpeg,js,mjs,php,png,svg,twig,webp,xml,yaml,yml}`
|
||||
|
||||
Можно явно задать файлы для отслеживания, используя синтаксис глобов:
|
||||
|
||||
```caddyfile
|
||||
localhost
|
||||
|
||||
mercure {
|
||||
anonymous
|
||||
}
|
||||
|
||||
root public/
|
||||
php_server {
|
||||
hot_reload src/**/*{.php,.js} config/**/*.yaml
|
||||
}
|
||||
```
|
||||
|
||||
Используйте полную форму `hot_reload`, чтобы указать используемый топик Mercure, а также каталоги или файлы для отслеживания:
|
||||
|
||||
```caddyfile
|
||||
localhost
|
||||
|
||||
mercure {
|
||||
anonymous
|
||||
}
|
||||
|
||||
root public/
|
||||
php_server {
|
||||
hot_reload {
|
||||
topic hot-reload-topic
|
||||
watch src/**/*.php
|
||||
watch assets/**/*.{ts,json}
|
||||
watch templates/
|
||||
watch public/css/
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Интеграция на стороне клиента
|
||||
|
||||
В то время как сервер обнаруживает изменения, браузер должен подписаться на эти события, чтобы обновить страницу.
|
||||
FrankenPHP предоставляет URL-адрес Mercure Hub для подписки на изменения файлов через переменную окружения `$_SERVER['FRANKENPHP_HOT_RELOAD']`.
|
||||
|
||||
Удобная библиотека JavaScript, [frankenphp-hot-reload](https://www.npmjs.com/package/frankenphp-hot-reload), также доступна для обработки логики на стороне клиента.
|
||||
Чтобы использовать ее, добавьте следующее в ваш основной макет:
|
||||
|
||||
```php
|
||||
<!DOCTYPE html>
|
||||
<title>FrankenPHP Hot Reload</title>
|
||||
<?php if (isset($_SERVER['FRANKENPHP_HOT_RELOAD'])): ?>
|
||||
<meta name="frankenphp-hot-reload:url" content="<?=$_SERVER['FRANKENPHP_HOT_RELOAD']?>">
|
||||
<script src="https://cdn.jsdelivr.net/npm/idiomorph"></script>
|
||||
<script src="https://cdn.jsdelivr.net/npm/frankenphp-hot-reload/+esm" type="module"></script>
|
||||
<?php endif ?>
|
||||
```
|
||||
|
||||
Библиотека автоматически подпишется на хаб Mercure, получит текущий URL-адрес в фоновом режиме при обнаружении изменения файла и морфирует DOM.
|
||||
Она доступна как [npm](https://www.npmjs.com/package/frankenphp-hot-reload) пакет и на [GitHub](https://github.com/dunglas/frankenphp-hot-reload).
|
||||
|
||||
В качестве альтернативы вы можете реализовать свою собственную клиентскую логику, подписавшись непосредственно на хаб Mercure с помощью нативного JavaScript-класса `EventSource`.
|
||||
|
||||
### Сохранение существующих узлов DOM
|
||||
|
||||
В редких случаях, например, при использовании инструментов разработки [таких как панель отладки Symfony web debug toolbar](https://github.com/symfony/symfony/pull/62970),
|
||||
вы можете захотеть сохранить определенные узлы DOM.
|
||||
Для этого добавьте атрибут `data-frankenphp-hot-reload-preserve` к соответствующему HTML-элементу:
|
||||
|
||||
```html
|
||||
<div data-frankenphp-hot-reload-preserve><!-- Моя панель отладки --></div>
|
||||
```
|
||||
|
||||
## Режим Worker
|
||||
|
||||
Если вы запускаете свое приложение в [режиме Worker](https://frankenphp.dev/docs/worker/), скрипт вашего приложения остается в памяти.
|
||||
Это означает, что изменения в вашем PHP-коде не будут отражены немедленно, даже если браузер перезагрузится.
|
||||
|
||||
Для лучшего опыта разработчика вы должны объединить `hot_reload` с [поддирективой `watch` в директиве `worker`](config.md#watching-for-file-changes).
|
||||
|
||||
- `hot_reload`: обновляет **браузер** при изменении файлов
|
||||
- `worker.watch`: перезапускает воркер при изменении файлов
|
||||
|
||||
```caddy
|
||||
localhost
|
||||
|
||||
mercure {
|
||||
anonymous
|
||||
}
|
||||
|
||||
root public/
|
||||
php_server {
|
||||
hot_reload
|
||||
worker {
|
||||
file /path/to/my_worker.php
|
||||
watch
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Как это работает
|
||||
|
||||
1. **Отслеживание**: FrankenPHP отслеживает изменения файловой системы, используя библиотеку [`e-dant/watcher`](https://github.com/e-dant/watcher) (мы внесли вклад в Go-биндинг).
|
||||
2. **Перезапуск (Режим Worker)**: если `watch` включен в конфигурации воркера, PHP-воркер перезапускается для загрузки нового кода.
|
||||
3. **Отправка**: JSON-полезная нагрузка, содержащая список измененных файлов, отправляется во встроенный [Mercure hub](https://mercure.rocks).
|
||||
4. **Получение**: Браузер, прослушивающий через JavaScript-библиотеку, получает событие Mercure.
|
||||
5. **Обновление**:
|
||||
|
||||
- Если обнаружен **Idiomorph**, он получает обновленное содержимое и морфирует текущий HTML, чтобы соответствовать новому состоянию, применяя изменения мгновенно без потери состояния.
|
||||
- В противном случае вызывается `window.location.reload()` для обновления страницы.
|
||||
150
docs/tr/hot-reload.md
Normal file
150
docs/tr/hot-reload.md
Normal file
@@ -0,0 +1,150 @@
|
||||
# Sıcak Yeniden Yükleme
|
||||
|
||||
FrankenPHP, geliştirici deneyimini büyük ölçüde iyileştirmek için tasarlanmış yerleşik bir **sıcak yeniden yükleme** özelliğine sahiptir.
|
||||
|
||||
|
||||
|
||||
Bu özellik, Vite veya webpack gibi modern JavaScript araçlarındaki **Sıcak Modül Değişimi (HMR)** ile benzer bir iş akışı sunar.
|
||||
Her dosya değişikliğinden (PHP kodu, şablonlar, JavaScript ve CSS dosyaları...) sonra tarayıcıyı manuel olarak yenilemek yerine,
|
||||
FrankenPHP sayfa içeriğini gerçek zamanlı olarak günceller.
|
||||
|
||||
Sıcak Yeniden Yükleme, WordPress, Laravel, Symfony ve diğer tüm PHP uygulamaları veya framework'leri ile yerel olarak çalışır.
|
||||
|
||||
Etkinleştirildiğinde, FrankenPHP dosya sistemi değişiklikleri için mevcut çalışma dizininizi izler.
|
||||
Bir dosya değiştirildiğinde, tarayıcıya bir [Mercure](mercure.md) güncellemesi gönderir.
|
||||
|
||||
Kurulumunuza bağlı olarak, tarayıcı ya:
|
||||
|
||||
- [Idiomorph](https://github.com/bigskysoftware/idiomorph) yüklüyse **DOM'u dönüştürür** (kaydırma konumunu ve girdi durumunu koruyarak).
|
||||
- Idiomorph mevcut değilse **sayfayı yeniden yükler** (standart canlı yeniden yükleme).
|
||||
|
||||
## Yapılandırma
|
||||
|
||||
Sıcak yeniden yüklemeyi etkinleştirmek için Mercure'ü etkinleştirin, ardından `Caddyfile` dosyanızdaki `php_server` yönergesine `hot_reload` alt yönergesini ekleyin.
|
||||
|
||||
> [!WARNING]
|
||||
>
|
||||
> Bu özellik **yalnızca geliştirme ortamları** içindir.
|
||||
> `hot_reload`'u üretimde etkinleştirmeyin, zira bu özellik güvenli değildir (hassas dahili ayrıntıları açığa çıkarır) ve uygulamanın yavaşlamasına neden olur.
|
||||
>
|
||||
```caddyfile
|
||||
localhost
|
||||
|
||||
mercure {
|
||||
anonymous
|
||||
}
|
||||
|
||||
root public/
|
||||
php_server {
|
||||
hot_reload
|
||||
}
|
||||
```
|
||||
|
||||
Varsayılan olarak, FrankenPHP mevcut çalışma dizinindeki şu glob desenine uyan tüm dosyaları izleyecektir: `./**/*.{css,env,gif,htm,html,jpg,jpeg,js,mjs,php,png,svg,twig,webp,xml,yaml,yml}`
|
||||
|
||||
İzlenecek dosyaları glob sözdizimi kullanarak açıkça ayarlamak mümkündür:
|
||||
|
||||
```caddyfile
|
||||
localhost
|
||||
|
||||
mercure {
|
||||
anonymous
|
||||
}
|
||||
|
||||
root public/
|
||||
php_server {
|
||||
hot_reload src/**/*{.php,.js} config/**/*.yaml
|
||||
}
|
||||
```
|
||||
|
||||
Kullanılacak Mercure konusunu ve izlenecek dizin veya dosyaları belirtmek için `hot_reload`'un uzun biçimini kullanın:
|
||||
|
||||
```caddyfile
|
||||
localhost
|
||||
|
||||
mercure {
|
||||
anonymous
|
||||
}
|
||||
|
||||
root public/
|
||||
php_server {
|
||||
hot_reload {
|
||||
topic hot-reload-topic
|
||||
watch src/**/*.php
|
||||
watch assets/**/*.{ts,json}
|
||||
watch templates/
|
||||
watch public/css/
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## İstemci Tarafı Entegrasyonu
|
||||
|
||||
Sunucu değişiklikleri algılarken, tarayıcının sayfayı güncellemek için bu olaylara abone olması gerekir.
|
||||
FrankenPHP, dosya değişikliklerine abone olmak için kullanılacak Mercure Hub URL'sini `$_SERVER['FRANKENPHP_HOT_RELOAD']` ortam değişkeni aracılığıyla gösterir.
|
||||
|
||||
İstemci tarafı mantığını yönetmek için kullanışlı bir JavaScript kütüphanesi olan [frankenphp-hot-reload](https://www.npmjs.com/package/frankenphp-hot-reload) da mevcuttur.
|
||||
Kullanmak için ana düzeninize aşağıdakileri ekleyin:
|
||||
|
||||
```php
|
||||
<!DOCTYPE html>
|
||||
<title>FrankenPHP Hot Reload</title>
|
||||
<?php if (isset($_SERVER['FRANKENPHP_HOT_RELOAD'])): ?>
|
||||
<meta name="frankenphp-hot-reload:url" content="<?=$_SERVER['FRANKENPHP_HOT_RELOAD']?>">
|
||||
<script src="https://cdn.jsdelivr.net/npm/idiomorph"></script>
|
||||
<script src="https://cdn.jsdelivr.net/npm/frankenphp-hot-reload/+esm" type="module"></script>
|
||||
<?php endif ?>
|
||||
```
|
||||
|
||||
Kütüphane otomatik olarak Mercure hub'ına abone olacak, bir dosya değişikliği algılandığında arka planda mevcut URL'yi getirecek ve DOM'u dönüştürecektir.
|
||||
Bir [npm](https://www.npmjs.com/package/frankenphp-hot-reload) paketi olarak ve [GitHub](https://github.com/dunglas/frankenphp-hot-reload) üzerinden edinilebilir.
|
||||
|
||||
Alternatif olarak, `EventSource` yerel JavaScript sınıfını kullanarak doğrudan Mercure hub'ına abone olarak kendi istemci tarafı mantığınızı uygulayabilirsiniz.
|
||||
|
||||
### Mevcut DOM Düğümlerini Korumak
|
||||
|
||||
Nadir durumlarda, [Symfony web hata ayıklama araç çubuğu gibi](https://github.com/symfony/symfony/pull/62970) geliştirme araçları kullanırken olduğu gibi,
|
||||
belirli DOM düğümlerini korumak isteyebilirsiniz.
|
||||
Bunu yapmak için, ilgili HTML öğesine `data-frankenphp-hot-reload-preserve` özniteliğini ekleyin:
|
||||
|
||||
```html
|
||||
<div data-frankenphp-hot-reload-preserve><!-- Hata ayıklama çubuğum --></div>
|
||||
```
|
||||
|
||||
## Çalışan Modu
|
||||
|
||||
Uygulamanızı [Çalışan Modunda](https://frankenphp.dev/docs/worker/) çalıştırıyorsanız, uygulama betiğiniz bellekte kalır.
|
||||
Bu, tarayıcı yeniden yüklense bile PHP kodunuzdaki değişikliklerin hemen yansımayacağı anlamına gelir.
|
||||
|
||||
En iyi geliştirici deneyimi için `hot_reload`'u [worker yönergesindeki `watch` alt yönergesiyle](config.md#watching-for-file-changes) birleştirmelisiniz.
|
||||
|
||||
- `hot_reload`: dosyalar değiştiğinde **tarayıcıyı** yeniler
|
||||
- `worker.watch`: dosyalar değiştiğinde çalışanı yeniden başlatır
|
||||
|
||||
```caddy
|
||||
localhost
|
||||
|
||||
mercure {
|
||||
anonymous
|
||||
}
|
||||
|
||||
root public/
|
||||
php_server {
|
||||
hot_reload
|
||||
worker {
|
||||
file /path/to/my_worker.php
|
||||
watch
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Nasıl Çalışır
|
||||
|
||||
1. **İzleme**: FrankenPHP, arka planda [`e-dant/watcher` kütüphanesini](https://github.com/e-dant/watcher) kullanarak (Go bağlayıcısını biz geliştirdik) dosya sistemindeki değişiklikleri izler.
|
||||
2. **Yeniden Başlatma (Çalışan Modu)**: Çalışan yapılandırmasında `watch` etkinse, yeni kodu yüklemek için PHP çalışanı yeniden başlatılır.
|
||||
3. **Gönderme**: Değiştirilen dosyaların listesini içeren bir JSON yükü, yerleşik [Mercure hub'ına](https://mercure.rocks) gönderilir.
|
||||
4. **Alma**: JavaScript kütüphanesi aracılığıyla dinleyen tarayıcı, Mercure olayını alır.
|
||||
5. **Güncelleme**:
|
||||
|
||||
- **Idiomorph** algılanırsa, güncellenmiş içeriği getirir ve mevcut HTML'i yeni duruma uydurmak için dönüştürerek, durum kaybetmeden değişiklikleri anında uygular.
|
||||
- Aksi takdirde, sayfayı yenilemek için `window.location.reload()` çağrılır.
|
||||
Reference in New Issue
Block a user