> ## Documentation Index
> Fetch the complete documentation index at: https://kawax.biz/llms.txt
> Use this file to discover all available pages before exploring further.

# Laravel FullFeed

> 為 feed reader 從網頁擷取主要內容的 Laravel 套件。活用 Laravel 的 Pipeline pattern。

## 概觀

[revolution/laravel-fullfeed](https://github.com/invokable/laravel-fullfeed) 是為 feed reader 從網頁擷取本文的 Laravel 套件。\
使用各網站的規則(JSON),為每篇文章擷取所需的內容。

<Info>
  原本是私人 feed reader 應用內部使用的功能,將其抽出並公開為套件。
</Info>

## 需求

* PHP >= 8.4(使用 `Dom\HTMLDocument`)
* Laravel >= 12.x

## 安裝

```bash theme={null}
composer require revolution/laravel-fullfeed
```

若使用開發版:

```bash theme={null}
composer require revolution/laravel-fullfeed:dev-main
```

## 發佈設定檔與網站定義

```bash theme={null}
php artisan vendor:publish --tag=fullfeed
```

此指令會建立以下項目:

* `config/fullfeed.php`
* `resources/fullfeed`

## 自動更新定義檔(composer post-update-cmd)

若希望 `composer update` 時自動重新發佈網站定義,可在 `composer.json` 加入以下設定。

```json theme={null}
{
  "scripts": {
    "post-update-cmd": [
      "@php artisan vendor:publish --tag=laravel-assets --ansi --force",
      "@php artisan vendor:publish --tag=fullfeed-site --ansi --force"
    ]
  }
}
```

## 基本用法

```php theme={null}
use Revolution\Fullfeed\Facades\FullFeed;

$html = FullFeed::get($url);
```

## 測試

可用 `FullFeed::expects()` 對 Facade 進行 stub。

```php theme={null}
use Revolution\Fullfeed\Facades\FullFeed;

FullFeed::expects('get')
    ->with('https://example.com/article/1')
    ->andReturn('<div>Main content</div>');
```

## 網站規則檔

### items\_all.json

`items_all.json` 是用於匯入 LDRFullFeed (wedata) 格式規則的基礎。\
Livedoor Reader 是日本著名的服務,雖然服務本身已停止,但目前規則資料主要作為資產保留下來。FullFeed 活用此歷史資料格式。

### plus.json

`plus.json` 是自訂規則新增的範例。

```json theme={null}
{
  "name": "note",
  "data": {
    "url": "^https://note\\.com/",
    "selector": "div[data-name=\"body\"]",
    "xpath": "//div[@data-name=\"body\"]",
    "enc": "UTF-8",
    "callable": "App\\FullFeed\\CustomExtractor"
  }
}
```

## 規則設定欄位

* `url`: 用於比對目標 URL 的正規表達式
* `selector`: CSS selector(優先於 `xpath`)
* `xpath`: XPath 指定
* `enc`: 需要字元編碼轉換時的編碼指定
* `callable`: 作為前處理執行的自訂 Extractor 類別(單個/陣列)
* `after_callable`: 作為後處理最後執行的 Extractor 類別

## 作為 Pipeline pattern 的 Extractor 執行順序

FullFeed 使用 Laravel 的 **Pipeline pattern** 依序執行 Extractor。

1. `callable` 指定的類別
2. `XPathExtractor`
3. `SelectorExtractor`
4. `after_callable` 指定的類別

可在單純的 XPath/CSS 擷取前後插入自訂處理,便於對應各網站的特殊需求。

## 內建 Extractor

### RemoveElements

刪除指定 selector 的元素。

```json theme={null}
{
  "after_callable": ["Revolution\\Fullfeed\\Extractor\\RemoveElements"],
  "remove": ["svg", "button", "script"]
}
```

### ReplaceMatches

以正規表達式取代符合的字串(對 HTML 字串進行處理)。

```json theme={null}
{
  "after_callable": ["Revolution\\Fullfeed\\Extractor\\ReplaceMatches"],
  "replace": [
    {
      "pattern": "/ data-(h-)?index=\"[0-9]+\"/",
      "replace": ""
    }
  ]
}
```

### StripTags

以 `strip_tags()` 相同方式移除標籤。

```json theme={null}
{
  "after_callable": ["Revolution\\Fullfeed\\Extractor\\StripTags:a,img"]
}
```

### Squish

以 `Str::squish()` 刪除多餘空白。

```json theme={null}
{
  "after_callable": ["Revolution\\Fullfeed\\Extractor\\Squish"]
}
```

## 新增自訂規則

1. 在 `resources/fullfeed` 新增 JSON 檔
2. 在 `config/fullfeed.php` 的 `paths` 加入

因為會使用 `data.url` 最先符合的規則,建議將新增檔案放在 `paths` 的最前面。


## Related topics

- [Feed Generator](/zh-TW/packages/laravel-bluesky/feed-generator.md)
- [Feedable](/zh-TW/packages/feedable/index.md)
- [Bot 教學 - Laravel Bluesky](/zh-TW/packages/laravel-bluesky/bot-tutorial.md)
- [支援網站清單 - Feedable](/zh-TW/packages/feedable/drivers.md)
- [核心套件與自訂驅動 - Feedable](/zh-TW/packages/feedable/core.md)