README

虽然有很多用于创建Laravel应用程序管理员面板的包和解决方案，但我发现它们大多数设置和管理都过于复杂。

此包的想法是尽可能快地为任何Laravel应用程序设置管理员面板。

它是如何工作的

其背后的原理非常简单：该包设置了一个管理员面板布局，您可以使用Livewire或Blade组件创建管理员页面。一旦您在配置adminPanel.pages中注册了每个页面，您的页面就会在管理员面板中可见。

安装

使用Composer在您的Laravel 8+应用程序中安装此包

composer require antonioprimera\laravel-admin-panel

注意：此包尚未与Laravel 9+进行测试，但原则上应该可以工作。

如果您的项目使用TailwindCss v2 / Tailwind v3，并且包含Tailwind类的CSS文件是public/css/app.css，则一切就绪。

注意：管理员面板需要TailwindCss插件@tailwindcss/forms！

如果TailwindCss在'css/app.css'之外的文件中

如果TailwindCss类在另一个文件中找到，您应该在配置文件“adminPanel.php”中配置资产路径（要么从包中发布，要么创建一个新的文件）

'projectTailwindCss' => 'css-folder/some-other-css-file.css',

如果您的项目不使用TailwindCss v2+

如果您的项目不使用TailwindCss v2+，您应将projectTailwindCss配置条目设置为布尔值false。管理员面板将使用CDN上的TailwindCss 3。

用法

默认情况下，在安装包并按照安装指南中的步骤操作后，您应该能够在浏览器中通过http://your-local-project.url/admin-panel访问您的管理员面板。

管理员面板配置

您可以创建自己的adminPanel.php配置文件，或者可以通过以下方式发布包配置

php artisan vendor:publish --tag=admin-panel-config

adminPanel.pages

此配置键将保存管理员面板中所有管理页面的列表和定义。

让我们从一个“网站设置”管理员页面的示例开始

return [
    'pages' => [
        'site-settings' => [
            'name'      => 'Site Settings',                                                 //required
            'view'      => MyProject\Html\Livewire\SiteSettingsAdminPageComponent::class,   //required
            'icon'      => 'heroicon:cog',                                                  //recommended
            'menuLabel' => 'Site Settings',                                                 //optional
            'position'  => 0,                                                               //optional
            'viewData'  => ['defaultTheme' => 'dark', 'otherData' => 'other stuff'],        //optional
        ],
        
        //... other pages
    ],
];

name（必需）

这是每个页面的必填设置。这是管理员页面的可读名称和标题。如果没有提供'menuLabel'，则此名称也将用作管理员面板菜单中此页面的标签。

view（可选）

如果您不需要复杂的逻辑，只需创建一个视图并将其用作管理页面。此视图将被包裹在管理面板布局中。

您可以使用 livewire 组件（推荐）、blade 组件或内联视图。

视图选项 1：管理页面 Livewire 组件

推荐的方法是创建用于管理页面的 Livewire 组件。这些是默认的 Livewire 组件，没有任何限制。您可以使用 TailwindCss v3 样式。

例如：

    'view' => MyProject\Html\Livewire\SomeAdminPageComponent::class

视图选项 2：管理页面 Blade 文件

Blade 文件应该只有一个根节点（为了未来的兼容性）。您可以使用 TailwindCss v3 样式。

例如：

    'view' => 'path.to.the-blade-file'

视图选项 3：内联 HTML

尽管不推荐，但您可以使用内联 HTML 来显示管理页面视图。如果您有一些在前端 JS 框架（如 VueJS）中的组件，并且不想创建一个只有一行 HTML 的 blade 文件，这可能很有用。

例如：

    'view' => '<my-special-component :message="This might be a VueJS component"/>'

图标（推荐）

Admin Panel 包使用一个简单的包，它使简单的 HeroIcons 集成成为可能。您可以在以下位置查看此包：antonioprimera/laravel-heroicons

这允许您通过简单地使用以 'heroicon:' 或 'hero:' 为前缀的图标名称，为每个页面定义来自 heroicons 页面的图标。

例如，要使用 'cog' 图标，您只需写下

    'icon' => 'heroicon:cog',   //or just 'hero:cog'

如果您没有提供图标，AdminPanel 将提供默认图标，但所有未定义图标的页面将使用菜单中的相同图标。

菜单标签（可选）

默认情况下，管理页面名称将用作菜单中的页面标签。在某些情况下，您可能想要定义不同的标签（例如，如果名称非常长）。

例如：

    'name'      => 'My Awesome Site Settings',
    'menuLabel' => 'Settings',

位置（可选）

默认情况下，管理页面在管理面板菜单中以伪随机顺序显示，基于它们定义的位置。如果您想设置特定的顺序，您可以定义页面位置为整数。

viewData（可选）

默认情况下，如果管理页面视图是自给自足的，您可以忽略此属性。如果您使用需要分配一些数据的通用 Livewire 或 Blade 组件，则可以使用此属性来定义数据数组。

例如：

    'viewData' => ['webComponentUid' => 'home-page'],

url（可选）

如果您想使管理页面指向特定的 URL，您可以在此处提供完整的 URL。如果您不提供 URL 或路由，则必须提供视图（Livewire / blade / 内联），AdminPanel 将将其与自己的路由 admin-panel/{uid} 关联。在这种情况下，uid 将用于区分管理页面。

例如：

    'url' => '/products/index',

route（可选）

如果您使用命名路由，您可以提供路由名称，以确定相应的 URL。这是 url 属性的替代方案（使用其中一个，不要同时使用两个）。

例如：

    'route' => 'products.index',

