README

Larvis 是一个用于 Laravel 的 PHP 包，允许 Laravel 应用将信息和错误报告发送到 MoonGuard 或 Krater。

目前，您可以在以下场景中使用 Larvis：

将应用程序中的异常报告给 MoonGuard（适用于需要跟踪的生产站点）。
将消息、异常、数据库查询和 HTTP 请求从 Laravel 应用程序发送到 Krater（适用于需要调试不同信息的开发环境）。

什么是 MoonGuard？

MoonGuard 是一个开源 Filament 插件，旨在为生产环境中的 Laravel 应用提供监控工具。

MoonGuard 帮助您跟踪 SSL 证书状态、正常运行时间、异常和应用程序服务器数据等重要功能。

更多信息请访问 MoonGuard 官方网站。

什么是 Krater？

Krater 是一个用于调试 Laravel 应用的桌面应用程序，它提供了一个直观、友好的界面来调试异常、查询、请求等。

更多信息请访问 Krater 官方网站。

安装

您可以使用以下命令通过 composer 安装 Larvis：

composer require taecontrol/larvis

安装后，我们建议发布配置以根据您的需求自定义 Larvis 的行为。

php artisan vendor:publish --tag larvis-config

太好了！Larvis 现已安装在您的项目中，配置文件应在 config/larvis.php 中可用。此时，您需要决定 Larvis 应如何操作和表现。

您可以将它配置为在 生产环境 中与 MoonGuard 一起工作，一旦发布并部署到全球，就报告应用程序中的每个异常和服务器度量。如果您想在本地上使用 Larvis 调试 Laravel 应用程序，可以将其配置为与 Krater 一起工作。总之，Larvis 可以以两种方式操作：

Larvis 在 生产环境 中与 MoonGuard 一起工作。
Larvis 在本地与 Krater 一起用于调试。

重要

Larvis 的默认行为是与 Krater 一起工作。

设置 Larvis 以与 MoonGuard 一起工作

要允许 Larvis 捕获并报告异常，需要在应用程序的 .env 文件中添加三个变量：

MOONGUARD_DOMAIN=https://mymoonguard.com
MOONGUARD_SITE_API_TOKEN=LDUxazsuq6aYi9bvSMqc6vkMXOjsD7JdrIN2FkWtA4UVNhaPE02gMS23FIp0
KRATER_DEBUG=false

您可以在 MoonGuard 管理面板（站点管理）中获取 API 令牌。此令牌对您的站点是唯一的，用于在每个请求中对站点进行身份验证。

无需额外步骤。使用此设置，Larvis 可以将您的应用程序异常报告给 MoonGuard。

重要

仅当应用程序环境为 production 时，向 MoonGuard 报告异常才有效。

设置 Larvis 以与 Krater 一起工作

Larvis 的默认行为是与 Krater 一起工作和调试。我们开发了几种实用工具，可以轻松地将消息、异常、查询和请求等数据捕获并报告给 Krater。

关注者

监控器是监控和记录应用程序不同方面的组件，例如请求、数据库查询和异常。Larvis 包括以下监控器：

QueryWatcher：检测并报告发送到应用程序数据库的所有查询。
ExceptionWatcher：检测并报告应用程序中发生的任何异常。
RequestWatcher：检测并报告发送到应用程序的任何请求。

所有监控器都可以从 Larvis 配置文件中启用或禁用。

重要

RequestWatcher 和 QueryWatcher 与 MoonGuard 不兼容。

向 Krater 发送消息

Larvis 将消息理解为要发送给 Krater 的数据，类似于你在项目中使用 dd($arg) 时的做法。在这种情况下，Larvis 和 Krater 使用不同的策略来格式化数据，使其调试更加灵活。

存在一个全局函数 larvis($args)，允许你将任何类型的数据作为消息发送给 Krater。以下是使用示例：

发送字符串数组

larvis(["hello","i'm Larvis"]);

发送字符串

larvis("Hello");

发送数字数组

