README

这些实用工具使您能够为crwl.io网络爬虫和抓取应用程序开发扩展。

如何为crwl.io应用程序打包自定义步骤

crwlr.software文档提供了如何为crwlr/crawler库构建自己的步骤的详细说明。

一旦您成功创建了一个工作的步骤，您的任务中最具挑战性的部分就已经完成。要将自定义步骤集成到crwl.io应用程序中，请按照以下简单步骤进行

将其打包为GitHub仓库中的Composer包。
创建一个 StepBuilder
创建一个laravel ServiceProvider，并使用本包中包含的ExtensionPackageManager注册您的扩展步骤。

Composer包设置

确保您的包仓库的composer.json文件类似于以下模板

{
  "name": "my-vendor/my-crwl-extension",
  "description": "Extension package with custom steps for the crwl.io app",
  "type": "library",
  "autoload": {
    "psr-4": {
      "MyVendor\\MyCrwlExtension\\": "src/"
    }
  },
  "require": {
    "crwlr/crawler": "^1.5",
    "illuminate/support": "^9.27|^10.0",
    "crwlr/crwl-extension-utils": "^1.0"
  }
}

您可以根据自己的喜好进行自定义，但请确保它包含以下三个包的依赖项：crwlr/crawler、crwlr/crwl-extension-utils 和 illuminate/support。

为了有一个良好的项目结构，我们建议以下文件夹安排

/
├─ src/
│  ├─ StepBuilders/
│  ├─ Steps/
│  ├─ ServiceProvider.php
├─ .gitignore
├─ composer.json
├─ README.md

在您的.gitignore中，至少包含以下条目

/vendor/
composer.lock

步骤构建器

要为您的步骤创建一个StepBuilder，请参考以下示例

namespace MyVendor\MyCrwlExtension\StepBuilders;

use Crwlr\Crawler\Steps\StepInterface;
use Crwlr\CrwlExtensionUtils\ConfigParam;
use Crwlr\CrwlExtensionUtils\StepBuilder;
use MyVendor\MyCrwlExtension\Steps\MyStep;

class MyStepBuilder extends StepBuilder
{
    public function stepId(): string
    {
        return 'my-extension.my-step';
    }

    public function label(): string
    {
        return 'This step does X.';
    }

    public function configToStep(array $stepConfig): StepInterface
    {
        $fooConfigValue = $this->getValueFromConfigArray('foo', $stepConfig);

        $barConfigValue = $this->getValueFromConfigArray('bar', $stepConfig);
        
        $bazConfigValue = $this->getValueFromConfigArray('baz', $stepConfig);

        return new MyStep($fooConfigValue, $barConfigValue);
    }

    public function configParams(): array
    {
        return [
            ConfigParam::string('foo')
                ->inputLabel('Your foo'),
            ConfigParam::int('bar')
                ->default(5)
                ->inputLabel('Number of bar')
                ->description('Provide the number of bar, so the step can do X.'),
            ConfigParam::bool('baz')
                ->inputLabel('Baz?'),
        ];
    }
}

如果您的步骤需要配置，请在configParams()方法中定义必要的参数。crwl.io应用程序的爬虫创建/编辑表单将显示相应的输入，以显示这些配置选项。当爬虫运行时，将使用用户保存的配置数据调用StepBuilder::configToStep()方法。在此方法中，使用配置值构建您的自定义步骤，并返回它。

目前，可用的配置参数类型是string、int和bool。您可以分别为每个配置参数指定默认值（default()）、输入标签（inputLabel()）和描述文本（description()）。

如果您的步骤不需要任何设置，则StepBuilder看起来相当简约

namespace MyVendor\MyCrwlExtension\StepBuilders;

use Crwlr\Crawler\Steps\StepInterface;
use Crwlr\CrwlExtensionUtils\StepBuilder;
use MyVendor\MyCrwlExtension\Steps\MyStep;

class MyStepBuilder extends StepBuilder
{
    public function stepId(): string
    {
        return 'my-extension.my-step';
    }

    public function label(): string
    {
        return 'This step does X.';
    }

    public function configToStep(array $stepConfig): StepInterface
    {
        return new MyStep();
    }

}

