Download the PHP package osmuhin/html-meta without Composer

HTML Meta is a PHP package for parsing website metadata, such as titles, favicons, Open Graph tags, JSON-LD and others.

Installation

To install the package via Composer, run:

[!NOTE] Ensure that the vendor/autoload.php file is required in your code to enable the autoloading mechanism provided by Composer.

Basic usage

Parsing Metadata from URL

Parsing Metadata from Raw HTML

Instead of URL, you can parse metadata from Raw HTML passing it as a string:

Always pass the url parameter when using raw HTML to resolve relative paths correctly.

Relative URL resolution follows RFC 3986: a base without a trailing slash treats the last path segment as a file. Use a trailing slash (e.g. https://example.com/dir/) when the base should act as a directory.

Using a Custom Request Object

Under the hood, the GuzzleHttp library is used to get html, so you can create your own request object and pass it as a $request parameter:

[!WARNING] When crawling URLs from untrusted input, be aware of SSRF risks (the crawler follows redirects by default). Prefer injecting a hardened Guzzle client via setGuzzleClient() (timeouts, allowlists, disabled private networks) instead of passing raw user URLs to Crawler::init(url: ...).

All properties of the meta object are described here.

Extended Open Graph namespaces

The crawler supports extended Open Graph namespaces in addition to base og:* tags:

• article:* -> $meta->openGraph->article
• book:* -> $meta->openGraph->book
• profile:* -> $meta->openGraph->profile

Unknown base og:* keys are preserved in $meta->openGraph->other.

JSON-LD

The crawler collects every <script type="application/ld+json"> tag (in head or body).

• Raw payloads and decode status: $meta->jsonLd->scripts
• Flattened entities from objects, JSON arrays, and @graph: $meta->jsonLd->nodes

Invalid JSON is kept in scripts with valid = false and does not produce nodes. Node url is resolved like other URLs unless dontProcessUrls() is set.

Configuration

You can customize the crawler’s behavior using its configuration methods:

Core concepts

The Crawler object

The main interaction happens through the $crawler object of type \Osmuhin\HtmlMeta\Crawler.

1. Initialization: Configure the crawler before run() calling.

2. Execution: After run() calling, the crawler performs the following steps:

   • fetches the HTML string from the URL (if raw HTML is not provided).
     The priority of the parameters, if they are more than 1 is following: string $html ➡ \GuzzleHttp\Psr7\Request $request ➡ string $url;

   • parses the HTML using the configured xpath:

     You are free to overwrite xpath property;

   • passes the parsed elements to the distributor stack;

   • the found HTML element is passed to the distributor stack
     If the HTML element passed the conditions, then its value is written to DTO (Data Transfer Object) of the type \Osmuhin\HtmlMeta\Contracts\Dto;

   • after parsing the HTML string, the root DTO \Osmuhin\HtmlMeta\Dto\Meta is formed in output.

Distributors

A Distributor validates HTML elements and distributes their data into DTOs.

Distributor must implement the interface \Osmuhin\HtmlMeta\Contracts\Distributor and has 2 main methods:

• Checks whether the distributor can handle the current element. If returns true, then all sub-distributors are polled, and then the handle method is called.

• Distributes the HTML element data by DTOs according to its own rules.

You can view the structure of the simplest TitleDistributor distributor:

You are free to replace some kind distributor of your own, example:

replace original TitleDistributor in initial configuration:

... or even overwrite the distributors tree completely:

Contributing

Thank you for considering contributing to this package! Please refer to the Contributing Guidelines for more details.

You can contact me or just come say hi in Telegram: @wischerdson

License

This package is open-sourced software licensed under the MIT license.