PHPackages                             osmuhin/html-meta - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [Parsing & Serialization](/categories/parsing)
4. /
5. osmuhin/html-meta

ActiveLibrary[Parsing & Serialization](/categories/parsing)

osmuhin/html-meta
=================

Parses website metadata such as titles, favicons and others

1.1.0(1y ago)113MITPHPPHP >=8.2CI passing

Since Jan 14Pushed 11mo ago1 watchersCompare

[ Source](https://github.com/osmuhin/html-meta)[ Packagist](https://packagist.org/packages/osmuhin/html-meta)[ Docs](https://github.com/wischerdson/html-meta)[ RSS](/packages/osmuhin-html-meta/feed)WikiDiscussions master Synced 1mo ago

READMEChangelog (4)Dependencies (7)Versions (6)Used By (0)

 [![HTML meta logo](https://raw.githubusercontent.com/wischerdson/html-meta/refs/heads/master/docs/logo.svg)](https://raw.githubusercontent.com/wischerdson/html-meta/refs/heads/master/docs/logo.svg)

 [![Tests status](https://github.com/wischerdson/html-meta/actions/workflows/tests.yml/badge.svg)](https://github.com/wischerdson/html-meta/actions/workflows/tests.yml/badge.svg) [![Total Downloads](https://camo.githubusercontent.com/f150c1851c065ed8666a30a51ddb3b1327ec506544cf5881980530abf9933e33/68747470733a2f2f706f7365722e707567782e6f72672f6f736d7568696e2f68746d6c2d6d6574612f642f746f74616c2e737667)](https://packagist.org/packages/osmuhin/html-meta) [![License](https://camo.githubusercontent.com/72124643f74f9bbfe1324ae8daa554f2f356c3a59faee20649644bf1777a6b10/68747470733a2f2f706f7365722e707567782e6f72672f6f736d7568696e2f68746d6c2d6d6574612f6c6963656e73652e737667)](https://camo.githubusercontent.com/72124643f74f9bbfe1324ae8daa554f2f356c3a59faee20649644bf1777a6b10/68747470733a2f2f706f7365722e707567782e6f72672f6f736d7568696e2f68746d6c2d6d6574612f6c6963656e73652e737667)

**HTML Meta** is a PHP package for parsing website metadata, such as titles, favicons, OpenGraph tags and others.

---

Installation
------------

[](#installation)

To install the package via Composer, run:

```
composer require osmuhin/html-meta
```

Note

Ensure that the vendor/autoload.php file is required in your code to enable the autoloading mechanism provided by [Composer](https://getcomposer.org/doc/01-basic-usage.md).

Basic usage
-----------

[](#basic-usage)

### Parsing Metadata from URL

[](#parsing-metadata-from-url)

```
use Osmuhin\HtmlMeta\Crawler;

$meta = Crawler::init(url: 'https://google.com')->run();

echo $meta->title; // Google
```

### Parsing Metadata from Raw HTML

[](#parsing-metadata-from-raw-html)

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

```
$html = run();

$icon = $meta->favicon->icons[0];

echo $icon->url // https://google.com/favicon.ico
```

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

### Using a Custom Request Object

[](#using-a-custom-request-object)

Under the hood, the [GuzzleHttp](https://docs.guzzlephp.org/en/stable/) library is used to get html, so you can create your own request object and pass it as a `$request` parameter:

```
$request = new \GuzzleHttp\Psr7\Request('GET', 'https://google.com');

$meta = Crawler::init(request: $request)->run();
```

All properties of the `meta` object are described [**here**](/docs/meta-object-properties.md).

Configuration
-------------

[](#configuration)

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

```
$crawler = Crawler::init(url: 'https://google.com');
$crawler->config
    ->dontProcessUrls()
    ->dontUseTypeConversions()
    ->processUrlsWith('https://yandex.ru')
    ->dontUseDefaultDistributorsConfiguration();
```

SettingDescription`dontProcessUrls()`Disables the conversion of relative URLs to absolute URLs.`dontUseTypeConversions()`Disables automatic type conversions (e.g., string to int):

 ``
 Using type conversions: `int(630)`
 Disabled type conversions: `string(3) "630"`

 ``
 Using type conversions: `null`
 Disabled type conversions: `string(5) "630.5"``processUrlsWith(string $url)`Sets a base URL for resolving relative paths (automatically enables URL processing).`dontUseDefaultDistributorsConfiguration()`Disables the default distributor configuration.Core concepts
-------------

[](#core-concepts)

### The Crawler object

[](#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:

        ```
        $crawler->xpath = '//html|//html/head/link|//html/head/meta|//html/head/title';
        ```

        > You are free to overwrite xpath property;
    - passes the parsed elements to the distributor stack;
    - the found HTML element is pass to the distributor stack
        If the HTML element passed the conditions, then its value is written to [DTO (Data Transfer Object)](https://en.wikipedia.org/wiki/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

[](#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:

```
public function canHandle(): bool
{

}

public function handle(): void
{

}
```

`canHandle()` - 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.

`handle()` - Distributes the HTML element data by DTOs according to its own rules.

You can view the structure of the simplest [TitleDistributor](/src/Distributors/TitleDistributor.php) distributor:

```
class TitleDistributor extends \Osmuhin\HtmlMeta\Distributors\AbstractDistributor
{
    public function canHandle(): bool
    {
        return $this->el->name === 'title';
    }

    public function handle(): void
    {
        $this->meta->title = $this->el->innerText;
    }
}
```

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

```
use Osmuhin\HtmlMeta\Distributors\TitleDistributor;

class MyCustomTitleDistributor extends TitleDistributor
{
    public function handle(): void
    {
        $this->meta->title = 'Prefix for title ' . $this->el->innerText;
    }
}
```

replace original `TitleDistributor` in initial configuration:

```
$crawler = Crawler::init(url: 'https://google.com');
$crawler->distributor->setSubDistributor(
    MyCustomTitleDistributor::class,
    TitleDistributor::class
);

$meta = $crawler->run();
$meta->title === 'Prefix for title Google';
```

... or even overwrite the distributors tree completely:

```
$crawler = Crawler::init(url: 'https://google.com');
$crawler->xpath = '//html/head/title';
$crawler->config->dontUseDefaultDistributorsConfiguration();

$crawler->distributor->useSubDistributors(
    MyCustomTitleDistributor::init($crawler->container)
);

$meta = $crawler->run();
```

Default distributors configuration```
$crawler->distributor->useSubDistributors(
    \Osmuhin\HtmlMeta\Distributors\HtmlDistributor::init(),
    \Osmuhin\HtmlMeta\Distributors\TitleDistributor::init(),
    \Osmuhin\HtmlMeta\Distributors\MetaDistributor::init()->useSubDistributors(
        \Osmuhin\HtmlMeta\Distributors\HttpEquivDistributor::init(),
        \Osmuhin\HtmlMeta\Distributors\TwitterDistributor::init(),
        \Osmuhin\HtmlMeta\Distributors\OpenGraphDistributor::init()
    ),
    \Osmuhin\HtmlMeta\Distributors\LinkDistributor::init()->useSubDistributors(
        \Osmuhin\HtmlMeta\Distributors\LinkRelDistributor::init()->useSubDistributors(
            \Osmuhin\HtmlMeta\Distributors\FaviconDistributor::init()
        )
    )
);
```

Contributing
------------

[](#contributing)

Thank you for considering contributing to this package! Please refer to the [Contributing Guidelines](CONTRIBUTING.md) for more details.

You can contact me or just come say hi in Telegram: [@wischerdson](https://t.me/wischerdson)

License
-------

[](#license)

This package is open-sourced software licensed under the [MIT license](LICENSE.md).

###  Health Score

31

—

LowBetter than 68% of packages

Maintenance47

Moderate activity, may be stable

Popularity7

Limited adoption so far

Community7

Small or concentrated contributor base

Maturity54

Maturing project, gaining track record

 Bus Factor1

Top contributor holds 100% of commits — single point of failure

How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window.

**Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores.

**Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement.

**Maturity (30%)** — Project age, version count, PHP version support, and release stability.

###  Release Activity

Cadence

Every ~3 days

Total

4

Last Release

479d ago

### Community

Maintainers

![](https://www.gravatar.com/avatar/078fd36ee6333a8a43602bd8663905fed96afc13afef874b2a1a32251ffa8c90?d=identicon)[osmuhin](/maintainers/osmuhin)

---

Top Contributors

[![osmuhin](https://avatars.githubusercontent.com/u/51699863?v=4)](https://github.com/osmuhin "osmuhin (84 commits)")

---

Tags

html-metameta-tagsparsing-libraryphpseo-tools

###  Code Quality

TestsPHPUnit

### Embed Badge

![Health badge](/badges/osmuhin-html-meta/health.svg)

```
[![Health](https://phpackages.com/badges/osmuhin-html-meta/health.svg)](https://phpackages.com/packages/osmuhin-html-meta)
```

###  Alternatives

[silverstripe/framework

The SilverStripe framework

7213.5M2.5k](/packages/silverstripe-framework)[spatie/laravel-sitemap

Create and generate sitemaps with ease

2.6k14.6M107](/packages/spatie-laravel-sitemap)[drupal/core

Drupal is an open source content management platform powering millions of websites and applications.

19462.3M1.3k](/packages/drupal-core)[drupal/core-recommended

Locked core dependencies; require this project INSTEAD OF drupal/core.

6939.5M343](/packages/drupal-core-recommended)[daux/daux.io

Documentation generator that uses a simple folder structure and Markdown files to create custom documentation on the fly

825191.0k1](/packages/daux-dauxio)[open-dxp/opendxp

Content & Product Management Framework (CMS/PIM)

7310.3k29](/packages/open-dxp-opendxp)

PHPackages © 2026

[Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)