PHP Html Parser

https://github.com/paquettg/php-html-parser
Admin
PHP Html Parser is a simple and flexible HTML DOM parser that allows developers to select and...
Tokens:105,485
Snippets:770
Trust Score:6.7
License:MIT
Update:1 week ago
Show doc for...
Tokens:
Raw
### Install with Composer

Source: https://github.com/paquettg/php-html-parser/blob/master/README.md

Install the latest version of the php-html-parser package using Composer. Supports PHP 7.2, 7.3, and 7.4.

```bash
$ composer require paquettg/php-html-parser
```

--------------------------------

### mount usage example

Source: https://github.com/paquettg/php-html-parser/blob/master/_autodocs/api-reference/static-dom.md

Mounts the facade and uses the alias to load HTML and find nodes. The alias 'Dom' is created by default.

```php
use PHPHtmlParser\StaticDom;

StaticDom::mount(); // alias 'Dom'

Dom::loadStr('<div class="all"><p>Hi</p></div>');
$nodes = Dom::find('.all');
```

--------------------------------

### Example: chaining setters on Options

Source: https://github.com/paquettg/php-html-parser/blob/master/_autodocs/api-reference/options.md

Shows how to instantiate Options and chain setters to configure strict mode, whitespace text node handling, and line break preservation.

```php
use PHPHtmlParser\Options;

$opts = (new Options())
    ->setStrict(true)
    ->setWhitespaceTextNode(false)
    ->setPreserveLineBreaks(true);
```

--------------------------------

### Full facade workflow example

Source: https://github.com/paquettg/php-html-parser/blob/master/_autodocs/api-reference/static-dom.md

Mounts the facade, loads a URL, counts anchor tags, then unloads. After unload, calling Dom::find would throw NotLoadedException.

```php
use PHPHtmlParser\StaticDom;

StaticDom::mount();

Dom::loadFromUrl('http://example.com');
echo count(Dom::find('a'));

Dom::unload();
// Dom::find('a'); // would throw NotLoadedException
```

--------------------------------

### Error-handling example

Source: https://github.com/paquettg/php-html-parser/blob/master/_autodocs/api-reference/dom.md

Demonstrates catching LogicalException when loadFromFile fails to read a file, and NotLoadedException when calling find before loading content. Shows the exact exception messages.

```php
use PHPHtmlParser\Dom;
use PHPHtmlParser\Exceptions\NotLoadedException;

$dom = new Dom();
try {
    $dom->loadFromFile('/missing/path.html');
} catch (\PHPHtmlParser\Exceptions\LogicalException $e) {
    echo 'Could not read file: ' . $e->getMessage();
}

// Calling any query method before a load throws NotLoadedException:
try {
    $dom->find('a');
} catch (NotLoadedException $e) {
    echo 'Load content first: ' . $e->getMessage();
}
```

--------------------------------

### Selector usage example

Source: https://github.com/paquettg/php-html-parser/blob/master/_autodocs/api-reference/selector.md

Example of using the Selector class directly to find nodes matching a CSS selector. Loads HTML into a Dom, creates a Selector for 'p.x', and finds matches on the root node. Outputs the count and the text of the first match.

```php
use PHPHtmlParser\Dom;
use PHPHtmlParser\Selector\Selector;

$dom = new Dom();
$dom->loadStr('<div class="all"><p>a</p><p class="x">b</p></div>');

$selector = new Selector('p.x');
$matches  = $selector->find($dom->root);
echo count($matches);         // 1
echo $matches[0]->text;       // 'b'
```

--------------------------------

### StaticDom::mount

Source: https://github.com/paquettg/php-html-parser/blob/master/README.md

Mounts a static facade for the Dom object, enabling static calls to Dom methods.

```APIDOC
## StaticDom::mount

### Description
Mounts a static facade for the Dom object, enabling static calls to Dom methods.

### Method
mount

### Example
```php
PHPHtmlParser\StaticDom::mount();
```
```

--------------------------------

### Error-handling example

Source: https://github.com/paquettg/php-html-parser/blob/master/_autodocs/api-reference/collection.md

Creates an empty Collection and catches EmptyCollectionException when accessing the text property, printing the exception message.

```php
$empty = new \PHPHtmlParser\Dom\Node\Collection();
try {
    echo $empty->text;
} catch (EmptyCollectionException $e) {
    echo 'Empty: ' . $e->getMessage();
}
```

--------------------------------

### Constructor usage example

Source: https://github.com/paquettg/php-html-parser/blob/master/_autodocs/api-reference/dom.md

Creates a Dom instance, loads an HTML string, and uses a CSS selector to extract text. The find('a')[0]->text returns 'click here'.

```php
use PHPHtmlParser\Dom;

$dom = new Dom();
$dom->loadStr('<div class="all"><p>Hey bro, <a href="google.com">click here</a></p></div>');
echo $dom->find('a')[0]->text; // "click here"
```

--------------------------------

### setOptions usage example

Source: https://github.com/paquettg/php-html-parser/blob/master/_autodocs/api-reference/dom.md

Shows how to set global options and per-load options. The global strict option applies to all loads, while the whitespaceTextNode option is only used for that specific loadStr call.

```php
use PHPHtmlParser\Dom;
use PHPHtmlParser\Options;

$dom = new Dom();
$dom->setOptions((new Options())->setStrict(true));          // global
$dom->loadStr('<html>h</html>', (new Options())->setWhitespaceTextNode(false)); // this load only
```

--------------------------------

### Discovery class find() method signature

Source: https://github.com/paquettg/php-html-parser/blob/master/_autodocs/api-reference/parser-cleaner.md

Example signature for the static find() method used by all discovery classes. Each class returns a cached singleton instance of its corresponding interface.

```php
public static function find(): CleanerInterface   // example signature; each class mirrors this shape
```

--------------------------------

### Load HTML from a file and process nodes