larvis([1, 2, 3, 4, 5]);

发送空值

larvis(null);

发送集合

$collection = collect([1, 2, 3, 4, 5]);
larvis($collection);

发送对象

$user = new User();
$user->name = 'John Doe';
$user->email = 'johndoe@example.com';
$user->age = 30;
larvis($user);

监控和发送查询到 Krater

为了监控和向 Krater 发送查询，必须启用 QueryWatcher，正如我们之前提到的，此监视器允许你检测并报告所有对应用程序数据库执行的查询。

可以在 Larvis 配置中启用 QueryWatcher

[
    'watchers' => [
        'queries' => [
            'enabled' => true,
        ],
    ],
];

要记录独立的查询，可以使用 startQueryWatch() 和 stopQueryWatch()，如下所示

larvis()->startQueryWatch();
User::all();
larvis()->stopQueryWatch();

startQueryWatch()：启动 QueryWatcher，此行之后的任何查询都将被记录和报告。
stopQueryWatch()：停止 QueryWatcher，此行之后的任何查询将不会被记录或报告。

监控和发送异常到 Krater

为了监控和向 Krater 发送异常，必须启用 ExceptionWatcher，此监视器默认启用。

[
    'watchers' => [
        'exceptions' => [
            'enabled' => true,
        ],
    ],
];

监控和发送请求到 Krater

为了监控和向 Krater 发送请求，必须启用 RequestWatcher，它启用了监控你的 Laravel 应用程序中的 HTTP 请求并将其相关信息发送到 Krater 的功能。

[
    'watchers' => [
        'request' => [
            'enabled' => true,
        ],
    ],
];

读取器

读取器是我们开发的一种实用工具，用于以实用方式处理 PHP 对象。其多功能性允许你指定需要从对象中处理哪些属性，你可以在 Larvis 配置中修改这些属性。

目前，此属性指定仅与以下 Illuminate 类兼容

Illuminate\Database\Eloquent\Model
Illuminate\Support\Collection

在配置文件中，你将找到类似以下内容

[
    'readers' => [
        'model' => [
            'props' => [
                'connection',
                'table',
                'primaryKey',
                'keyType',
                'incrementing',
                'with',
                'withCount',
                //...
            ],
        ],
    ],
];

在这里，你可以根据你的偏好修改需要调试的 Illuminate 模型的属性。

你可以用同样的方式处理 Illuminate 的 Collection

[
    'collection' => [
        'props' => [
            'items',
            'escapeWhenCastingToString',
        ],
    ],
];

命令

Larvis 允许你执行用于不同目的的命令。

CheckHardwareHealthCommand

此命令非常有用，可以从运行应用程序的服务器上获取 CPU 负载、RAM 内存使用情况和磁盘使用情况（磁盘消耗和总磁盘容量），然后通过 HTTP 协议发送到 MoonGuard Filament 插件。此命令旨在与 Laravel 控制台调度器一起使用，请在 console/Kernel.php 文件中注册它

注意

我们建议频率为 5 分钟或更短

protected function schedule(Schedule $schedule): void
{
    $schedule->command(CheckHardwareHealthCommand::class)
        ->everyFiveMinutes();
}

Krater：调试进化

Krater 是一个轻量级、跨平台的应用程序，它彻底改变了你在下一个主要项目中使用 Laravel 应用程序的调试。

MoonGuard：软件开发者的旅程 [书籍]

MoonGuard 开发团队撰写了一本名为“MoonGuard：软件开发者的旅程”的书籍。在这本书中，我们记录并解释了创建、开发、发布 MoonGuard 作为 Filament 插件的整体过程。每个难点和特殊技巧都被记录在这本书中，你可以在以下链接中获取你的电子版：这里。

贡献

感谢考虑为 Larvis 贡献，贡献指南可以在 MoonGuard 文档中找到。

鸣谢

许可

Larvis 包是开源软件，根据 MIT 许可证许可。

taecontrol / larvis

维护者

详细信息