README

Larapoke

保持你的表单活跃，通过温柔地戳你的 Laravel 应用来避免 TokenMismatchException

要求

PHP 7.4, 8.0 或更高版本。
Laravel 7.x, 8.x 或更高版本。

对于旧版本的支持，请考虑通过赞助或捐赠来帮助。

安装

使用 Composer 将此包添加到您的项目中

composer require darkghosthunter/larapoke

它是如何工作的？

Larapoke 会以给定的时间间隔向你的应用发送 HTTP HEAD 请求到指定的 /poke 路由。作为回应，在您的应用刷新会话寿命的同时，它发送一个 HTTP 204 状态码，这是一个没有主体的 OK 响应。

这仅仅相当于 仅发送 800 字节！

CSRF 令牌过期时自动重新加载

Larapoke 脚本将检测 CSRF 会话令牌是否过期，基于上一次成功的戳击，并在有网络连接的情况下强制重新加载页面。

这是通过检测浏览器或选项卡变为活动状态时或设备用户再次上线时来实现的。

这在用户笔记本电脑休眠或手机失去信号的情况下非常有用。因为这些时刻会话可能会过期，当浏览器唤醒或手机重新上线时，页面会重新加载以获取新的 CSRF 令牌。

用法

在您的应用中启用 Larapoke 有三种方式。

auto（简单的无接触默认模式）
中间件
手动

您可以通过环境文件更改默认模式

LARAPOKE_MODE=auto

`auto`

只需安装此包，看看它如何运行。这将推送一个全局中间件，它会查看您所有响应的内容，其中

内容是 HTML，
存在包含 csrf 令牌的输入，
或存在 csrf-token 元标签。

如果存在任何大小写不敏感的匹配项，这将在此 </body> 标签之前注入负责保持表单活跃的 Larapoke 脚本。

在此模式下，不会在无成功响应（不是 HTTP 2xx 的任何内容）上注入脚本，如错误或重定向。

如果您的应用有多个路由或大量文本的响应，建议使用其他模式。

`middleware`

这将禁用全局中间件，允许您仅在您明确指定的路由中使用 larapoke 中间件。

<?php

use Illuminate\Support\Facades\Route;
use App\Http\Controllers\Auth\RegisterController;

Route::get('register', [RegisterController::class, 'showForm'])
    ->middleware('larapoke');

即使没有表单，也会强制注入脚本到路由中。您也可以将其应用于路由组。

由于路由组可能包含没有任何表单的路由，您可以将 detect 选项添加到中间件中，这将扫描响应以查找 CSRF 令牌，并且只有在找到令牌时才注入脚本。

<?php

use Illuminate\Support\Facades\Route;
use App\Http\Controllers\Auth\RegisterController;

Route::prefix('informationForms')
    ->middleware('larapoke:detect')
    ->group(function () {
        
        // Here it will be injected
        Route::get('register', [RegisterController::class, 'showForm']);
        
        // But not here since there is no form
        Route::get('status', [RegisterController::class, 'status']);
    });

在此模式下，不会在无成功响应（不是 HTTP 2xx 的任何内容）上注入脚本，如错误或重定向。

`blade`

blade 方法允许您在视图的任何位置使用 @larapoke 指令来注入脚本，同时保持该响应的表单状态。

<h2>Try to Login:</h2>
<form action="/login" method="post">
    @csrf
    @larapoke <!-- This script will run -->
    <input type="text" name="username" required>
    <input type="password" name="password" required>
    <button type="submit">Log me in!</button>
</form>
<h2>Or reset your password</h2>
<form action="/password" method="post">
    @csrf
    @larapoke <!-- This won't -->
    <input type="email" name="email" required>
    <button type="submit">I forgot my password!</button>
</form>

如果您在视图中使用了许多 @larapoke 指令，例如在这个示例中，无需担心。脚本可以多次注入，但只有第一次运行的脚本会激活并检查网站。

配置

为了微调，您可以发布 larapoke.php 配置文件。

php artisan vendor:publish --provider=DarkGhostHunter\Larapoke\LarapokeServiceProvider

让我们来看看 Larapoke 的配置数组。

<?php return [
    'mode' => env('LARAPOKE_MODE', 'auto'),
    'times' => 4,
    'view' => 'larapoke::script',
    'poking' => [
        'route' => 'poke',
        'name' => 'larapoke',
        'domain' => null,
        'middleware' => ['web'],
    ]
];

时间（间隔）

相对于全局会话生命周期的检查次数。次数越多，检查间隔越短。默认的 4 应该适用于任何正常应用程序。

例如，如果我们的会话生命周期是默认的 120 分钟

则每 40 分钟检查应用 3 次
则每 30 分钟检查应用 4 次
则每 24 分钟检查应用 5 次
则每 20 分钟检查应用 6 次，依此类推...

因此，基本上，会话生命周期 / 次数 = 检查间隔。

如果您预计用户会做很多无关的事情，并且可能随时退出，则应将其提高。

脚本视图

Larapoke 使用其自己的 Blade 模板来注入脚本。

您可以使用其他带有脚本的视图或通过创建 views/vendor/larapoke/script.blade.php 文件来覆盖默认值。后一种选项不需要发布配置文件。

为什么您会这样做？有些人可能想要更改这一点，因为他们想要使用 JavaScript HTTP 库、压缩响应、使其与旧浏览器兼容，甚至在 CSRF 令牌过期时创建自定义事件。

视图接收三个变量

$route：进行检查的相对路由。
$interval：进行检查的间隔（毫秒）。
$lifetime：会话生命周期（毫秒）。

检查

这是接收脚本 HTTP HEAD 请求的检查路由的设置数组。

<?php return [

    // ...

    'poking' => [
        'route' => 'poke',
        'name' => 'larapoke',
        'domain' => null,
        'middleware' => ['web'],
    ]
];

路由

将用于接收检查的应用程序根 URL 相对的路由。

<?php 
return [
    'poking' => [
        'route' => '/dont-sleep'
    ],
];

检查路由在您的应用程序中注册之前。您可以在用 HTTP 204 响应之前用您自己的逻辑覆盖检查路由。

名称

路由名称，无论出于何种原因，都可以在您的应用程序中找到检查路由。

<?php 
return [
    'poking' => [
        'name' => 'my-custom-poking-route'
    ],
];

如果您使用的是域名或子域名的数组，则此字符串将被附加到路由名称上。

域名

如果您正在使用不同的域名或子域名，可能更方便仅在特定域名下允许此路由，而不是所有域名下。一个经典的例子是，使探测路由在 http://user.myapp.com/poke 可用，但不允许在 http://myapp.com/poke。

null（默认值）：探测路由将在 每个域名或子域名 上应用。
mydomain.com：探测路由将仅应用于该域名，例如：http://mydomain.com/poke。
[数组]：探测路由将仅适用于数组内部的域名。

<?php 
return [
    'poking' => [
        'domain' => ['mysubdomain.myapp.com', 'myotherdomain.com']
    ],
];

如果您使用数组，路由名称将方便地使用域名作为前缀命名，例如 myotherdomain.com-larapoke。

中间件

默认的 Larapoke 路由使用 "web" 中间件组，这是新安装中处理网页请求的默认设置。如果您使用另一个组或想使用特定的中间件，可以在此处进行修改。

<?php 
return [
    'poking' => [
        'middleware' => ['auth:api', 'validates-ip', 'my-custom-middleware']
    ],
];

许可证

本软件包采用 MIT 许可证许可。

darkghosthunter / larapoke

维护者

详细信息