Source: https://github.com/paquettg/php-html-parser/blob/master/README.md

Load HTML from a file using loadFromFile, find elements by class, and access node attributes, inner HTML, and child/sibling relationships. The example uses the 'big.html' file from the tests directory.

```php
// Assuming you installed from Composer:
require "vendor/autoload.php";
use PHPHtmlParser\Dom;

$dom = new Dom;
$dom->loadFromFile('tests/data/big.html');
$contents = $dom->find('.content-border');
echo count($contents); // 10

foreach ($contents as $content)
{
	// get the class attr
	$class = $content->getAttribute('class');
	
	// do something with the html
	$html = $content->innerHtml;

	// or refine the find some more
	$child   = $content->firstChild();
	$sibling = $child->nextSibling();
}
```

--------------------------------

### Regex attribute matching with find()

Source: https://github.com/paquettg/php-html-parser/blob/master/_autodocs/api-reference/selector.md

Demonstrates using regex patterns in attribute selectors. Patterns starting with '/' are treated as raw regex. The example shows counts for different selectors: 'a[href^=http://]' matches 1, 'a[href*="example"]' matches 2, and 'a[href=/^https/]' matches 1.

```php
use PHPHtmlParser\Dom;

$dom = new Dom();
$dom->loadStr('<a href="http://example.com">h</a><a href="https://example.org">h2</a>');
echo count($dom->find('a[href^=http://]'));      // 1
echo count($dom->find('a[href*="example"]'));    // 2
echo count($dom->find('a[href=/^https/]'));      // 1  (pattern starting with '/' is a raw regex)
```

--------------------------------

### Example with a custom HTTP client

Source: https://github.com/paquettg/php-html-parser/blob/master/_autodocs/api-reference/dom.md

Shows how to pass a custom PSR-18 HTTP client to loadFromUrl. The client must implement ClientInterface. After loading, the outer HTML is echoed.

```php
use PHPHtmlParser\Dom;
use App\Services\MyClient;

$dom = new Dom();
$dom->loadFromUrl('http://google.com', null, new MyClient());
echo $dom->outerHtml;
```

--------------------------------

### Node::getAttribute

Source: https://github.com/paquettg/php-html-parser/blob/master/README.md

Gets the value of an attribute on a node. Returns the attribute value as a string.

```APIDOC
## Node::getAttribute

### Description
Gets the value of an attribute on a node. Returns the attribute value as a string.

### Method
getAttribute

### Parameters
- **name** (string) - Required - The attribute name.

### Returns
- string - The attribute value.

### Example
```php
echo $a->getAttribute('class'); // "foo"
```
```

--------------------------------

### Mount static facade and use Dom::loadFromFile and find

Source: https://github.com/paquettg/php-html-parser/blob/master/README.md

Mounts the PHPHtmlParser\StaticDom facade, then uses the static Dom class to load a file and find elements. Supports all public methods of the Dom object.

```php
PHPHtmlParser\StaticDom::mount();

Dom::loadFromFile('tests/big.hmtl');
$objects = Dom::find('.content-border');
```

--------------------------------

### Direct use of PHPHtmlParser\Content with StringToken

Source: https://github.com/paquettg/php-html-parser/blob/master/_autodocs/api-reference/content.md

Shows how to instantiate Content with an HTML string and use fastForward, copyByToken, and skipByToken to navigate and extract tokens. The example skips the '<', copies 'div' using StringToken::SLASH(), skips blanks, copies 'class' using StringToken::EQUAL(), and prints the cursor position.

```php
use PHPHtmlParser\Content;
use PHPHtmlParser\Enum\StringToken;

$content = new Content('<div class="x">text</div>');
$content->fastForward(1);                       // skip '<'
$tag = $content->copyByToken(StringToken::SLASH(), true); // 'div'
$content->skipByToken(StringToken::BLANK());
$name = $content->copyByToken(StringToken::EQUAL(), true); // 'class'
echo $content->getPosition();                   // somewhere past 'class'
```

--------------------------------

### Error handling with ContentLengthException

Source: https://github.com/paquettg/php-html-parser/blob/master/_autodocs/api-reference/content.md

Demonstrates catching ContentLengthException when fastForward exceeds the content length. The example creates a Content with 'short' and attempts to fastForward(100), printing the exception message on failure.

```php
use PHPHtmlParser\Content;
use PHPHtmlParser\Exceptions\ContentLengthException;

$content = new Content('short');
try {
    $content->fastForward(100);
} catch (ContentLengthException $e) {
    echo 'Overshot: ' . $e->getMessage();
}
```

--------------------------------

### Load HTML from a URL with custom client

Source: https://github.com/paquettg/php-html-parser/blob/master/README.md

Load HTML from a URL using a custom HTTP client that implements \Psr\Http\Client\ClientInterface. Pass the client as the third argument to loadFromUrl.

```php
// Assuming you installed from Composer:
require "vendor/autoload.php";
use PHPHtmlParser\Dom;
use App\Services\MyClient;

$dom = new Dom;
$dom->loadFromUrl('http://google.com', null, new MyClient());
$html = $dom->outerHtml;
```

--------------------------------

### Run php-cs-fixer to fix code style

Source: https://github.com/paquettg/php-html-parser/blob/master/CONTRIBUTING.md

Run this command before pushing changes to comply with the PSR-12 coding style used by the project.

```bash
./vendor/bin/php-cs-fixer fix
```

--------------------------------

### Example — global vs per-call options

Source: https://github.com/paquettg/php-html-parser/blob/master/_autodocs/api-reference/options.md

Shows how global options set via `setOptions` apply to every `loadStr` call, while per-call options passed to `loadStr` only affect that call. Here, `whitespaceTextNode` is false only for the second load; the third load still uses the global true value.

