开发扩展

since v1.6.0

laravel-admin支持安装扩展工具来帮助丰富你的后台功能,目前在https://github.com/laravel-admin-extensions下面已经有了十几个扩展。

如果大家在使用的过程中有在laravel-admin的基础上添加一些自己的功能或者组件,不妨做成一个laravel-admin扩展,这样可以给其它laravel-admin使用者提供帮助,并且在其它人的使用反馈中的提升扩展的质量。

这篇文档将会以开发一个phpinfo的扩展为例,一步一步的开发一个扩展,并且发布给他人使用,最终的效果参考phpinfo

创建composer包

laravel-admin的包将会用composer安装,所以先要创建一个composer包,如果你安装了v1.6或者dev-master版本,可以是用内置的admin:extend命令来生成一个扩展的骨架

运行命令的时候,可能会提示输入一个目录来存放你的扩展文件,你可以在config/admin.php里面增加一个配置'extension_dir' => admin_path('extensions'),,这样扩展文件将会存放在app/Admin/extensions目录下,当然你也可以放在任何其它目录

php artisan admin:extend laravel-admin-ext/phpinfo --namespace=Encore\\PHPInfo

其中laravel-admin-ext/phpinfo是包名,namespace选项是这个包使用的顶级命名空间,运行这个命令之后, 将会在在config/admin.php中设置的扩展目录中生成目录laravel-admin-ext/phpinfo和下面的文件结构

    ├── LICENSE
    ├── README.md
    ├── composer.json
    ├── database
    │   ├── migrations
    │   └── seeds
    ├── resources
    │   ├── assets
    │   └── views
    │       └── index.blade.php
    ├── routes
    │   └── web.php
    └── src
        ├── PHPInfo.php
        ├── PHPInfoServiceProvider.php
        └── Http
            └── Controllers
                └── PHPInfoController.php

resources用来放置视图文件和静态资源文件,src主要用来放置逻辑代码, routes/web.php用来存放这个扩展的路由设置,database用来放置数据库迁移文件和数据seeders

功能开发

这个扩展的功能主要用来将PHP中的phpinfo函数所显示的页面,集成进laravel-admin中,它将会有一个路由和一个视图文件,没有数据库文件和静态资源文件,我们可以将没有的文件或目录清理掉,清理之后的目录文件为:

    ├── LICENSE
    ├── README.md
    ├── composer.json
    ├── resources
    │   └── views
    │       └── index.blade.php
    ├── routes
    │   └── web.php
    └── src
        ├── PHPInfo.php
        ├── PHPInfoServiceProvider.php
        └── Http
            └── Controllers
                └── PHPInfoController.php

生成完扩展框架之后,你可能需要一边调试一边开发,所以可以参考下面的本地安装,先把扩展安装进系统中,继续开发

添加路由

首先添加一个路由,在routes/web.php中已经自动生成好了一个路由配置

<?php
use Encore\PHPInfo\Http\Controllers\PHPInfoController;

Route::get('phpinfo', PHPInfoController::class.'@index');

访问路径phpinfo,将会由Encore\PHPInfo\Http\Controllers\PHPInfoController控制器的index方法来处理这个请求。

设置扩展属性

src/PHPInfo.php作为扩展类,用来设置扩展的属性

<?php

namespace Encore\PHPInfo;

use Encore\Admin\Extension;

class PHPInfo extends Extension
{
    public $name = 'phpinfo';

    public $views = __DIR__.'/../resources/views';

    public $assets = __DIR__.'/../resources/assets';

    public $menu = [
        'title' => 'Phpinfo',
        'path'  => 'phpinfo',
        'icon'  => 'fa-gears',
    ];
}

这个文件用来设置这个扩展的一些属性,$name是这个扩展的名字,如果这个扩展有视图文件需要渲染,则必须指定这个扩展的$views属性,同样如果有静态资源文件需要发布,则必须设置$assets属性, 如果需要在左侧边栏增加一项菜单按钮,设置$menu属性

可以根据需要去掉不必要的属性,修改之后src/PHPInfo.php文件的代码为:

<?php

namespace Encore\PHPInfo;

use Encore\Admin\Extension;

class PHPInfo extends Extension
{
    public $name = 'phpinfo';

    public $views = __DIR__ . '/../resources/views';

    public $menu = [
        'title' => 'PHP info',
        'path'  => 'phpinfo',
        'icon'  => 'fa-exclamation',
    ];
}

然后打开src/PHPInfoServiceProvider.php,这个ServiceProvider将会在laravel启动的时候运行,用来将这个扩展的一些数据注册进系统中

加载视图

如果这个扩展需要加载视图文件,在src/PHPInfoServiceProvider.phphandle方法中加入以下的代码:

if ($views = $extension->views()) {
    $this->loadViewsFrom($views, 'phpinfo');
}

loadViewsFrom方法的的第一个参数为在扩展类src/PHPInfo.php中设置的视图属性,第二个参数是视图文件目录的命名空间,设置为phpinfo之后,在控制器中用view('phpinfo::index')来加载resources/views目录下的视图文件

引入静态资源

