README

Kontour 是一个用于 Laravel 管理页面的实用程序包。它为你在 Laravel 应用程序中创建或安装或创建的包中创建的管理工具路由提供了一个共享的 "框架"。

想法是，你的管理工具可以调用 Kontour 的功能，为网站的管理区域提供一致的用户体验。你的管理工具是使用标准的 Laravel 路由、控制器、认证、授权、验证、视图等构建的。Kontour 旨在为你提供管理区域的功能增强和可重用元素。

使用此包的最新版本，您需要至少 Laravel 9。

在 Laravel 应用程序中使用 Kontour

本文档旨在提供如何在 Laravel 应用程序中配置 Kontour 的说明。配置完成后，您可以登录到 Kontour 管理区域并使用安装包中的任何管理工具。

使用 Kontour 创建管理工具

有关如何使用 Kontour 提供的功能创建和注册自己的工具的文档和有用的指南，请参阅 使用 Kontour 构建 admin 工具。

功能

• 具有可配置守卫器的管理员登录和密码重置路由，以将管理员用户与前端用户分开。请带来您自己的 AdminUser 模型！
• 可扩展的 Blade 布局，具有命名部分以供管理工具视图使用，以及可配置的样式表和 JavaScript 依赖项。
• 可放置在命名 Blade 部分中的小工具
  • 全局小工具，用于菜单、注销和最近使用工具。
  • 工具小工具，用于反馈消息、面包屑导航和项目历史记录。
• 可配置 URL 前缀和域的管理路由组。
• 可重用的 Blade 包含/组件
  • 表单模板.
  • 按钮模板.
  • 时间模板.
• 对 AdminLink 的授权确保在输出链接之前当前用户有权限。

架构

• Kontour 作为依赖项安装在 Laravel 项目中，而不是模板。
• 尽可能使用核心 Laravel 功能，如认证和授权，Kontour 没有依赖 Laravel 生态系统之外的功能。
• Kontour 提供的一切都是可选的，并且可以配置以在已安装的 Laravel 应用程序中留下最小的足迹。

安装

也许您来这里是因为您安装的某个包需要 Kontour 用于其管理页面？在这种情况下，Kontour 已经通过 composer 安装，但您仍然需要阅读下面的内容，了解如何配置 Kontour 以满足您的需求。

即使 Kontour 是由其他包要求的，您也是您 Laravel 应用的所有者，并且您至少需要在登录 Kontour 管理区域之前设置管理员用户模型。

在您的 Laravel 项目中显式安装 Kontour

composer require kontenta/kontour

如果您不想在项目中运行 Kontour 服务提供程序，您可以选择 退出包发现。

检查路由列表

Kontour 以及使用它的包，将在您的 Laravel 应用程序中自动注册路由。为了跟踪正在发生的事情，您可以使用 artisan 打印所有路由。

php artisan route:list -c

列表将显示您应用中每个URI、路由名称和中介的信息。其中还包括kontour.login、kontour.logout和kontour.index路由。如果您不喜欢这些路由，您可以设置配置值来更改URL前缀或域名，甚至完全关闭它们。

在您的Laravel项目中配置Kontour

使用artisan发布配置

php artisan vendor:publish --tag="kontour-config"

然后您可以编辑config/kontour.php，并取消注释您想要调整的任何示例设置。

登录

默认情况下，Kontour仪表板路由kontour.index通过在浏览器中访问/admin来访问。

要启用登录，您需要确保要赋予访问管理员区域的用户模型实现了Kontenta\Kontour\Contracts\AdminUser合约，该合约有一个返回显示名的getDisplayName()方法。

默认的Kontour配置使用Laravel的web守卫，它从config/auth.php中获取，然后使用具有模型App\User::class的Eloquent用户提供者。如果您想让所有用户都进入管理员区域（即您没有前端用户），您可以修改该用户类以实现该接口，通过使其扩展Kontenta\Kontour\Auth\AdminUser。

这种要求是为了避免任何意外给前端用户访问管理员路由的情况。《您需要主动选择允许哪些用户模型进入管理员区域。

为管理员创建单独的用户提供者

最常见的情况是您想要为管理员用户创建一个单独的表和模型，以及一个单独的Laravel用户提供者和守卫。

1. 创建Eloquent模型和表。最简单的方法是复制Laravel原始的app/User.php模型和database/migrations/2014_10_12_000000_create_users_table.php迁移，并根据您的需求进行修改。

2. 确保模型实现了Kontenta\Kontour\Contracts\AdminUser，可能通过扩展Kontenta\Kontour\Auth\AdminUser来实现。

3. 编辑config/auth.php以添加守卫、用户提供者和可能的密码重置配置

   'guards' => [
     //...
     'admin' => [
       'driver' => 'session',
       'provider' => 'admins',
     ],
   ],
   
   'providers' => [
     //...
     'admins' => [
       'driver' => 'eloquent',
       'model' => App\AdminUser::class, // Your admin user model
     ],
   ],
   
   'passwords' => [
     //...
     'admins' => [
       'provider' => 'admins',
       'table' => 'password_resets', //using same table as the main user model
       'expire' => 60,
     ],
   ],

4. 编辑config/kontour.php并告诉它使用您的管理员守卫名称和密码配置

   'guard' => 'admin',
   'passwords' => 'admins',

创建管理员用户

为管理员用户创建公开注册没有意义，因此为开发和生产创建管理员用户的最简单方法是使用php artisan tinker。

/* Use the name of your admin model, this examples uses the default App\User */

// List all users
App\User::all();

// Start building a new user object
$user = new App\User();

// Set fields
$user->name = 'Admin';
$user->email = 'admin@yourdomain.net';

// Set a password (remember to send it to the user):
$user->password = bcrypt(...);
// ...or have the user reset password before logging in (if you've added a password reset configuration):
$user->password = '';

// Then save the user!
$user->save();

如果您愿意冒险，您可以在Kontour内创建一个管理员工具，让登录的管理员创建和邀请新的管理员用户！

在您的Laravel项目中发布默认CSS和js

您可能想要为您的管理员区域添加一些样式，纯HTML与默认浏览器样式对大多数人来说太原始了... 一个好起点是默认的Kontour样式表。

包含的javascript包括一个功能，在提交表单之前确认任何删除操作，以及在具有“脏”表单输入的页面上离开前进行确认。

方法A: artisan

传统上，使用artisan来发布资源。

使用artisan发布CSS

php artisan vendor:publish --tag="kontour-styling"

然后编辑config/kontour.php，并在stylesheets数组中取消注释'css/kontour.css'，以便每个管理员页面都拉入样式表。

使用artisan发布js

php artisan vendor:publish --tag="kontour-js"

然后编辑config/kontour.php，并在javascripts数组中取消注释'js/kontour.js'，以便每个管理员页面都拉入javascript。

方法B: Mix

还可以使用Laravel Mix来复制和版本化公共资源。

在webpack.mix.js文件中

mix
  .copy("vendor/kontenta/kontour/resources/css/kontour.css", "public/css")
  .copy("vendor/kontenta/kontour/resources/js/kontour.js", "public/js");

if (mix.inProduction()) {
  mix.version();
}

在config/kontour.php文件中

'stylesheets' => [
        (string) mix('css/kontour.css'),
    ],
    'javascripts' => [
        (string) mix('js/kontour.js'),
    ],

将Mix的输出转换为字符串，在配置文件中可以使在生产环境中缓存配置成为可能。

后备实现

此包包含Kontour合约的实现，当在Laravel服务容器中未注册其他实现时，这些实现会被用作后备。

可以通过其他包的服务提供程序或主应用程序注册覆盖实现。