```php
use PHPHtmlParser\Dom;
use PHPHtmlParser\Options;

$dom = new Dom();
$dom->setOptions((new Options())->setStrict(true));                  // used by every load
$dom->loadStr('<br>', (new Options())->setWhitespaceTextNode(false)); // this load only
$dom->loadStr('<br>');                                               // whitespaceTextNode still true here
```

--------------------------------

### Set text of a TextNode with setText()

Source: https://github.com/paquettg/php-html-parser/blob/master/README.md

Use setText() on a TextNode to change its content. If an encoding is set, the new text will be encoded using that encoding. The example loads HTML, finds the first anchor, and replaces its text with 'biz baz', then echoes the modified DOM.

```php
use PHPHtmlParser\Dom;

$dom = new Dom;
$dom->loadStr('<div class="all"><p>Hey bro, <a href="google.com">click here</a><br /> :)</p></div>');
/** @var Dom\Node\InnerNode $a */
$a   = $dom->find('a')[0];
$a->firstChild()->setText('biz baz');
echo $dom; // '<div class="all"><p>Hey bro, <a href="google.com">biz baz</a><br /> :)</p></div>'
```

--------------------------------

### Node::setAttribute

Source: https://github.com/paquettg/php-html-parser/blob/master/README.md

Sets an attribute on a node. This method is available on node objects returned by find.

```APIDOC
## Node::setAttribute

### Description
Sets an attribute on a node. This method is available on node objects returned by find.

### Method
setAttribute

### Parameters
- **name** (string) - Required - The attribute name.
- **value** (string) - Required - The attribute value.

### Example
```php
$a->setAttribute('class', 'foo');
```
```

--------------------------------

### Example: using findById to locate a node

Source: https://github.com/paquettg/php-html-parser/blob/master/_autodocs/api-reference/finder.md

Loads a DOM, finds the first paragraph, stores its id, then retrieves the same node via findById from both the node itself and the root. Outputs 'same node' and the text 'a'.

```php
use PHPHtmlParser\Dom;

$dom = new Dom();
$dom->loadStr('<div class="all"><p>a</p><p>b</p></div>');
$first = $dom->find('p')[0];
$id    = $first->id();

$again = $first->findById($id);
echo $again === $first ? 'same node' : 'different'; // 'same node'

// the whole-tree lookup also works from anywhere:
$root = $dom->root;
$found = $root->findById($id);
echo $found->text; // 'a'
```

--------------------------------

### Content::string

Source: https://github.com/paquettg/php-html-parser/blob/master/_autodocs/api-reference/content.md

Returns a substring of the specified length starting at the current cursor position, accumulated character by character.

```APIDOC
## Content::string

### Description
Returns a substring of the specified length starting at the current cursor position, accumulated character by character.

### Method
Method

### Signature
```php
public function string(int $length = 1): string
```

### Parameters
- **$length** (int) - Optional - Number of characters to include. Defaults to 1.

### Return Value
- **string** - Substring of the requested length.
```

--------------------------------

### Dom::loadFromUrl

Source: https://github.com/paquettg/php-html-parser/blob/master/README.md

Loads HTML content from a URL. Accepts an optional Options object to override global options for this specific load operation.

```APIDOC
## Dom::loadFromUrl

### Description
Loads HTML content from a URL. Accepts an optional Options object to override global options for this specific load operation.

### Method
loadFromUrl

### Parameters
- **url** (string) - Required - The URL to load HTML from.
- **options** (Options) - Optional - Options to apply for this load, overriding global options.

### Example
```php
$dom->loadFromUrl('http://google.com', (new Options())->setWhitespaceTextNode(false));
```
```

--------------------------------

### Example: using InnerNode methods

Source: https://github.com/paquettg/php-html-parser/blob/master/_autodocs/api-reference/inner-node.md

Demonstrates countChildren, firstChild, lastChild, hasChild, and insertBefore on an InnerNode. Outputs the modified DOM after inserting a new node.

```php
use PHPHtmlParser\Dom;
use PHPHtmlParser\Dom\Node\HtmlNode;

$dom = new Dom();
$dom->loadStr('<ul><li>a</li><li>b</li></ul>');
/** @var \PHPHtmlParser\Dom\Node\InnerNode $ul */
$ul = $dom->find('ul')[0];

echo $ul->countChildren();           // 2
$first = $ul->firstChild();          // <li>a</li>
echo $ul->lastChild()->text;         // 'b'
echo $ul->hasChild($first->id());    // true

// insert a node before the second item
$new = new HtmlNode('li');
$new->setAttribute('class', 'new');
$ul->insertBefore($new, $dom->find('li')[1]->id());
echo $dom; // '<ul><li>a</li><li>class="new"></li><li>b</li></ul>'
```

--------------------------------

### Collection usage example

Source: https://github.com/paquettg/php-html-parser/blob/master/_autodocs/api-reference/collection.md

Shows how to use a Collection returned by getElementsByClass: count nodes, iterate with foreach, use each(), and access the first node via array offset or property forwarding.

```php
use PHPHtmlParser\Dom;
use PHPHtmlParser\Exceptions\EmptyCollectionException;

$dom = new Dom();
$dom->loadStr('<div class="c">one</div><div class="c">two</div>');

$items = $dom->getElementsByClass('c');
echo count($items);          // 2
foreach ($items as $item) {
    echo $item->text;        // 'one' then 'two'
}
$items->each(function ($node, $key) {
    echo $key . ':' . $node->text;
});

// forwarding to the first node
echo $items[0]->getAttribute('class'); // 'c'
echo $items->text;                     // 'one' (first node's text)
```

--------------------------------

### Error-handling example: CircularException and ChildNotFoundException

Source: https://github.com/paquettg/php-html-parser/blob/master/_autodocs/api-reference/inner-node.md

Shows how to catch CircularException when adding a node to itself and ChildNotFoundException when a child ID is not found.

