Product Decisions This Supports
- Reader Mode / "clean view" — the strongest justification. A PHP-native, Apache-2.0 implementation of the Readability algorithm lets you ship a decluttered article view, an ad-light "lite" page, or a save-for-later payload without a Node sidecar or a third-party extraction API. Frame it on the roadmap as content consumption quality, not as an infrastructure project.
- Full-text RSS / content syndication. If you ingest feeds that only ship summaries, this is the cheapest path to "show the whole article in our reader" — the exact origin use case of the upstream full-text-rss fork this was extracted from.
- AI/RAG ingestion hygiene. Boilerplate removal before chunking directly improves retrieval quality and cuts embedding/token spend: you embed the article, not the nav bar, cookie banner, and "related stories" rail. This is often the fastest way to justify the dependency because it shows up as cost reduction, not a new feature.
- Email digests, newsletters, preview cards. Populate a
getTitle() / getContent() payload into a Blade template or link-preview card without maintaining hand-written per-site CSS selectors.
- Content-quality scoring. Comparing extracted body length against raw HTML size is a cheap, useful signal for thin/aggregator/duplicate pages — feeds ranking heuristics, spam scoring, or "is this link worth unfurling?" decisions.
- A build-vs-buy decision it resolves cheaply. The realistic alternatives are (a) a SaaS extraction API, (b) a Node/Symfony sidecar running Mozilla Readability, or (c) vendoring a parser. This package collapses (a)–(c) into
composer require j0k3r/php-readability, which is a decision you can de-risk in a one-day spike instead of an architecture review.
- Roadmap sequencing. Treat it as a validation instrument: prove demand for reader/AI-quality features with a thin slice, and only invest in a first-party extraction service if the metrics hold.
When to Consider This Package
Adopt when:
- The backend is Laravel/PHP and you do not want a second runtime, another deployable, or another vendor in the content path.
- You already have the HTML in hand — server-rendered articles, blogs, news, docs, or HTML you fetched yourself. The library is parsing only; fetching is yours (Guzzle/HTTP client).
- Your volumes and latency budget fit CPU-bound parsing. Route every call through a queued job (Horizon), cache aggressively (key on URL + content hash), and measure p95 — do not call it synchronously in a request cycle.
- You can install
ext-tidy, ext-dom, and ext-mbstring. Tidy materially improves results on malformed real-world HTML; the libxml fallback works but is the explicitly-documented second-best path. This is an infrastructure acceptance criterion, not a detail — check it against your shared-hosting/container images before committing.
- Permissive licensing and fast procurement matter. Apache-2.0 clears legal without a contract; a SaaS API does not.
- You need the article title and body — not structured fields. That is the whole contract.
Look elsewhere when:
- Targets are JS-rendered/SPA. This parses HTML strings; you would need a headless browser (Browsershot/Puppeteer) first, and at that point the extraction engine choice is secondary.
- You need high-accuracy structured data — author, publish date, schema.org entities, paywall state. Pair it with a dedicated extractor rather than bending this one.
- Accuracy is a revenue lever and you need an SLA, support, or per-language tuning. Benchmark a commercial API (Diffbot, Postlight/Mercury-style services) against a golden set before picking the free option.
- You have no appetite for patching. The README itself says the code is "really hard to understand / read." Budget for a maintainer who can read a parser.
- Adoption risk is a real consideration, and it should be stated plainly: ~184 stars, zero listed dependents on Packagist, a very small maintainer pool, two maintained branches (1.x and 2.x), and PHP ≥7.4 on 2.x. Mitigate by pinning the exact version, snapshotting the source in your VCS, and wrapping it behind your own
ContentExtractor interface so the engine is swappable in an afternoon.
How to Pitch It (Stakeholders)
Executives (one paragraph): This is a small, free, permissively-licensed PHP library that strips navigation, ads, and boilerplate out of a web page and returns the article title and body. It requires no vendor contract, no new service, and no new language runtime — it drops into the Laravel stack we already run. The cost of finding out whether reader mode, cleaner email digests, or better AI answers are worth building is a one-to-two-day spike, and the downside is capped because we isolate it behind our own interface and can replace it with a commercial API without touching product code. Recommended ask: fund the spike, not the platform.
Engineering (the actual contract): One namespaced class, composer require, new Readability($html, $url) → init() → getTitle()/getContent(), with an optional PSR-3 logger you can point at Monolog to debug parse failures. It is actively maintained (regular releases through 2026, CI green on PHP 8.4, 2.0 realigned with Mozilla Readability, and loadHtml() is public as of 2.0.9 so you can parse once and extract repeatedly). Our integration plan: a ReadabilityServiceProvider binding a ContentExtractor interface, execution inside a queued job, results cached by content hash, raw and extracted HTML both persisted so we can build a golden-set regression suite. That suite is the real deliverable — it gives us a number for extraction success rate and recall, which is what turns "should we keep this?" into a data question instead of a debate. Pin the minor version, vendor the source, and require ext-tidy in the container image so production and local behave identically.
Success metrics to agree up front: extraction success rate, human-judged content recall (does it find the article body and only the article body), p95 parse latency, cost per 1,000 pages versus the SaaS quote, and — for the AI use case — retrieval quality and token spend before/after boilerplate removal.