如果您的步骤需要文件系统路径，其中可以存储文件，您可以在构建器中使用$this->fileStoragePath。crwl.io应用程序在构建任何步骤之前为所有步骤构建器设置此路径。

public function configToStep(array $stepConfig): StepInterface
{
    return new MyStep($this->fileStoragePath);
}

ServiceProvider和注册包及步骤

要使您的步骤在crwl.io应用程序中可用，最后的步骤是使用本包中包含的ExtensionPackageManager注册扩展包和所有步骤。由于crwl.io是一个Laravel应用程序，这是通过一个ServiceProvider类来完成的

namespace MyVendor\MyCrwlExtension;

use Crwlr\CrwlExtensionUtils\ExtensionPackageManager;
use MyCrwlExtension\StepBuilders\FooStepBuilder;
use MyCrwlExtension\StepBuilders\BarStepBuilder;
use MyCrwlExtension\StepBuilders\BazStepBuilder;

class ServiceProvider extends \Illuminate\Support\ServiceProvider
{
    public function register()
    {
        $this->app->make(ExtensionPackageManager::class)
            ->registerPackage('my-vendor-name/my-crwl-extension')
            ->registerStep(FooStepBuilder::class)
            ->registerStep(BarStepBuilder::class)
            ->registerStep(BazStepBuilder::class);
    }
}

为了完成设置，将ServiceProvider添加到composer.json文件的extra部分

{
  "name": "my-vendor/my-crwl-extension",
  "description": "Extension package with custom steps for the crwl.io app",
  "type": "library",
  "autoload": {
    "psr-4": {
      "MyVendor\\MyCrwlExtension\\": "src/"
    }
  },
  "require": {
    "crwlr/crawler": "^1.4",
    "illuminate/support": "^9.27|^10.0",
    "crwlr/crwl-extension-utils": "^1.0"
  },
  "extra": {
    "laravel": {
      "providers": [
        "MyVendor\\MyCrwlExtension\\ServiceProvider"
      ]
    }
  }
}

有了这些配置，您的扩展包就准备好使用了。如果您的扩展是私有的，请确保您授予crwlrsoft GitHub组织访问权限。作为crwl.io实例上的超级用户，您可以通过应用程序中的扩展页面安装您的扩展。

不使用crwlr/crawler HttpLoader执行HTTP请求的自定义步骤

在需要执行无法利用来自 crwlr/crawler 包的 HttpLoader 的 HTTP 请求的自定义步骤的场景中——例如，在利用 REST API SDK 从 API 获取数据时——您需要确保在 crwl.io 应用程序内执行自定义步骤时跟踪每个 HTTP 请求。

为此，您有两种选择

使用由 TrackingGuzzleClientFactory 生成的 Guzzle 客户端实例。
或者，在每个请求后手动调用 RequestTracker 的 trackHttpResponse() 或 trackHeadlessBrowserResponse() 方法。

使用 Guzzle 客户端实例

如果您想使用 Guzzle Client 实例进行请求（对于 PHP API SDK，通常允许您提供自己的 Guzzle 实例），请使用此包中的 TrackingGuzzleClientFactory。

use Crwlr\CrwlExtensionUtils\TrackingGuzzleClientFactory;

// Let the factory be resolved by the laravel service container.
$factory = app()->make(TrackingGuzzleClientFactory::class);

$client = $factory->getClient();

您还可以将自定义 Guzzle 配置作为参数传递

$client = $factory->getClient(['allow_redirects' => false]);

使用 RequestTracker

在不适合使用 Guzzle Client 实例进行请求的场景中，您需要调用 RequestTracker::trackHttpResponse() 或如果您使用无头浏览器执行请求，则调用 RequestTracker::trackHeadlessBrowserResponse()。

use Crwlr\CrwlExtensionUtils\RequestTracker;

// Let the tracker be resolved by the laravel service container.
$tracker = app()->make(RequestTracker::class);

// Execute your request however you want...

$tracker->trackHttpResponse();

// or

$tracker->trackHeadlessBrowserResponse();

如果您可以提供实现 PSR-7 RequestInterface 和/或 ResponseInterface 的请求/响应实例，请这样做

$tracker->trackHttpResponse($request, $response);

// or

$tracker->trackHeadlessBrowserResponse($request, $response);

crwlr / crwl-extension-utils

维护者

详细信息