```php
use PHPHtmlParser\Dom;
use PHPHtmlParser\Exceptions\ChildNotFoundException;
use PHPHtmlParser\Exceptions\CircularException;

$dom = new Dom();
$dom->loadStr('<div><p>t</p></div>');
$root = $dom->root;

try {
    $root->addChild($root); // cannot add a node to itself
} catch (CircularException $e) {
    echo 'Circular: ' . $e->getMessage();
}

try {
    $root->nextChild(12345);
} catch (ChildNotFoundException $e) {
    echo 'Missing: ' . $e->getMessage();
}
```

--------------------------------

### Set global and load-specific parsing options with setOptions and Options

Source: https://github.com/paquettg/php-html-parser/blob/master/README.md

Shows how to set global options via Dom::setOptions and per-load options by passing an Options instance to loadFromUrl. The load-specific option only applies to that load, while global options persist. Requires Composer autoload and the PHPHtmlParser\Dom and PHPHtmlParser\Options classes.

```php
// Assuming you installed from Composer:
require "vendor/autoload.php";
use PHPHtmlParser\Dom;
use PHPHtmlParser\Options;

$dom = new Dom;
$dom->setOptions(
    // this is set as the global option level.
    (new Options())
        ->setStrict(true)
);

$dom->loadFromUrl('http://google.com', 
    (new Options())->setWhitespaceTextNode(false) // only applies to this load.
);

$dom->loadFromUrl('http://gmail.com'); // will not have whitespaceTextNode set to false.
```

--------------------------------

### Basic usage example

Source: https://github.com/paquettg/php-html-parser/blob/master/_autodocs/api-reference/abstract-node.md

Loads an HTML string, finds the first <a> element, reads its href attribute, sets a double-quoted class attribute, prints the outer HTML, and walks up to the ancestor <div> using ancestorByTag.

```php
use PHPHtmlParser\Dom;

$dom = new Dom();
$dom->loadStr('<div class="all"><p>Hey bro, <a href="google.com">click here</a></p></div>');
/** @var \PHPHtmlParser\Dom\Node\AbstractNode $a */
$a = $dom->find('a')[0];

echo $a->getAttribute('href');          // 'google.com'
$a->setAttribute('class', 'foo', true); // double-quoted attribute
echo $a->outerHtml;                     // '<a href="google.com" class="foo">click here</a>'
$anchor = $a->ancestorByTag('div');     // walks up to <div>
```

--------------------------------

### RootAccessTrait usage example

Source: https://github.com/paquettg/php-html-parser/blob/master/_autodocs/api-reference/dom.md

Shows how to use the root-node convenience wrappers after loading a string. The output comments show that outerHtml returns the full HTML, countChildren() returns 1, firstChild()->text returns 'Hey', and getElementById('all') returns an HtmlNode instance.

```php
$dom = new Dom();
$dom->loadStr('<div class="all"><p>Hey</p></div>');
echo $dom->outerHtml;      // '<div class="all"><p>Hey</p></div>'
echo $dom->countChildren(); // 1
echo $dom->firstChild()->text; // 'Hey'
echo $dom->getElementById('all') instanceof \PHPHtmlParser\Dom\Node\HtmlNode ? 'found' : 'missing';
```

--------------------------------

### Node::getTag

Source: https://github.com/paquettg/php-html-parser/blob/master/README.md

Returns the Tag object associated with a node, allowing direct manipulation of the tag's attributes.

```APIDOC
## Node::getTag

### Description
Returns the Tag object associated with a node, allowing direct manipulation of the tag's attributes.

### Method
getTag

### Returns
- Tag - The Tag object for the node.

### Example
```php
$tag = $a->getTag();
$tag->setAttribute('class', 'foo');
```
```

--------------------------------

### Error-handling example: find returns false for missing id

Source: https://github.com/paquettg/php-html-parser/blob/master/_autodocs/api-reference/finder.md

Creates a Finder with a non-existent id (999999) and calls find on the root node. The result is false, demonstrating the fall-through behavior when no node matches.

```php
use PHPHtmlParser\Dom;
use PHPHtmlParser\Finder;

$dom = new Dom();
$dom->loadStr('<div><p>t</p></div>');
$finder = new Finder(999999); // id that does not exist
$result = $finder->find($dom->root);
var_dump($result); // false
```

--------------------------------

### Dom::find

Source: https://github.com/paquettg/php-html-parser/blob/master/README.md

Searches the DOM for elements matching a CSS selector. Returns a collection of nodes that can be iterated or accessed by index.

```APIDOC
## Dom::find

### Description
Searches the DOM for elements matching a CSS selector. Returns a collection of nodes that can be iterated or accessed by index.

### Method
find

### Parameters
- **selector** (string) - Required - The CSS selector to search for.

### Returns
- Collection of matching nodes.

### Example
```php
$objects = $dom->find('.content-border');
```
```

--------------------------------

### Dom::setOptions

Source: https://github.com/paquettg/php-html-parser/blob/master/README.md

Sets global parsing options for the Dom object. This method accepts an Options object and applies it to all subsequent load operations unless overridden per load.

```APIDOC
## Dom::setOptions

### Description
Sets global parsing options for the Dom object. This method accepts an Options object and applies it to all subsequent load operations unless overridden per load.

### Method
setOptions

### Parameters
- **options** (Options) - Required - The Options object containing parsing options.

### Example
```php
$dom->setOptions((new Options())->setStrict(true));
```
```

--------------------------------

### Dom::loadStr

Source: https://github.com/paquettg/php-html-parser/blob/master/README.md

Loads HTML content from a string. This method is used to parse HTML from a string input.

```APIDOC
## Dom::loadStr

### Description
Loads HTML content from a string. This method is used to parse HTML from a string input.

### Method
loadStr

### Parameters
- **html** (string) - Required - The HTML string to parse.

### Example
```php
$dom->loadStr('<div class="all"><p>Hey bro, <a href="google.com">click here</a><br /> :)</p></div>');
```
```