如果你的项目中有静态资源文件需要引入,先把文件放在resources/assets目录中,比如放入resources/assets/foo.jsresources/assets/bar.css这两个文件

接着在扩展类src/PHPInfo.php中设置$assets属性

    public $assets = __DIR__.'/../resources/assets';

然后在src/PHPInfoServiceProvider.phphandle方法中设置发布目录

if ($this->app->runningInConsole() && $assets = $extension->assets()) {
    $this->publishes(
        [$assets => public_path('vendor/laravel-admin-ext/phpinfo')],
        'phpinfo'
    );
}

安装完成之后,运行php artisan vendor:publish --provider=Encore\PHPInfo\PHPInfoServiceProvider.php,文件将会复制到public/vendor/laravel-admin-ext/phpinfo目录中。

我们需要在laravel-admin启动的时候在页面里引入这两个文件,需要在src/PHPInfoServiceProvider.phphandle方法加入下面的代码

use use Encore\Admin\Admin;

...

Admin::booting(function () {
    Admin::js('vendor/laravel-admin-ext/phpinfo/foo.js');
    Admin::css('vendor/laravel-admin-ext/phpinfo/bar.css');
});

这样就完成了静态资源的引入,在phpinfo这个扩展中,由于没有静态资源需要引入,所以可以忽略掉这一步

代码逻辑开发

这个扩展的逻辑是将phpinfo函数显示的PHP配置数据提取出来, 然后渲染新的视图渲染输出。在这一步,参考了nova-phpinfo的核心代码, 修改后的代码参考PHPInfo.php

接下来就是在控制器中通过调用PHPInfo::toCollection方法获取phpinfo的配置数据,然后渲染到视图里面,在这个扩展中,我省略了控制器这一步,直接在路由文件routes/web.php配置中渲染视图输出

<?php

use Encore\Admin\Layout\Content;
use Encore\PHPInfo\PHPInfo;

$path = PHPInfo::config('path', 'phpinfo');

Route::get($path, function (Content $content, PHPInfo $info) {
    $info = $info->toCollection();

    return $content
        ->header('PHP\'s configuration')
        ->description(' ')
        ->body(view('phpinfo::phpinfo', compact('info')));
});

这样一个完整的扩展就开发完成了,最终完整的代码可以参考phpinfo

修改 composer.json & README.md

代码部分完成之后,需要修改composer.json里面的内容,将descriptionkeywordslicenseauthors等内容替换为你的信息,然后不要忘记完善README.md,补充使用文档等相关信息。

安装

完成了扩展开发之后,根据情况可以用下面的的方式安装你的扩展

本地安装

在开发的过程中,一般需要一边调试一边开发,所以先按照下面的方式进行本地安装

打开你的项目中composer.json文件,在加入下面的配置

"repositories": [
    {
        "type": "path",
        "url": "app/Admin/extensions/laravel-admin-ext/phpinfo"
    }
]

然后运行composer require laravel-admin-ext/phpinfo完成安装,如果有静态文件需要发布,运行下面的命令

php artisan vendor:publish --provider=Encore\PHPInfo\PHPInfoServiceProvider.php

这样就完成了安装,打开http://localhost/admin/phpinfo访问这个扩展

远程安装

如果开发完成之后,希望开源出来给大家使用,按照该下面的步骤

上传到github

先登录你的Github,创建一个仓库,然后按照页面上的提示把你的代码push上去

git init
git remote add origin https://github.com/<your-name>/<your-repository>.git
git add .
git commit -am "Initial commit."
git push origin master

发布release

可以用下面的方式在本地发布版本

git tag 0.0.1 && git push --tags

也可以在Github的仓库页面的Releases页面手动设置

发布到Packagist.org

接下来就是发布你的项目到Packagist.org,如果没有账号的话,先注册一个,然后打开顶部导航的Submit, 填入仓库地址提交

默认情况下,当您推送新代码时,Packagist.org不会自动更新,所以,您需要创建一个GitHub服务钩子, 你也可以使用点击页面上的“Update”按钮手动更新它,但我建议自动执行这个过程

提交之后,由于各地的镜像同步时间的延迟,可能子用composer安装的时候,会暂时找到到你的项目,这个时候可能需要等待同步完成

发布完成之后就可以通过composer安装你的扩展了

加入到https://github.com/laravel-admin-extensions

如果想把你开发的扩展加入到laravel-admin-extensions中,欢迎用各种方式联系我,这样可以让更多人看到并使用你开发的工具。

总结

Laravel nova发布的不到一个月的时间里,就已经有了上百个扩展,虽然laravel-admin在很久之前就已经支持扩展的开发,但是由于文档的不足和缺乏时间来推动,所以这一块的功能一直没有怎么发展

我希望通过这篇文档,大家把自己在laravel-admin的使用过程中开发出来的功能, 开发成扩展沉淀下来,laravel-admin需要更多人的参与才能形成更好的生态系统

另外大家如果有好的idea,也不妨分享出来,其它有时间有精力的同学或许可以和你一起实现它。

不久的将来,laravel-admin将会尝试参考fastadmin的方式,将部分扩展组件商业化, 欢迎大家参与