tatter/alerts

适用于CodeIgniter 4的轻量级用户警报

维护者

详细信息

github.com/tattersoftware/codeigniter4-alerts

主页

源代码

问题

资助包维护！
tattersoftware
paypal.me/tatter

安装次数: 56,492

依赖项: 5

建议者: 0

安全性: 0

星标: 38

关注者: 8

分支: 9

开放性问题: 1

v3.1.0 2022-11-10 19:00 UTC

Requires

  • php: ^7.4 || ^8.0

Requires (Dev)

MIT aa7a57d5aaef3b9d0103f6fe17eca86c147fcf04

alertscodeignitermessagesdialogscodeigniter4

This package is auto-updated.

Last update: 2024-09-18 16:21:51 UTC

README

适用于CodeIgniter 4的轻量级用户警报

Coverage Status

Screenshot

快速入门

  1. 使用Composer安装: > composer require tatter/alerts
  2. 在 app/Config/Filters.php 中启用 alerts 过滤器
  3. 将 {alerts} 令牌添加到您的视图布局
  4. 加载助手: helper('alerts');
  5. 设置一个带有类和消息的警报: alert('success', 'You did it!')

功能

提供集成用户警报，适用于CodeIgniter 4，具有各种内置模板和自定义模板支持。

安装

通过Composer轻松安装，以利用CodeIgniter 4的自动加载功能，并始终保持最新状态。

composer require tatter/alerts

或者，通过下载源文件并将其添加到 app/Config/Autoload.php 中手动安装。

注意：默认显示模板期望使用 Bootstrap（不包括在内）

配置（可选）

可以使用其配置文件更改库的默认行为。将 examples/Alerts.php 复制到 app/Config/Alerts.php，并遵循注释中的说明。如果没有找到配置文件，则库将使用其默认值。

配置文件包含两个属性。

模板

属性 $template 设置用于格式化警报的视图文件的路径。默认模板具有用于与 Bootstrap 5 Alerts 一起使用的HTML标签和类，但库还包括供您选择的额外模板

  • Tatter\Alerts\Views\Bootstrap4: 与Bootstrap 4 CSS框架兼容
  • Tatter\Alerts\Views\Foundation: 与Foundation CSS框架兼容
  • Tatter\Alerts\Views\Vanilla: 框架无关的实现，具有可用于您自己的CSS样式的类

当然，您也可以添加自己的。视图文件将传递一个名为 $alerts 的数组，其中每个元素都是一个元组，其格式为 [string $class, string $content]。您的视图文件应解包每个元组

foreach ($alerts as $alert) {
    [$class, $content] = $alert;

... 然后输出警报 $content，并将其包裹在适当的HTML标签中，根据 $class 使用您喜欢的样式或类。

注意：此库 不包括 Bootstrap或Foundation的资产。请查看 Tatter\Frontend 以获取集成解决方案。

类

属性 $classes 是Session键到其CSS类的映射。这允许您控制哪些Session键被视为“警报”，以及如何将它们指定给您的视图模板。默认列表是对框架和模块常用的常见键的慷慨猜测，还添加了Bootstrap警报类，但在大多数情况下，您可能希望精简此列表或完全用您自己的替换。

请参阅下面的 警告，了解在将Session键自动填充到显示内容时需要考虑的一些注意事项。

过滤器

为了使用 AlertsFilter，您必须将其应用于目标路由。仅当存在令牌时，过滤器才适用，因此在 app/Config/Filters.php 中全局应用它是安全的。有关更多信息，请参阅 控制器过滤器。

注意：别名已为您预定义为您为 "alerts"，并且只有 after() 方法是相关的。

令牌

令牌是以下字符串：{alerts}。将其放置在您希望警报显示的视图布局中。例如

<body>
    <aside>
    {alerts}
    </aside>
    <main class="wrapper">
    ...

用法

如果正确安装，CodeIgniter 4 将检测并自动加载库、过滤器、辅助函数和配置。过滤器将收集您在配置中定义的会话键中的任何警报，通过您的视图模板进行格式化，并将其放置在您放置令牌的响应体中的任何位置 - 您只需设置警报即可！

警报可以直接在会话中设置，理想情况下作为flashdata（这样就不会重复）

session()->setFlashdata('success', 'Your account has been updated.');

很多时候，您的警报将在重定向过程中处理，因此您可以利用框架的 RedirectResponse 类的 with() 方法直接应用flashdata

if (! $fruit = $this->getPost('fruit')) {
    return redirect()->back()->with('error', 'You must select a fruit!');
}

辅助函数

此库还包括一个辅助函数，它具有合并值和检查冲突的额外优势。初始化辅助函数以使用便利包装函数

helper(['alerts']);
alert('error', 'You must accept the terms of service to continue.');

此辅助函数添加了一些功能（如冲突检测和警报合并），但在某些情况下可能会抛出异常 - 请参阅下面的 冲突 部分。

收集器

此库捆绑了一个 工具栏收集器，以简化开发和集成。它默认启用，并在工具栏处于活动状态时应在开发环境中出现。

警告

此库的前提是从 $_SESSION 获取数据并将其显示给您的网站访客。这里提到了一些预防措施，但通常：在将数据在后端和公共视图之间移动时，始终使用强大的安全实践和良好的判断力。

安全性

理想情况下，$_SESSION 不应包含如密码或信用卡号之类的关键信息。您也不应使用可区分的标识符作为会话键，这同样适用于 Alerts。请使用基本的键，并考虑将配置文件中的值减少到应用程序和模块所需的最小值。

例如，假设您向项目中添加了一个支付库，并且一些开发人员使用以下代码进行信用卡提交测试，并忘记了删除它

$_SESSION['debug'] = (string) $user->getCreditCard();

由于 "debug" 是有效的 Alerts 键，因此此信用卡号现在将成为在用户浏览器窗口中可视显示的警报！

冲突

另一个关注点是会话冲突。这次从一个例子开始

/** @var Notice $notice */
$notice = model(NoticeModel::class)->first();
session('notice', $notice);
...

// Later that same day...
alert('notice', 'Site statistics are currently being updated, expect longer load times.');

我们刚刚尝试为已存在并包含不是另一个警报的某些内容的会话键设置一个警报！这可能有几种表现方式，但最终这是一个错误，您应该注意避免这种情况。

为了澄清这个例子

  1. AlertsFilter 将默默地忽略非字符串或字符串数组的会话数据，因此 session('notice', $notice); 没有问题。
  2. 使用警报辅助函数设置您的警报包括额外的冲突保护层，但会导致 alert() 函数抛出异常。
  3. 自己设置会话键是可行的解决方案，但您必须处理现有键的检查，以避免覆盖数据。