--------------------------------

### Node::delete

Source: https://github.com/paquettg/php-html-parser/blob/master/README.md

Removes a node from the DOM tree. After calling delete, the node should be unset to free memory.

```APIDOC
## Node::delete

### Description
Removes a node from the DOM tree. After calling delete, the node should be unset to free memory.

### Method
delete

### Example
```php
$a->delete();
unset($a);
```
```

--------------------------------

### Basic DOM parsing with loadStr and find

Source: https://github.com/paquettg/php-html-parser/blob/master/README.md

Load an HTML string and find an anchor tag using a CSS selector. Outputs the text content of the first matching element.

```php
// Assuming you installed from Composer:
require "vendor/autoload.php";
use PHPHtmlParser\Dom;

$dom = new Dom;
$dom->loadStr('<div class="all"><p>Hey bro, <a href="google.com">click here</a><br /> :)</p></div>');
$a = $dom->find('a')[0];
echo $a->text; // "click here"
```

--------------------------------

### Advanced example — style attributes and quoting

Source: https://github.com/paquettg/php-html-parser/blob/master/_autodocs/api-reference/tag.md

Demonstrates style attribute manipulation and single-quote attribute rendering. `getStyleAttributeArray()` returns an associative array; `setStyleAttributeValue` appends a style property; `setAttribute` with `false` forces single-quoted output; `makeOpeningTag()` shows the resulting tag.

```php
use PHPHtmlParser\Dom;

$dom = new Dom();
$dom->loadStr('<div style="color:red;width:10px;">x</div>');
$tag = $dom->find('div')[0]->getTag();

print_r($tag->getStyleAttributeArray()); // ['color' => 'red', 'width' => '10px']
$tag->setStyleAttributeValue('height', '5px');
echo $tag->getAttribute('style')->getValue(); // 'color:red;width:10px;height:5px;'

$tag->setAttribute('data-x', "it's ok", false); // single-quoted
echo $tag->makeOpeningTag();                    // '<div style="..." data-x=\'it\'s ok\'>'
```

--------------------------------

### Error-handling example with ParentNotFoundException

Source: https://github.com/paquettg/php-html-parser/blob/master/_autodocs/api-reference/abstract-node.md

Attempts to find an ancestor <section> for a <p> element that has none, catching ParentNotFoundException and printing the message. Demonstrates handling the exception thrown by ancestorByTag.

```php
use PHPHtmlParser\Dom;
use PHPHtmlParser\Exceptions\ParentNotFoundException;

$dom = new Dom();
$dom->loadStr('<div><p>text</p></div>');
$root = $dom->root; // HtmlNode with tag 'root'

try {
    $dom->find('p')[0]->ancestorByTag('section');
} catch (ParentNotFoundException $e) {
    echo 'No matching ancestor: ' . $e->getMessage();
}
```

--------------------------------

### Basic Tag attribute example

Source: https://github.com/paquettg/php-html-parser/blob/master/_autodocs/api-reference/tag.md

Loads a simple HTML string, finds an anchor tag, and demonstrates getting/setting attributes. `setAttribute('class', 'foo')` changes the class; `setAttribute('title', null)` creates a valueless attribute; `outerHtml` reflects the changes.

```php
use PHPHtmlParser\Dom;

$dom = new Dom();
$dom->loadStr('<div class="all"><a href="google.com">click</a></div>');
$a   = $dom->find('a')[0];
$tag = $a->getTag();               // Dom\Tag

$tag->setAttribute('class', 'foo');
echo $a->getAttribute('class');    // 'foo'
$a->setAttribute('title', null);   // valueless attribute
echo $a->outerHtml;                // '<a href="google.com" title>click</a>'
```

--------------------------------

### find method signature for Finder

Source: https://github.com/paquettg/php-html-parser/blob/master/_autodocs/api-reference/finder.md

Public method that takes a starting AbstractNode and returns the matching node or false when not found. Traversal may throw ChildNotFoundException or ParentNotFoundException.

```php
public function find(AbstractNode $node)
```

--------------------------------

### Load HTML from a URL with default client

Source: https://github.com/paquettg/php-html-parser/blob/master/README.md

Load HTML from a URL using loadFromUrl with default PSR-18 client and PSR-7 request implementations. The outerHtml property returns the full HTML.

```php
// Assuming you installed from Composer:
require "vendor/autoload.php";
use PHPHtmlParser\Dom;

$dom = new Dom;
$dom->loadFromUrl('http://google.com');
$html = $dom->outerHtml;

// or
$dom->loadFromUrl('http://google.com');
$html = $dom->outerHtml; // same result as the first example
```

--------------------------------

### Class signature for PHPHtmlParser\Finder

Source: https://github.com/paquettg/php-html-parser/blob/master/_autodocs/api-reference/finder.md

Declares the Finder class with its constructor and find method. The constructor takes a node id, and find locates a node by that id starting from a given AbstractNode.

```php
class Finder
{
    public function __construct($id);
    public function find(AbstractNode $node);
}
```

--------------------------------

### Set attribute on a node with setAttribute

Source: https://github.com/paquettg/php-html-parser/blob/master/README.md

Loads an HTML string, finds the first anchor element, and sets its class attribute to 'foo'. Then echoes the attribute value, which outputs "foo".

```php
use PHPHtmlParser\Dom;

$dom = new Dom;
$dom->loadStr('<div class="all"><p>Hey bro, <a href="google.com">click here</a><br /> :)</p></div>');
$a = $dom->find('a')[0];
$a->setAttribute('class', 'foo');
echo $a->getAttribute('class'); // "foo"
```

--------------------------------

### Content::__construct

Source: https://github.com/paquettg/php-html-parser/blob/master/_autodocs/api-reference/content.md

Initializes a new Content instance with the raw HTML string to scan. Sets the initial size and position.

