README

A framework-agnostic meta web-search client for PHP. Point it at several search-API keys and it gives you one clean interface with automatic failover — if one provider is down, rate-limited, or returns nothing, the next one covers. Results are unfiltered by default (safe-search off); you opt back into filtering when you want it.

Supported providers: Serper, Tavily, SearchApi.io, Scavio, Firecrawl, ScrapingBee. All six have free tiers.

This is web search (the open internet via search APIs). For searching your own indexed data (Elasticsearch, Meilisearch, …) see jarir-ahmed/search.

Install

composer require jarir-ahmed/uncensored-search

Requires PHP 7.4+ and ext-curl.

Quick start

use JarirAhmed\UncensoredSearch\UncensoredSearch;

// Load whatever keys you have — only configured providers are used.
$search = UncensoredSearch::fromKeys([
    'serper' => 'xxxx',
    'tavily' => 'tvly-xxxx',
    // 'searchapi' => '...', 'scavio' => '...', 'firecrawl' => '...', 'scrapingbee' => '...',
]);

$results = $search->search('open source vector database');

echo $results->provider();   // "serper" (whichever one answered)
foreach ($results as $hit) {
    echo $hit->title() . "\n";
    echo $hit->url() . "\n";
    echo $hit->snippet() . "\n\n";
}

Loading keys

UncensoredSearch::fromKeys([...]);                 // inline array
UncensoredSearch::fromFile('uncensored_keys.txt'); // KEY=value / .env style file
UncensoredSearch::fromEnv();                        // SERPER_API_KEY, TAVILY_API_KEY, ...

Both naming styles are accepted in arrays and files: provider names (serper) or env-var names (SERPER_API_KEY).

Two search modes

// FAILOVER (default) — try providers in order, first with results wins.
// Cheapest: one provider's quota per query.
$set = $search->search('php 8.4 release date');

// AGGREGATE — query every provider, merge, dedupe by URL. Max coverage,
// spends multiple quotas per call.
$set = $search->searchAll('php 8.4 release date');
echo implode('+', $set->providers()); // e.g. "serper+tavily+firecrawl"

The Query object

Safe-search is off by default. Everything is fluent and immutable.

use JarirAhmed\UncensoredSearch\Query;

$q = Query::create('climate data')
    ->withLimit(20)
    ->withSafeSearch(true)   // re-enable filtering (providers that support it)
    ->withCountry('us')
    ->withLanguage('en');

$search->search($q);

Working with results

$set = $search->search('something');

$set->count();        // int  (ResultSet is Countable + iterable)
$set->isEmpty();      // bool
$set->first();        // ?Result
$set->provider();     // ?string — who served it
$set->providers();    // string[] — all contributors (aggregate mode)
$set->elapsedMs();    // float
$set->errors();       // array<provider,message> — why others were skipped
$set->toArray();      // array of plain rows

foreach ($set as $r) {
    $r->title(); $r->url(); $r->snippet();
    $r->source();   // provider name
    $r->position(); // ?int  rank
    $r->score();    // ?float (Tavily)
    $r->raw();      // untouched provider row
}

search() never throws on provider failure — failures land in errors() and an all-failed run simply returns an empty set you can inspect.

Choosing / ordering providers

// Restrict and reorder; tries tavily first, then serper.
$search->only(['tavily', 'serper'])->search('...');

Default failover order (best free quota / quality first): serper → tavily → searchapi → scavio → firecrawl → scrapingbee.

Command-line tool

php examples/cli.php "open source vector database"
php examples/cli.php --all --limit=5 "best php testing framework"
php examples/cli.php --safe "kids science fair ideas"
php examples/cli.php --keys=/path/to/keys.txt "php 8.4"

Provider reference

Get keys from each provider's site, drop them in a KEY=value file, and never commit it — .gitignore already excludes *.env / *keys.txt.

Extending

Implement Contracts\ProviderInterface (or extend Providers\AbstractProvider for the shared mapping/decoding helpers) and pass your provider into the UncensoredSearch constructor. The failover engine and aggregator work against the interface, so no core changes are needed.

Testing

composer test

Tests use a fake HTTP client fed with real captured provider JSON, so no network or API quota is touched. 31 tests, 86 assertions, all green.

License

MIT © Jarir Ahmed