Laragear/Poke

# Poke [](https://packagist.org/packages/laragear/poke) [](https://github.com/Laragear/Poke/actions) [](https://codecov.io/gh/Laragear/Poke) [](https://qlty.sh/gh/Laragear/projects/Poke) [](https://sonarcloud.io/dashboard?id=Laragear_Poke) [](https://laravel.com/docs/13.x/octane#introduction) 保持您的表单活跃，通过轻轻“戳（poke）”您的 Laravel 应用来避免 `TokenMismatchException`。 ## 环境要求 * PHP 8.3 或更高版本 * Laravel 12 或更高版本 ## 安装 使用 Composer 将此包引入您的项目： ``` composer require laragear/poke ``` ## 它是如何工作的？ 此包会以给定的时间间隔通过 HTTP `HEAD` 请求访问您的应用的 `/poke` 路由。作为回报，当您的应用刷新会话生命周期时，它会返回一个 `HTTP 204` 状态码，这是一个无正文的 OK 响应。 这总共**仅发送约 0.8 KB 的数据！** ### CSRF token 过期时自动重新加载 Poke 脚本会根据最后一次成功的“戳”请求检测 CSRF 会话 token 是否已过期，如果存在网络连接，则强制重新加载页面。 这是通过检测[浏览器或标签页何时变为活动状态](https://developer.mozilla.org/en-US/docs/Web/API/Page_Visibility_API)，或[设备用户何时恢复在线](https://developer.mozilla.org/en-US/docs/Web/API/NavigatorOnLine/onLine)来完成的。 这在用户笔记本电脑进入睡眠状态或手机失去信号的情况下非常有用。因为会话可能会在这些时刻过期，所以当浏览器唤醒或手机恢复在线时，页面会重新加载以获取新的 CSRF token。 ## 使用方法 在您的应用中有三种开启 Poke 的方式。 * `auto`（简单的免手动默认模式） * `middleware` * `blade`（性能最佳） 您可以使用环境文件更改默认模式： ``` POKE_MODE=auto ``` ### `auto` 只需安装此包，*看着它运行即可*。这将在 [the `web` group](https://laravel.com/docs/middleware#middleware-groups) 中追加一个中间件，该中间件会检查您所有响应的内容，其中： * 请求接受 HTML，并且 * 存在包含 `csrf` token 的输入框。 如果有任何匹配，它将在 `` 标签之前注入负责保持表单活跃的 Poke 脚本。 此模式不会在错误响应或重定向中注入脚本。 ### `middleware` 此模式不会将中间件推送到 `web` 组。相反，它允许您仅在您决定的路由中使用 `poke` 中间件。 ``` use Illuminate\Support\Facades\Route; use App\Http\Controllers\Auth\RegisterController; Route::get('register', RegisterController::class)->middleware('poke'); ``` 如果存在带有 CSRF token 的输入框，这会将脚本注入到路由响应中。您也可以将其应用到 [route group](https://laravel.com/docs/routing#route-groups)。 您可能希望使用 `force` 选项强制在 `` 标签末尾注入脚本，而无论是否存在 CSRF token 输入框。当您希望在视图加载后动态加载表单或构建 SPA 时，这可能很方便。 ``` use Illuminate\Support\Facades\Route; use App\Http\Controllers\StatusController; Route::get('status', StatusController::class)->middleware('poke:force'); ``` 与 [`auto` 模式](#auto)一样，此模式不会在错误或重定向时注入脚本。 ### `blade` `blade` 模式禁用中间件注入，因此您可以自由使用 `` 组件在视图的任何位置注入脚本，最好是在 `` 结束标签之前。 ```

Try to Login:

@csrf Log me in!