```APIDOC
## Content::__construct

### Description
Initializes a new Content instance with the raw HTML string to scan. Sets the initial size and position.

### Method
Constructor

### Signature
```php
public function __construct(string $content = '')
```

### Parameters
- **$content** (string) - Optional - The raw HTML string to scan. Defaults to `''`.

### Behavior
Initializes `$size = strlen($content)` and `$pos = 0`.
```

--------------------------------

### Manipulate Tag object directly with getTag and setAttribute

Source: https://github.com/paquettg/php-html-parser/blob/master/README.md

Gets the Tag object from a node and sets an attribute on it. The change is reflected when reading the attribute from the node. Uses the PHPHtmlParser\Dom\Tag class.

```php
use PHPHtmlParser\Dom;

$dom = new Dom;
$dom->loadStr('<div class="all"><p>Hey bro, <a href="google.com">click here</a><br /> :)</p></div>');
/** @var Dom\Node\AbstractNode $a */
$a   = $dom->find('a')[0];
$tag = $a->getTag();
$tag->setAttribute('class', 'foo');
echo $a->getAttribute('class'); // "foo"
```

--------------------------------

### TextNode usage example

Source: https://github.com/paquettg/php-html-parser/blob/master/_autodocs/api-reference/html-node.md

Loads HTML, finds a <p> element, gets its first child as a TextNode, reads and updates its text. After setText('biz baz'), echoing the DOM shows the updated content. Note: with active encoding, setText output is converted to that encoding.

```php
use PHPHtmlParser\Dom;

$dom = new Dom();
$dom->loadStr('<div class="all"><p>Hey bro</p></div>');
$p = $dom->find('p')[0];

$textNode = $p->firstChild();            // TextNode with text 'Hey bro'
echo $textNode->text;                    // 'Hey bro'
$textNode->setText('biz baz');
echo $dom;                               // '<div class="all"><p>biz baz</p></div>'
```

--------------------------------

### StaticDom::loadFromFile

Source: https://github.com/paquettg/php-html-parser/blob/master/_autodocs/api-reference/static-dom.md

Creates a fresh Dom instance from an HTML file and stores it as the facade target. Returns the created Dom instance.

```APIDOC
## StaticDom::loadFromFile

### Description
Creates a fresh `Dom` instance from an HTML file and stores it as the facade target. Returns the created `Dom` instance.

### Method
`public static function loadFromFile(string $file, ?Options $options = null): Dom`

### Parameters
- `$file` (string) - Required - Path to the HTML file.
- `$options` (?Options) - Optional - Parsing options. Default: `null`.

### Returns
- `Dom` - The created `Dom` instance.

### Exceptions
- `ChildNotFoundException`
- `CircularException`
- `StrictException`
- `Exceptions\LogicalException`

### Example
```php
use PHPHtmlParser\StaticDom;

StaticDom::mount();
$dom = StaticDom::loadFromFile('/path/to/file.html');
```
```

--------------------------------

### StaticDom::loadFromUrl

Source: https://github.com/paquettg/php-html-parser/blob/master/_autodocs/api-reference/static-dom.md

Creates a fresh Dom instance from a URL and stores it as the facade target. Returns the created Dom instance.

```APIDOC
## StaticDom::loadFromUrl

### Description
Creates a fresh `Dom` instance from a URL and stores it as the facade target. Returns the created `Dom` instance.

### Method
`public static function loadFromUrl(string $url, ?Options $options = null, ClientInterface $client = null, RequestInterface $request = null): Dom`

### Parameters
- `$url` (string) - Required - URL to fetch.
- `$options` (?Options) - Optional - Parsing options. Default: `null`.
- `$client` (?ClientInterface) - Optional - PSR-18 HTTP client. Default: `new GuzzleHttp\Client()`.
- `$request` (?RequestInterface) - Optional - PSR-7 request. Default: `new GuzzleHttp\Psr7\Request('GET', $url)`.

### Returns
- `Dom` - The created `Dom` instance.

### Exceptions
- `ChildNotFoundException`
- `CircularException`
- `StrictException`
- `\Psr\Http\Client\ClientExceptionInterface`

### Example
```php
use PHPHtmlParser\StaticDom;

StaticDom::mount();
$dom = StaticDom::loadFromUrl('http://example.com');
```
```

--------------------------------

### new Content(string $content)

Source: https://github.com/paquettg/php-html-parser/blob/master/_autodocs/api-reference/content.md

Creates a new Content instance that acts as a cursor over the given HTML string. This is the entry point for direct use of the Content class.

```APIDOC
## new Content(string $content)

### Description
Creates a new Content instance that acts as a cursor over the given HTML string. This is the entry point for direct use of the Content class.

### Method
Constructor

### Parameters
- **$content** (string) - Required - The HTML string to parse.

### Request Example
```php
use PHPHtmlParser\Content;

$content = new Content('<div class="x">text</div>');
```
```

--------------------------------

### Load HTML from a string with loadStr

Source: https://github.com/paquettg/php-html-parser/blob/master/README.md

Load an HTML string directly using loadStr and access the outerHtml property.

```php
// Assuming you installed from Composer:
require "vendor/autoload.php";
use PHPHtmlParser\Dom;

$dom = new Dom;
$dom->loadStr('<html>String</html>');
$html = $dom->outerHtml;
```

--------------------------------

### Set global and per-call options for Dom::loadStr

Source: https://github.com/paquettg/php-html-parser/blob/master/_autodocs/configuration.md

Shows how to configure global options via setOptions() and override them per call. Global options (strict, enforceEncoding) persist across loads, while per-call options like whitespaceTextNode only apply to that load. Requires PHP >= 7.2 and the listed composer dependencies.

