gnews-unwrap is a PHP library that turns Google News wrapper links back into the publisher’s own article URLs. It also gives you an outlet key and an article key, so attribution and duplicate checks work on the real source. It is for anyone who ingests Google News feeds. The code is at https://github.com/IndianOpinion/gnews-unwrap, under the MIT licence, and v0.1.0 was released on 12 November 2026.
It has no runtime dependencies and needs PHP 8.1 or later. We wrote it from scratch. It is independent of and not affiliated with any third-party plugin it integrates with.
Google News feeds do not link to articles. Each item links to a Google wrapper page. A system that stores that link as the item’s source gets three things wrong at once:
A smaller fault sits beside these. Outlets serve one article from several hosts, such as www., amp. and m.. Counted as raw host strings, one outlet counts twice. Rows already stored with wrapper links also need repairing, which the library supports.
Result that says what was tried, what it cost and, when it fails, a reason code.www, amp, m and mobile labels stripped, never past the registrable domain) and an article key from a URL (tracking parameters, fragments and trailing slashes dropped).not_google_news, and no request. It is safe to run every stored URL through it.For each link the Unwrapper runs a chain of methods. The names are cache, query_param, offline_decode, batch_execute, http_redirect and html_parse, and each can be switched off.
url or q parameter, read it. Nested redirectors unwrap up to three levels.BatchExecute. It reports format_changed when the answer changes shape.Location headers between Google hosts, and stop at the first hop that leaves Google. The publisher is never requested.Each link’s method chain is a PHP generator that yields a request when it needs the network. resolve() drives one generator. resolveMany() can drive several through curl_multi. Both paths therefore share one piece of resolution logic.
The usage from the README:
$unwrapper = new Unwrapper();
$result = $unwrapper->resolve($link);
if ($result->resolved) {
$url = $result->output; // publisher URL
$outlet = $result->outletKey;
$key = $unwrapper->articleKey($url);
} else {
// $result->output is the wrapper, $result->reason says why.
}
Unwrap at ingest, before any hash, key, outlet count or dedup check. Store the resolved URL, and do not re-resolve on read.
rate_limited, timeout and circuit_open are never cached.The reviewer called the build solid and fixed these directly before the merge:
filter_var flags, whose coverage differs by PHP version. It now uses explicit IPv4 and IPv6 range tables, checks embedded IPv4 addresses in mapped, NAT64 and 6to4 forms, and looks up AAAA records as well as A records. Before, a host with only a loopback AAAA record passed. Hops with userinfo or a backslash are now refused, because parsers disagree on which host they reach.sendMany() threw escaped resolveMany(). It now fails that round’s requests with network_error.format_changed or signature_missing, and the link comes back unresolved, not wrong. Complying with Google’s terms is your responsibility, and you can switch the method off.consent_wall. A live check on 11 November 2026 hit this. Run network resolution from a host outside those regions.pauseMs and keep concurrency low.Test status: this is v0.1.0. At review, 196 tests ran on PHP 8.3 against recorded fixtures and a fake transport (no live site), with PHPStan level 8 and phpcs clean. A live smoke test is opt-in. The README carries a CI badge, but the workflow has not run on GitHub yet, because the token lacked the scope to push it, so PHP 8.1 and 8.2 are untested. There are no open issues.
The package is not on Packagist yet, so first add a Composer vcs repository entry for https://github.com/IndianOpinion/gnews-unwrap.
composer require indianopinion/gnews-unwrap
It needs PHP 8.1 or later. ext-curl is used when present, with a fallback to PHP streams, and ext-intl is used for IDN hosts when present. Without Composer, require bootstrap.php from a release download.