``` 如果您有大型响应（如博客文章、文章或图库），这可能很有用，因为框架无需花费资源检查响应，而只需渲染组件。 ## Livewire Trait 如果您正在使用 Livewire，您可以在组件中使用 `Laragear\Poke\Livewire\InteractsWithPoke` trait 来向您的页面_分发_一个事件。唯一的要求是 [use the Blade](#blade) 模式，或添加带有 `force` 属性的 [force](#blade)。 ``` ``` 在您的组件中，如果使用了该 trait，`poke:renew` 将被分发到前端，从而在组件渲染时更新 poke。 ``` use Laragear\Poke\Livewire\InteractsWithPoke; use Livewire\Component as LivewireComponent; class MyCustomForm extends LivewireComponent { use InteractsWithPoke; // ... } ``` ## Filament PHP 如果您正在使用 Filament PHP，则无需担心。当您渲染带有表单的 Resource，或实现 `HasForms` 合约的页面时，脚本将自动注入到 body 结束标签之前。 如果您使用的是自定义 Page，则需要使用 [Livewire Trait](#livewire-trait)。 ``` use Filament\Pages\Page; use Laragear\Poke\Livewire\InteractsWithPoke; class Onboarding extends Page { use InteractsWithPoke; // ... } ``` ## 配置 为了进行微调，您可以发布 `poke.php` 配置文件。 ``` php artisan vendor:publish --provider="Laragear\Poke\PokeServiceProvider" --tag="config" ``` 让我们检查一下配置数组： ``` return [ 'mode' => env('POKE_MODE', 'auto'), 'times' => 4, 'poking' => [ 'route' => 'poke', 'name' => 'poke', 'domain' => null, 'middleware' => 'web', ] ]; ``` ### Times (间隔) 相对于全局会话生命周期，执行“戳”操作的次数。次数越多，“戳”的间隔越短。默认值 `4` 应该适用于任何正常的应用程序。 例如，如果我们的会话生命周期是默认的 120 分钟： - 3 次将每 40 分钟戳一次应用程序， - 4 次将每 30 分钟戳一次应用程序， - 5 次将每 24 分钟戳一次应用程序， - 6 次将每 20 分钟戳一次应用程序，依此类推... 换句话说，即 `会话生命周期 / 次数 = 戳的间隔`。 - 🔺 如果您希望用户在您的网站上闲置几分钟甚至几小时，请提高间隔次数。 - 🔻 如果您预期用户活动频繁，请降低间隔次数。 ### Poking 这是接收 Poke 脚本请求的“戳”路由的设置数组。 ``` return [ 'poking' => [ 'route' => 'poke', 'name' => 'poke', 'domain' => null, 'middleware' => ['web'], ] ]; ``` #### 路由 将用于接收“戳”请求的路由（相对于应用程序的根 URL）。 ``` return [ 'poking' => [ 'route' => '/dont-sleep' ], ]; ``` #### 名称 路由名称，用于在您的应用中查找 poke 路由（无论出于何种原因）。 ``` return [ 'poking' => [ 'name' => 'my-custom-poking-route' ], ]; ``` #### 域名 Poke 路由在所有域上均可用。设置给定的域会将路由范围限定在该域内。 如果您正在使用一个域或域模式，将 Poke 路由置于某个特定域下可能会很方便。一个典型的例子是让“戳”功能在 `http://user.myapp.com/poke` 上可用，但不在 `http://api.myapp.com/poke` 上可用。 ``` return [ 'poking' => [ 'domain' => '{user}.myapp.com' ], ]; ``` #### Middleware 默认的 Poke 路由使用 [the `web` middleware group](https://laravel.com/docs/middleware#middleware-groups) 才能正常工作，因为该组处理会话、cookie 和 CSRF token。 如果需要，您可以在此处添加自己的中间件。 ``` return [ 'poking' => [ 'middleware' => ['web', 'validates-ip', 'my-custom-middleware'] ], ]; ``` 如果您愿意，也可以使用“极简”中间件，但如果您不知道自己在做什么，这可能会产生问题。 ``` return [ 'poking' => [ 'middleware' => [ \Illuminate\Cookie\Middleware\EncryptCookies::class, \Illuminate\Session\Middleware\StartSession::class, \App\Http\Middleware\VerifyCsrfToken::class, ], ] ] ``` ## 脚本视图 Poke 始终将脚本作为 [Blade component](https://laravel.com/docs/blade#components) 注入。 您可以通过在 `views` 标签下发布来覆盖脚本： ``` php artisan vendor:publish --provider="Laragear\Poke\PokeServiceProvider" --tag="views" ``` 有些人可能希望更改脚本以使用自定义 Javascript HTTP 库、压缩响应、使其兼容旧版浏览器，甚至在 CSRF token 过期时 [create a custom Event](https://developer.mozilla.org/en-US/docs/Web/Guide/Events/Creating_and_triggering_events)。 该视图接收三个变量： * `$route`：将进行“戳”操作的相对路由。 * `$interval`：进行“戳”操作的时间间隔（毫秒）。 * `$lifetime`：会话生命周期（毫秒）。 ## Laravel Octane 兼容性 - 只有 `InjectsScript` 中间件被绑定为 singleton（单例），并且它保存了模式，该模式将在整个进程生命周期中持续存在。该模式并不打算随请求而改变。 将此包与 Laravel Octane 一起使用应该没有问题。 ## 安全 如果您发现任何与安全相关的问题，请 [use the online form](https://github.com/Laragear/Poke/security)。 # 许可证 此特定包版本在发布时根据 [MIT License](LICENSE.md) 的条款授权。 [Laravel](https://laravel.com) 是 [Taylor Otwell](https://github.com/TaylorOtwell/) 的商标。版权所有 © 2011–2026 Laravel LLC。

标签：Composer 包, CSRF Token, HTTP HEAD 请求, Laragear, Laravel, Laravel Octane, OpenVAS, PHP, Session Keep-Alive, Session 管理, TokenMismatchException, Web 开发, 中间件, 会话过期处理, 后端开发, 数据可视化, 状态维护, 用户体验优化, 网络安全, 自动刷新, 表单保活, 隐私保护, 页面可见性 API