```php
use PHPHtmlParser\Dom;
use PHPHtmlParser\Options;

$dom = new Dom();
$dom->setOptions(
    (new Options())
        ->setStrict(true)
        ->setEnforceEncoding('ISO-8859-1')
);

$dom->loadFromUrl('http://example.com',
    (new Options())->setWhitespaceTextNode(false) // only this load
);
$dom->loadFromUrl('http://gmail.com');            // strict + ISO-8859-1 still apply; whitespaceTextNode back to true
```

--------------------------------

### loadFromFile method signature

Source: https://github.com/paquettg/php-html-parser/blob/master/_autodocs/api-reference/dom.md

Loads an HTML document from a filesystem path. Reads the file with file_get_contents and delegates to loadStr. Throws LogicalException if the file cannot be read, plus all exceptions from loadStr.

```php
public function loadFromFile(string $file, ?Options $options = null): Dom
```

--------------------------------

### StaticDom::loadStr

Source: https://github.com/paquettg/php-html-parser/blob/master/_autodocs/api-reference/static-dom.md

Creates a fresh Dom instance from an HTML string and stores it as the facade target. Returns the created Dom instance.

```APIDOC
## StaticDom::loadStr

### Description
Creates a fresh `Dom` instance from an HTML string and stores it as the facade target. Returns the created `Dom` instance.

### Method
`public static function loadStr(string $str, ?Options $options = null): Dom`

### Parameters
- `$str` (string) - Required - HTML string to parse.
- `$options` (?Options) - Optional - Parsing options. Default: `null`.

### Returns
- `Dom` - The created `Dom` instance.

### Example
```php
use PHPHtmlParser\StaticDom;

StaticDom::mount();
$dom = StaticDom::loadStr('<div>Hello</div>');
```
```

--------------------------------

### find method signature

Source: https://github.com/paquettg/php-html-parser/blob/master/_autodocs/api-reference/selector.md

Searches for nodes matching the selector starting from the given node. Returns a Collection of matched nodes, possibly empty. Throws ChildNotFoundException.

```php
public function find(AbstractNode $node): Collection
```

--------------------------------

### fastForward(int $offset)

Source: https://github.com/paquettg/php-html-parser/blob/master/_autodocs/api-reference/content.md

Moves the cursor forward by the specified number of characters. Throws a ContentLengthException if the offset exceeds the content length.

```APIDOC
## fastForward(int $offset)

### Description
Moves the cursor forward by the specified number of characters. Throws a ContentLengthException if the offset exceeds the content length.

### Method
fastForward

### Parameters
- **$offset** (int) - Required - The number of characters to move forward.

### Request Example
```php
use PHPHtmlParser\Content;

$content = new Content('<div class="x">text</div>');
$content->fastForward(1); // skip '<'
```

### Error Handling
- Throws **ContentLengthException** if the offset exceeds the content length.

### Error Example
```php
use PHPHtmlParser\Content;
use PHPHtmlParser\Exceptions\ContentLengthException;

$content = new Content('short');
try {
    $content->fastForward(100);
} catch (ContentLengthException $e) {
    echo 'Overshot: ' . $e->getMessage();
}
```
```

--------------------------------

### setOptions()

Source: https://github.com/paquettg/php-html-parser/blob/master/_autodocs/api-reference/dom.md

Sets the options for the Dom object. Returns the Dom instance for chaining.

```APIDOC
## setOptions()

### Description
Sets the options for the Dom object. Returns the Dom instance for chaining.

### Method
setOptions

### Signature
`public function setOptions(Options $options): Dom`

### Parameters
- `$options` (Options) - Required - The options to set.

### Returns
(Dom) The Dom instance for chaining.
```

--------------------------------

### Tag::makeOpeningTag()

Source: https://github.com/paquettg/php-html-parser/blob/master/_autodocs/api-reference/tag.md

Generates the opening tag string. This method constructs the opening tag based on the tag's state.

```APIDOC
## Tag::makeOpeningTag()

### Description
Generates the opening tag string.

### Method
makeOpeningTag

### Parameters
None

### Return Value
- (not specified) - The return value is not documented, but likely a string.

```

--------------------------------

### setOptions

Source: https://github.com/paquettg/php-html-parser/blob/master/_autodocs/api-reference/dom.md

Sets global options applied to every subsequent load* call. Returns the Dom instance for chaining.

```APIDOC
## setOptions

### Description
Sets global options applied to every subsequent load* call. Returns the Dom instance for chaining.

### Method
setOptions

### Signature
public function setOptions(Options $options): Dom

### Parameters
- `$options` (Options) - Required - Global options applied to every subsequent `load*` call.

### Returns
- `Dom` - The Dom instance.

### Example
```php
use PHPHtmlParser\Dom;
use PHPHtmlParser\Options;

$dom = new Dom();
$dom->setOptions((new Options())->setStrict(true));          // global
$dom->loadStr('<html>h</html>', (new Options())->setWhitespaceTextNode(false)); // this load only
```
```

--------------------------------

### loadFromFile method signature

Source: https://github.com/paquettg/php-html-parser/blob/master/_autodocs/api-reference/static-dom.md

Declares the loadFromFile method that creates a fresh Dom and delegates to Dom::loadFromFile. Throws ChildNotFoundException, CircularException, StrictException, and Exceptions\LogicalException.

```php
public static function loadFromFile(string $file, ?Options $options = null): Dom
```

--------------------------------

### HTML meta tag with duplicate charset

Source: https://github.com/paquettg/php-html-parser/blob/master/tests/data/files/html5.html

Example meta tag from duckduckgo.com that triggers the greedy regex issue in Dom.php's detectCharset method.

```html
    <meta http-equiv="content-type" content="text/html; charset=UTF-8;charset=utf-8">
```

--------------------------------

### Tag::__construct(string $name)

Source: https://github.com/paquettg/php-html-parser/blob/master/_autodocs/api-reference/tag.md

Creates a new Tag instance with the given tag name. The constructor initializes the tag's name and default state.