uid（可选）

默认情况下，每个页面都有一个唯一的id，这是管理页面配置的数组键。您可以为一个页面设置特定的uid，以覆盖具有相同uid之前注册的管理页面。自行设置uid可能会产生意外结果，所以，只有当您知道自己在做什么时才这样做。

adminPanel.layout

adminPanel.layout配置决定用于管理面板的布局blade文件。默认布局是admin-panel::layouts.default。

adminPanel.projectTailwindCss

adminPanel.projectTailwindCss配置决定包含tailwind css类的css文件的位置，相对于您的公共文件夹（默认为'css/app.css'）。如果您的项目不使用tailwind css或您想要一个干净且完整的tailwind css文件（来自tailwind cdn），可以将此条目设置为布尔值false。

adminPanel.routePrefix

这是所有管理面板页面的路由前缀，也是管理面板仪表板的路由（管理面板的入口点）。默认情况下，这是admin-panel，因此您的管理面板可以通过https://your.project.url/admin-panel访问。如果您想更好地保护您的管理面板，可以使用随机的路由前缀，在adminPanel.routePrefix中配置，或作为ENV变量。

ADMIN_PANEL_ROUTE_PREFIX="/random/admin-panel/prefix"

adminPanel.middleware

您可以定义应用于所有管理面板页面的中间件。默认情况下，以下中间件被配置为应用'middleware' => ['web', 'auth']。

您可以设置env属性ADMIN_PANEL_MIDDLEWARE为逗号分隔的中间件列表，而不会覆盖默认配置。这允许您，例如，只在开发环境中使用'web'中间件（不使用'auth'），这样您就不必创建用户并登录才能访问您的管理面板。

例如，ADMIN_PANEL_MIDDLEWARE="web,some-special-middleware"

使用您自己的控制器向管理面板添加视图

从admin-panel的2.2版本开始，您可以创建自己的管理页面，并轻松地将它们添加到管理面板。如果您想将多个页面与一个管理面板菜单项关联，这尤其有用。

例如，如果您有一个'/admin-panel/products'页面，列出了您所有的产品，配置在您的adminPanel配置文件中，您可以在同一管理页面（同一菜单项显示为活动状态）下添加一个产品详情页面：'/admin-panel/products/{product}'。

管理面板布局blade组件

admin-panel包暴露了当前配置的管理面板布局作为blade组件，别名为x-admin-page或x-admin-panel-layout（同一布局的两个别名）。

布局组件接受一个可选参数uid，可以用来显示菜单中的其中一个页面为活动状态。在幕后，视图使用AdminPanel::setCurrentPageUid(<active admin page uid>);来设置给定的uid为管理面板中当前活动的管理页面uid。

例如：

//your adminPanel config - you must provide the proper url or route name for the admin page
return [
    //...
    'pages' => [
        'machines' => [
            'name' => 'Products'
            'icon' => 'hero:cog',
            'url' => '/products',   //or 'route' => 'products.index'
        ],
    ],
]

//your Controller - no special treatment here
class MachineManager extends Controller
{
    public function index()
    {
        return view('machines.index', ['products' => Products::available()->get()]);
    }
}

//your routes file (usually: routes/web.php) - no special treatment here
Route::get('/machines', [MachineController::class, 'index'])->name('machines.index');

<!-- Your blade file (resources/views/machines/index.blade.php) -->
<!-- Just wrap everything in the x-admin-page layout and provide the active admin-page uid as an attribute -->
<x-admin-page uid="machines">
    ... your admin page content goes here ...
</x-admin-page>

包开发 & 扩展管理页面

管理员面板旨在轻松集成到现有的 Laravel 应用程序中，同时也易于在其他包中进行扩展和使用，在这些包中，您希望发布管理页面，以便您的用户可以访问您包的一些方面。

AdminPanel Facade

通过 AdminPanel Facade，您可以访问管理面板及其管理页面的所有设置。您可以获取所有管理页面，添加新的页面。

如果您想构建自己的管理面板布局，读取所有管理页面并为所有管理页面添加菜单项，可以使用此外观。

AdminPage 实例

管理员面板为每个单独的管理页面生成一个 AntonioPrimera\AdminPanel\AdminPage 实例。此类公开了管理页面的所有属性 - 其 URL、名称、Uid、视图、视图数据等。

在您的包中生成管理页面

您可以通过在 Service Container 中添加一个页面收集器类并为其标记为 'admin-pages'，轻松为您的包添加管理页面，而无需要求此包。

以下是一个 HeroIcons 包的示例，该包添加了一个列出所有可用英雄图标的管理页面

//WebPageServiceProvider.php

public function register()
{
    //...
    $this->app->bind(HeroIconsAdminPageCollector::class);
    $this->app->tag(HeroIconsAdminPageCollector::class, 'admin-pages');
}

此页面收集器类可以是任何类，只需有一个简单的公共方法名为 'resolve'，该方法返回一个页面配置数组，这正是您会在您的 adminPanel.pages 配置中编写的。

以下是一个 HeroIcons 包的简单管理页面收集器示例

 
class HeroIconsAdminPageCollector
{

    public function resolve()
    {
        return [
            'hero-icons-admin-page' => [
                'name'      => 'Hero Icons',
                'icon'      => 'heroicon:shield-check',
                'view'      => 'hero-icons::admin-panel.icons-list',
                'viewData'  => ['icons' => HeroIcons::all()],
            ],
        ];
    }
}

当然，您甚至可以动态地为来自数据库的模型或您包中的任何项生成管理页面。

antonioprimera / laravel-admin-panel

维护者

详细信息