README

A framework-agnostic PHP package for finding published articles via Bing and Google SERP scraping, using a chain-of-responsibility finder pattern.

Given a site domain and article title, the package queries Bing first and falls back to Google if no sufficiently similar result is found. You can swap or extend the chain with your own finders.

Requirements

• PHP 8.2+
• Guzzle 7+

Installation

composer require vsimke/article-finder

Usage

Default chain (Bing → Google)

use Vsimke\ArticleFinder\ArticleFinder;
use Vsimke\ArticleFinder\FinderParameter;
use Vsimke\ArticleFinder\Scraper\HQueryScraper;

$scraper = new HQueryScraper();
$finder  = ArticleFinder::create($scraper);

$result = $finder->find([
    FinderParameter::SITE  => 'example.com',
    FinderParameter::TITLE => 'My Article Title',
]);

if ($result !== false) {
    echo $result['title'];  // 'My Article Title'
    echo $result['link'];   // 'https://example.com/my-article-title'
    echo $result['finder']; // 'www.bing.com' or 'www.google.com'
}

ArticleFinder::find() returns array<string, string> on success or false when no match is found across the whole chain.

Dependency injection

use Vsimke\ArticleFinder\ArticleFinder;
use Vsimke\ArticleFinder\FinderParameter;
use Vsimke\ArticleFinder\Scraper\HQueryScraper;

class ArticleOnlineChecker
{
    public function __construct(private readonly ArticleFinder $finder) {}

    public function check(string $site, string $title): array|false
    {
        return $this->finder->find([
            FinderParameter::SITE  => $site,
            FinderParameter::TITLE => $title,
        ]);
    }
}

// Wire it up
$checker = new ArticleOnlineChecker(
    ArticleFinder::create(new HQueryScraper())
);

Scraper options

Pass a custom ClientInterface or override the config array to control transport:

use GuzzleHttp\Client;
use Vsimke\ArticleFinder\Scraper\HQueryScraper;

// Custom Guzzle client (e.g. with a proxy)
$client  = new Client(['proxy' => 'socks5://127.0.0.1:1080']);
$scraper = new HQueryScraper($client);

// Override User-Agent
$scraper = new HQueryScraper(config: [
    'headers' => [
        'User-Agent' => 'MyBot/1.0',
    ],
]);

Custom finder chain

Build your own chain by extending Finder and wiring it with setFinder():

use Vsimke\ArticleFinder\Finders\Finder;

class DuckDuckGoFinder extends Finder
{
    public function find(array $parameters): array
    {
        // ... scrape DuckDuckGo ...

        if ($article['link'] ?? null) {
            return $article;
        }

        return parent::find($parameters); // delegate to next in chain
    }
}

$ddg    = new DuckDuckGoFinder();
$google = new GoogleArticleFinder($scraper);
$ddg->chain($google);

$finder->setFinder($ddg);

How it works

ArticleFinder::find()
  └─ BingArticleFinder::find()        ← queries www.bing.com
       ├─ match found → return result
       └─ no match    → GoogleArticleFinder::find()   ← queries www.google.com
                          ├─ match found → return result
                          └─ no match    → []  →  ArticleFinder returns false

A result is considered a match when similar_text() similarity between the SERP title and the search title exceeds 70%.

Note on fragility: SERP markup changes regularly. The parser fixture tests in tests/Unit/ are the safety net — update the fixtures if Bing or Google changes their HTML structure.

Development

Run tests

./vendor/bin/pest

Static analysis

./vendor/bin/phpstan analyse

Code style (PSR-12)

# Check only
./vendor/bin/pint --test

# Fix
./vendor/bin/pint

Rector

# Dry run
./vendor/bin/rector process --dry-run

# Apply
./vendor/bin/rector process

Release

.github/release.sh patch   # 1.2.3 → 1.2.4  (default)
.github/release.sh minor   # 1.2.3 → 1.3.0
.github/release.sh major   # 1.2.3 → 2.0.0

The script auto-detects the latest vX.Y.Z tag, bumps the requested segment, prompts for confirmation, then tags and pushes.

License

MIT — see LICENSE.