```APIDOC
## Tag::__construct(string $name)

### Description
Creates a new Tag instance with the given tag name.

### Method
Constructor

### Parameters
- **$name** (string) - Required - The name of the HTML tag.

### Return Value
- A new Tag instance.

```

--------------------------------

### loadFromUrl method signature

Source: https://github.com/paquettg/php-html-parser/blob/master/_autodocs/api-reference/static-dom.md

Declares the loadFromUrl method that creates a fresh Dom and delegates to Dom::loadFromUrl. Throws ChildNotFoundException, CircularException, StrictException, and \Psr\Http\Client\ClientExceptionInterface.

```php
public static function loadFromUrl(string $url, ?Options $options = null, ClientInterface $client = null, RequestInterface $request = null): Dom
```

--------------------------------

### clean(string $str, Options $options, string $defaultCharset): string

Source: https://github.com/paquettg/php-html-parser/blob/master/_autodocs/api-reference/parser-cleaner.md

Cleans raw input HTML by applying a configurable pipeline of cleanup steps, including gzip decoding, encoding normalization, whitespace and line break handling, and removal of doctype, comments, CDATA, scripts, styles, and Smarty tags. Returns the cleaned string, or the original string unchanged if cleanup is disabled.

```APIDOC
## clean(string $str, Options $options, string $defaultCharset): string

### Description
Cleans raw input HTML by applying a configurable pipeline of cleanup steps, including gzip decoding, encoding normalization, whitespace and line break handling, and removal of doctype, comments, CDATA, scripts, styles, and Smarty tags. Returns the cleaned string, or the original string unchanged if cleanup is disabled.

### Method
clean

### Signature
```php
public function clean(string $str, Options $options, string $defaultCharset): string
```

### Parameters
- **$str** (string) - Required - Raw input HTML.
- **$options** (Options) - Required - Controls which cleanup steps run.
- **$defaultCharset** (string) - Required - Fallback charset for regex encoding (Dom passes `'UTF-8'`).

### Return Value
- **string** - The cleaned string.

### Behavior
- If `isCleanupInput()` is false, returns `$str` unchanged.
- Otherwise, applies the following pipeline steps:
  1. **Gzip decode** - If the string starts with gzip magic bytes `\x1f\x8b\x08`, apply `gzdecode()`.
  2. **Encoding setup** - `setUpRegexEncoding`: sets `mb_regex_encoding()` to `enforceEncoding` or `$defaultCharset`, then `mb_convert_encoding($str, $encoding)`.
  3. **Whitespace before closing tags** - `mb_eregi_replace("'\s+>", "'>")` and `mb_eregi_replace('"\s+>', '">')`.
  4. **Line breaks** - `\r\n`, `\r`, `\n` replaced with `' '`, or with `'&#10;'` when `preserveLineBreaks` is true.
  5. **Doctype** - `<!doctype(.*?)>` stripped.
  6. **Comments** - `<!--(.*?)-->` stripped.
  7. **CDATA** - `<!\[CDATA\[(.*?)\]\]>` stripped.
  8. **Scripts** (when `removeScripts`) - Two regexes for `<script ...>` / `<script>` blocks.
  9. **Styles** (when `removeStyles`) - Two regexes for `<style ...>` / `<style>` blocks.
  10. **Smarty** (when `removeSmartyScripts`) - `(\{\w)(.*?)(\})` stripped.

### Exceptions
- Throws `LogicalException` for any step whose mb/str operation returns `false` (each message pinpoints the failed step).

### Source
`src/PHPHtmlParser/Dom/Cleaner.php:18-118`
```

--------------------------------

### makeOpeningTag method signature

Source: https://github.com/paquettg/php-html-parser/blob/master/_autodocs/api-reference/tag.md

Returns the opening tag string: `$opening . $name` plus each attribute — `' key'` for null values, `' key="value"'` when `AttributeDTO::isDoubleQuote()`, `key='value'` otherwise. Appends `$closing` (`' />'`) when self-closing with trailing slash, else `'>'`. Catches `AttributeNotFoundException` (skips the attribute) and `\TypeError` (uses null value). Source: `src/PHPHtmlParser/Dom/Tag.php:321-355`.

```php
public function makeOpeningTag()
```

--------------------------------

### Constructor: __construct(string $name)

Source: https://github.com/paquettg/php-html-parser/blob/master/_autodocs/api-reference/tag.md

Creates a new Tag instance with the given tag name. The name is used for element tags like 'div' or 'text' for text nodes.

```APIDOC
## Constructor: __construct(string $name)

### Description
Creates a new Tag instance with the given tag name. The name is used for element tags like 'div' or 'text' for text nodes.

### Method
Constructor

### Signature
```php
public function __construct(string $name)
```

### Parameters
- **$name** (string) - Required - Tag name, e.g. `'div'` or `'text'` (used for text nodes).

### Source
`src/PHPHtmlParser/Dom/Tag.php:68-71`
```

--------------------------------

### Delete a node from the DOM tree with delete and unset

Source: https://github.com/paquettg/php-html-parser/blob/master/README.md

Removes an anchor node from the tree using the delete method, then unsets the variable to free memory. Echoing the Dom shows the modified HTML without the anchor.

```php
use PHPHtmlParser\Dom;

$dom = new Dom;
$dom->loadStr('<div class="all"><p>Hey bro, <a href="google.com">click here</a><br /> :)</p></div>');
/** @var Dom\Node\AbstractNode $a */
$a   = $dom->find('a')[0];
$a->delete();
unset($a);
echo $dom; // '<div class="all"><p>Hey bro, <br /> :)</p></div>');
```

--------------------------------

### Constructor signature for Finder

Source: https://github.com/paquettg/php-html-parser/blob/master/_autodocs/api-reference/finder.md

Public constructor that accepts the node id to search for. The id is declared untyped but documented as an int.

```php
public function __construct($id)
```
Tokens:
Raw