QueryList文档

插件开发 - 理论篇

QueryList支持安装插件来帮助丰富你的采集功能,目前收录的一些QueryList插件: https://github.com/jae-jae/QueryList-Community

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

接下来会以开发一个MyHttp扩展为例,一步一步的开发一个扩展,并且发布给他人使用。

前言

我们知道可以轻松通过bind绑定自定义方法到QueryList对象,从而用来扩展QueryList的功能,像下面这样:

//注册一个myHttp方法到QueryList对象
QueryList::bind('myHttp',function ($url){
    $html = file_get_contents($url);
    $this->setHtml($html);
    return $this;
});

遇到比较复杂的扩展情况,代码量比较多,如果都写到这里的话就很不优雅了,所以有一个优雅的做法,像下面这样:

QueryList::bind('myHttp',function(){
  return new MyHttp($this);
})

把代码独立到一个class中去,然后在这里引用,这样就优雅多了,而且移植性也强了,下次如果其他项目里面也需要用到,只需要把这个class拷贝过去,然后bind一下就行了。

但这样写还是不够完美,如果把你封装的功能开源给别人使用,你还得告诉别人该如何bind,用起来还是比较麻烦,有没有更简单的方法呢?当然有,那就是你替用户把bind过程也写好,这样用户只需要引入你的扩展文件就可以使用了。

实现

下面来看具体实现:

class MyHttp
{
    protected $ql;

    public function __construct($ql)
    {
        $this->ql = $ql;
    }

    //定义一个静态的install方法,用于安装你的扩展功能
    public static function install(QueryList $queryList)
    {
        //在这个方法中实现你的`bind`
        $queryList->bind('myHttp',function($url){
            return (new MyHttp($this))->get($url);
        });
     }

     //定义一个http get方法
    public function get($url)
    {
        $html = file_get_contents($url);
       $this->ql->setHtml($html);
        return $this->ql;
     }

}

这样用户使用你的扩展功能只需要这样调用即可:

MyHttp::install($ql);

用户不用关心任何细节。

插件

根据上面的推导,我们实际上就推导出插件的写法了,上面的MyHttp就是一个独立的插件了。 QueryList实现了一个use方法用于安装插件:

QueryList::use(MyHttp::class);
//相当于执行了:MyHttp::install($ql);

QueryList插件需要实现QL\Contracts\PluginContract这个接口,接口源码:

<?php
namespace QL\Contracts;

use QL\QueryList;

interface PluginContract
{
    public static function install(QueryList $queryList,...$opt);
}

所以上面的MyHttp需要改成下面这样:

<?php

use QL\Contracts\PluginContract;
use QL\QueryList;

class MyHttp implements PluginContract
{
    protected $ql;

    public function __construct($ql)
    {
        $this->ql = $ql;
    }

    //定义一个静态的install方法,用于安装你的扩展功能
    public static function install(QueryList $queryList,...$opt)
    {
        //在这个方法中实现你的`bind`
        $queryList->bind('myHttp',function($url){
            return (new MyHttp($this))->get($url);
        });
     }

     //定义一个http get方法
    public function get($url)
    {
        $html = file_get_contents($url);
        $this->ql->setHtml($html);
        return $this->ql;
     }

}

一个完整的插件就这么诞生了!

然后你就可以这样使用:

$ql = QueryList::use(MyHttp::class);
$ql->myHttp('https://querylist.cc');
echo $ql->getHtml();

插件安装参数


插件安装的时候可以让用户指定一些个性化参数,比喻提供让用户自定义bind的名字:

public static function install(QueryList $queryList,...$opt)
{
        //接受用户自定义name,默认name:'myHttp'
        $name = $opt[0] ?? 'myHttp';
        $queryList->bind($name,function($url){
            return (new MyHttp($this))->get($url);
        });
}

然后用法就变成这样了:

$ql = QueryList::use(MyHttp::class,'httpGet');

$ql->httpGet('https://querylist.cc');

echo $ql->getHtml();

复杂情况

编写一个高级的插件可能就不止一个class文件,也不止bind一个方法;这些情况QueryList都是支持的,对于多个class文件,只要主文件实现QL\Contracts\PluginContract接口即可,也可以同时bind多个方法:

public static function install(QueryList $queryList,...$opt)
{
        $name1 = $opt[0] ?? 'myHttpGet';
        $name2 = $opt[1] ?? 'myHttpPost';

        $queryList->bind($name,function($url){
            return (new MyHttp($this))->get($url);
        });

        $queryList->bind($name2,function($url,$params = []){
            return (new MyHttp($this))->post($url,$params);
        });
}

使用:

$ql = QueryList::use(MyHttp::class,'httpGet','httpPost');

$ql->httpGet('https://querylist.cc');

$ql->httpPost('https://querylist.cc',['param' => 'val']);

echo $ql->getHtml();

互相依赖


一个插件可以依赖另一个插件,一个bind也可以依赖另一个bind:

public static function install(QueryList $queryList,...$opt)
{
        //安装一个其它的插件
        $queryList->use(Curl::class);

        $queryList->bind('myHttpGet',function($url){
            // 使用刚刚安装的插件
            return $this->curl()->get($url);
        });

        $queryList->bind('getAndEncode',function($url){
            //使用上一个bind的功能
            $html = $this->myHttpGet($url)->getHtml()
            $html = iconv('GBK','UTF-8',$html);
            $this->setHtml($html);
            return $this;
        });
}

版本号约定


希望大家有一个规范的插件版本号,建议插件大版本号与QueryList大版本号对应,比喻你的插件的第一个版本号可以取为:4.0.0,然后更新的时候大版本号保持不变,依次递增小版本号。

快速上手

查看现有的QueryList插件源码是一个快速上手的好方式,QueryList插件Demo:https://github.com/jae-jae/QueryList-AbsoluteUrl

提交你的插件

欢迎提交你的插件,让更多人发现和使用:查看提交说明

QueryList插件列表:https://github.com/jae-jae/QueryList-Community

总结

说了这么多总结起来其开发一个QueryList插件非常简单,只需要实现一个install方法即可,然后在install方法中调用bind方法注入你的扩展功能即可。 最后就可以做成Composer包然后推送到GitHub和Packagist上面,方便的通过Composer安装。