Download the PHP package ioodev/elephscraper without Composer

🐘 ElephScraper

ElephScraper is a lightweight, PHP-native web scraping toolkit, built on top of Guzzle and Symfony DomCrawler. This library provides a clean and powerful interface for extracting HTML, metadata, and structured data from any web page — or from an HTML string you already have yourself.

Fast. Clean. Eleph-style scraping. 🐘⚡

Part of the ioodev scraper ecosystem alongside SnakyScraper (Python) and NodeScraper (Node.js) — three libraries with a similar API philosophy for three different language ecosystems.

Moving from riodevnet/elephscraper? See Migrating from v1.0 below — the namespace and package name changed in v1.1.0.

📋 Table of Contents

• Features
• Installation
• Basic Usage
• Error Handling
• Request Options (Headers, Timeout, Proxy, etc.)
• Full API Reference
  • Page Metadata
  • Open Graph & Twitter Card
  • Heading & Text
  • List
  • Images
  • Links
  • Custom DOM Filter
  • Low-Level Access
• Project Structure
• Testing & Quality Tools
• Migrating from v1.0 (riodevnet/elephscraper)
• Contributing
• Changelog
• License

🚀 Features

• ✅ Extract metadata: title, description, keywords, author, charset, canonical, and more
• ✅ Full support for Open Graph, Twitter Card, CSRF token, and HTTP-equiv headers
• ✅ Extract headings, paragraphs, images, lists, and links — complete with rel, nofollow, etc. details
• ✅ Flexible filter() method with tag/class/ID-based selectors
• ✅ Can load from a URL or directly from an HTML string (fromHtml()) — no HTTP request needed, great for testing
• ✅ Never throws a fatal error — fetch/parse failures can always be checked via isValid() / getError(), or optionally thrown as an exception (throwOnError)
• ✅ Custom headers, timeout, proxy, cookies, and other Guzzle options via the $options parameter
• ✅ Safe return types: string, array, or associative array — always null (never a crash) when data isn't found
• ✅ Strict types & full type-hints (PHP 8.0+) for a safer development experience
• ✅ Built on top of Guzzle + Symfony DomCrawler + CssSelector
• ✅ PHPUnit test suite, PHPStan level 6, and PHP-CS-Fixer (PSR-12) already set up

📦 Installation

Install via Composer:

Requires PHP 8.0 or newer.

🛠️ Basic Usage

Load from an HTML string (no HTTP request)

Useful for unit tests, or when you already have HTML from another source (headless browser, file cache, webhook payload, etc.):

⚠️ Error Handling

By default, the constructor never throws an exception — this is intentional, so a single broken URL in the middle of a batch/loop process doesn't halt the entire process. Always check one of:

If you prefer a "fail-fast" model with try/catch, set throwOnError:

All extraction methods (title(), h1(), links(), etc.) are always safe to call even if the document fails to load — they will return null (never a crash), including edge cases from previous versions that had a fatal error bug under this condition.

⚙️ Request Options (Headers, Timeout, Proxy, etc.)

The constructor's second parameter is an options array passed directly to Guzzle request(), merged with the defaults (timeout: 10, connect_timeout: 5, redirects followed, browser User-Agent):

You can also inject your own Guzzle Client instance (for example, for testing with a mock handler):

📚 Full API Reference

🔹 Page Metadata

🔹 Open Graph & Twitter Card

🔹 Heading & Text

🔹 List

🔹 Images

🔹 Links

🔍 Custom DOM Filter

filter() is the most flexible method — ideal for scraping custom HTML structures like product lists, article cards, data tables, etc.

Filter multiple elements at once:

Get raw HTML from a single section:

Selector rules for extract:

• Tag name: h2, p, span, etc.
• Class: .className (automatically matches even if the element has multiple classes)
• ID: #idName

Result array keys always follow the original selector string (e.g. result['.title']). Values in attributes (for class/id/other attributes) are safe from quote characters — they won't break the selector as they could in previous versions.

Returns null if the document fails to load, or if no matching elements are found.

🔧 Low-Level Access

For cases not covered by the built-in methods, you can drop straight down to Symfony DomCrawler:

🗂 Project Structure

This separation is intentional, to make further development easier:

• src/Exceptions/ — all exception classes, so library consumers can catch (ScraperException $e) specifically without catching generic PHP errors.
• src/Support/ — internal helpers (currently CssSelectorBuilder) kept separate from the main class so they can be unit-tested independently and reused if more selector features are added later.
• tests/Unit/ — mirrors the src/ namespace structure, one test file per class.
• examples/ — runnable scripts (php examples/basic-usage.php) for quick onboarding without needing to read the whole README.

🧪 Testing & Quality Tools

The test suite covers metadata extraction, heading/paragraph/list extraction, images & links (including the edge case of relative links without rel), filter() (single & multiple, including values containing quote characters), and behavior when the document fails to load (must return null, not crash).

🔁 Migrating from v1.0 (riodevnet/elephscraper)

Version 1.1.0 changes the namespace and package name following the username rename from riodevnet to ioodev. Migration steps:

Then find-and-replace throughout your project:

All method names remain exactly the same — there are no signature changes to any public method that existed in v1.0, so you only need to update the use statement. See CHANGELOG.md for the full list of changes, new features, and bug fixes.

🤝 Contributing

Found a bug? Want to add a feature? Open an issue or submit a pull request at github.com/ioodev/elephscraper!

Before opening a PR, please run:

📝 Changelog

See CHANGELOG.md for the full list of changes in each version.

📄 License

MIT License © 2025–2026 — ioodev

🔗 Related Libraries

• Guzzle
• Symfony DomCrawler
• Symfony CssSelector
• SnakyScraper — Python version
• NodeScraper — Node.js version

💡 Why ElephScraper?

ElephScraper is your trusty PHP elephant — strong, smart, and always ready to extract exactly the data you need. 🐘