The DomCrawler Component ¶

The DomCrawler component eases DOM navigation for HTML and XML documents.
DomCrawler コンポーネントは、HTML および XML ドキュメントの DOM ナビゲーションを容易にします。

Note

ノート

While possible, the DomCrawler component is not designed for manipulation of the DOM or re-dumping HTML/XML.

可能な限り、DomCrawler コンポーネントは DOM の操作や HTML/XML の再ダンプ用には設計されていません。

Installation ¶

    
                        $ composer require symfony/dom-crawler

Note

ノート

If you install this component outside of a Symfony application, you must require the vendor/autoload.php file in your code to enable the class autoloading mechanism provided by Composer. Read this article for more details.

このコンポーネントを Symfony アプリケーションの外部にインストールする場合は、Composer が提供するクラス自動ロードメカニズムを有効にするために、コード内に vendor/autoload.php ファイルを必要とする必要があります。詳細については、この記事をお読みください。

Usage ¶

Node Filtering ¶

Using XPath expressions, you can select specific nodes within the document:

XPath 式を使用すると、ドキュメント内の特定のノードを選択できます。

    
                        $crawler = $crawler->filterXPath('descendant-or-self::body/p');

Tip

ヒント

DOMXPath::query is used internally to actually perform an XPath query.

DOMXPath::query は、実際に XPath クエリを実行するために内部的に使用されます。

If you prefer CSS selectors over XPath, install The CssSelector Component. It allows you to use jQuery-like selectors:

XPath よりも CSS セレクターを使用する場合は、CssSelector コンポーネントをインストールします。これにより、jQuery のようなセレクターを使用できるようになります。

    
                        $crawler = $crawler->filter('body > p');

An anonymous function can be used to filter with more complex criteria:

無名関数を使用して、より複雑な基準でフィルタリングできます。

    
                        use Symfony\Component\DomCrawler\Crawler;
// ...

$crawler = $crawler
    ->filter('body > p')
    ->reduce(function (Crawler $node, $i) {
        // filters every other node
        return ($i % 2) == 0;
    });

To remove a node, the anonymous function must return false.

ノードを削除するには、無名関数が false を返す必要があります。

Note

ノート

All filter methods return a new Crawler instance with the filtered content. To check if the filter actually found something, use $crawler->count() > 0 on this new crawler.

すべてのフィルターメソッドは、フィルター処理されたコンテンツを含む新しい Crawlerinstance を返します。フィルターが実際に何かを見つけたかどうかを確認するには、この新しいクローラーで $crawler->count() > 0 を使用します。

Both the filterXPath() and filter() methods work with XML namespaces, which can be either automatically discovered or registered explicitly.

filterXPath() メソッドとfilter() メソッドはどちらも XML 名前空間で動作し、自動的に検出されるか、明示的に登録されます。

Consider the XML below:

以下の XML を検討してください。

    
        
                
                
                        <?xml version="1.0" encoding="UTF-8" ?>
<entry
    xmlns="http://www.w3.org/2005/Atom"
    xmlns:media="http://search.yahoo.com/mrss/"
    xmlns:yt="http://gdata.youtube.com/schemas/2007"
>
    <id>tag:youtube.com,2008:video:kgZRZmEc9j4</id>
    <yt:accessControl action="comment" permission="allowed"/>
    <yt:accessControl action="videoRespond" permission="moderated"/>
    <media:group>
        <media:title type="plain">Chordates - CrashCourse Biology #24</media:title>
        <yt:aspectRatio>widescreen</yt:aspectRatio>
    </media:group>
</entry>
                    

            

    

This can be filtered with the Crawler without needing to register namespace aliases both with filterXPath():

これは、名前空間エイリアスを両方の filterXPath() に登録する必要なく、theCrawler でフィルタリングできます。

    
                        $crawler = $crawler->filterXPath('//default:entry/media:group//yt:aspectRatio');

and filter():

およびフィルター():

    
                        $crawler = $crawler->filter('default|entry media|group yt|aspectRatio');

Note

ノート

The default namespace is registered with a prefix "default". It can be changed with the setDefaultNamespacePrefix() method.

デフォルトの名前空間は、プレフィックス「default」で登録されます。 setDefaultNamespacePrefix() メソッドで変更できます。

The default namespace is removed when loading the content if it's the only namespace in the document. It's done to simplify the XPath queries.

デフォルトの名前空間は、ドキュメント内の唯一の名前空間である場合、コンテンツをロードするときに削除されます。これは、XPath クエリを簡素化するために行われます。

Namespaces can be explicitly registered with the registerNamespace() method:

名前空間は registerNamespace() メソッドで明示的に登録できます。

    
                        $crawler->registerNamespace('m', 'http://search.yahoo.com/mrss/');
$crawler = $crawler->filterXPath('//m:group//yt:aspectRatio');

Verify if the current node matches a selector:

現在のノードがセレクターと一致するかどうかを確認します。

    
                        $crawler->matches('p.lorem');

Node Traversing ¶

Access node by its position on the list:

リスト上の位置でノードにアクセスします。

    
                        $crawler->filter('body > p')->eq(0);

Get the first or last node of the current selection:

現在の選択の最初または最後のノードを取得します。

    
                        $crawler->filter('body > p')->first();
$crawler->filter('body > p')->last();

Get the nodes of the same level as the current selection:

現在の選択と同じレベルのノードを取得します。

    
                        $crawler->filter('body > p')->siblings();

Get the same level nodes after or before the current selection:

現在の選択の前後に同じレベルのノードを取得します。

    
                        $crawler->filter('body > p')->nextAll();
$crawler->filter('body > p')->previousAll();

Get all the child or ancestor nodes:

すべての子ノードまたは祖先ノードを取得します。

    
                        $crawler->filter('body')->children();
$crawler->filter('body > p')->ancestors();

Get all the direct child nodes matching a CSS selector:

CSS セレクターに一致するすべての直接の子ノードを取得します。

    
                        $crawler->filter('body')->children('p.lorem');

Get the first parent (heading toward the document root) of the element that matches the provided selector:

指定されたセレクターに一致する要素の最初の親 (ドキュメントルートに向かう) を取得します。

    
                        $crawler->closest('p.lorem');

Note

ノート

All the traversal methods return a new Crawler instance.

すべてのトラバーサルメソッドは、新しい Crawlerinstance を返します。

Accessing Node Values ¶

Access the node name (HTML tag name) of the first node of the current selection (e.g. "p" or "div"):

現在の選択の最初のノードのノード名 (HTML タグ名) にアクセスします (例: "p" または "div"):

    
                        // returns the node name (HTML tag name) of the first child element under <body>
$tag = $crawler->filterXPath('//body/*')->nodeName();

Access the value of the first node of the current selection:

現在の選択の最初のノードの値にアクセスします。

    
                        // if the node does not exist, calling to text() will result in an exception
$message = $crawler->filterXPath('//body/p')->text();

// avoid the exception passing an argument that text() returns when node does not exist
$message = $crawler->filterXPath('//body/p')->text('Default text content');

// by default, text() trims white spaces, including the internal ones
// (e.g. "  foo\n  bar    baz \n " is returned as "foo bar baz")
// pass FALSE as the second argument to return the original text unchanged
$crawler->filterXPath('//body/p')->text('Default text content', false);

// innerText() is similar to text() but only returns the text that is
// the direct descendant of the current node, excluding any child nodes
$text = $crawler->filterXPath('//body/p')->innerText();
// if content is <p>Foo <span>Bar</span></p>
// innerText() returns 'Foo' and text() returns 'Foo Bar'

Access the attribute value of the first node of the current selection:

現在の選択の最初のノードの属性値にアクセスします。

    
                        $class = $crawler->filterXPath('//body/p')->attr('class');

Extract attribute and/or node values from the list of nodes:

ノードのリストから属性および/またはノードの値を抽出します。

    
                        $attributes = $crawler
    ->filterXpath('//body/p')
    ->extract(['_name', '_text', 'class'])
;

Note

ノート

Special attribute _text represents a node value, while _name represents the element name (the HTML tag name).

特別な属性 _text はノード値を表し、_name は要素名 (HTML タグ名) を表します。

Call an anonymous function on each node of the list:

リストの各ノードで無名関数を呼び出します。

    
                        use Symfony\Component\DomCrawler\Crawler;
// ...

$nodeValues = $crawler->filter('p')->each(function (Crawler $node, $i) {
    return $node->text();
});

The anonymous function receives the node (as a Crawler) and the position as arguments. The result is an array of values returned by the anonymous function calls.

匿名関数はノード (Crawler として) と位置を引数として受け取ります。結果は、匿名関数呼び出しによって返される値の配列です。

When using nested crawler, beware that filterXPath() is evaluated in the context of the crawler:

ネストされたクローラーを使用する場合、filterXPath() がクローラーのコンテキストで評価されることに注意してください。

    
                        $crawler->filterXPath('parent')->each(function (Crawler $parentCrawler, $i) {
    // DON'T DO THIS: direct child can not be found
    $subCrawler = $parentCrawler->filterXPath('sub-tag/sub-child-tag');

    // DO THIS: specify the parent tag too
    $subCrawler = $parentCrawler->filterXPath('parent/sub-tag/sub-child-tag');
    $subCrawler = $parentCrawler->filterXPath('node()/sub-tag/sub-child-tag');
});

Adding the Content ¶

The crawler supports multiple ways of adding the content, but they are mutually exclusive, so you can only use one of them to add content (e.g. if you pass the content to the Crawler constructor, you can't call addContent() later):

クローラーはコンテンツを追加する複数の方法をサポートしていますが、それらは相互に排他的であるため、コンテンツを追加するために使用できるのはそのうちの 1 つだけです (たとえば、コンテンツをクローラーコンストラクターに渡す場合、後で addContent() を呼び出すことはできません)。

    
                        $crawler = new Crawler('<html><body/></html>');

$crawler->addHtmlContent('<html><body/></html>');
$crawler->addXmlContent('<root><node/></root>');

$crawler->addContent('<html><body/></html>');
$crawler->addContent('<root><node/></root>', 'text/xml');

$crawler->add('<html><body/></html>');
$crawler->add('<root><node/></root>');

Note

ノート

The addHtmlContent() and addXmlContent() methods default to UTF-8 encoding but you can change this behavior with their second optional argument.

addHtmlContent() および addXmlContent() メソッドのデフォルトは UTF-8 エンコーディングですが、2 番目のオプション引数でこの動作を変更できます。

The addContent() method guesses the best charset according to the given contents and defaults to ISO-8859-1 in case no charset can be guessed.

addContent() メソッドは、指定されたコンテンツに従って最適な文字セットを推測し、文字セットを推測できない場合はデフォルトで ISO-8859-1 に設定します。

As the Crawler's implementation is based on the DOM extension, it is also able to interact with native DOMDocument, DOMNodeList and DOMNode objects:

クローラーの実装は DOM 拡張に基づいているため、ネイティブの DOMDocument、DOMNodeList、および DOMNode オブジェクトと対話することもできます。

    
                        $domDocument = new \DOMDocument();
$domDocument->loadXml('<root><node/><node/></root>');
$nodeList = $domDocument->getElementsByTagName('node');
$node = $domDocument->getElementsByTagName('node')->item(0);

$crawler->addDocument($domDocument);
$crawler->addNodeList($nodeList);
$crawler->addNodes([$node]);
$crawler->addNode($node);
$crawler->add($domDocument);

クローラーの操作とダンプ

These methods on the Crawler are intended to initially populate your Crawler and aren't intended to be used to further manipulate a DOM (though this is possible). However, since the Crawler is a set of DOMElement objects, you can use any method or property available on DOMElement, DOMNode or DOMDocument. For example, you could get the HTML of a Crawler with something like this:

Crawler のこれらのメソッドは、最初に yourCrawler にデータを設定することを目的としており、DOM をさらに操作するために使用することを目的としていません (これは可能ですが)。ただし、Crawler は DOMElement オブジェクトのセットであるため、DOMElement、DOMNode、または DOMDocument で使用可能な任意のメソッドまたはプロパティを使用できます。たとえば、次のような方法で Crawler の HTML を取得できます。

    
                        $html = '';

foreach ($crawler as $domElement) {
    $html .= $domElement->ownerDocument->saveHTML($domElement);
}

Or you can get the HTML of the first node using html():

または、html() を使用して最初のノードの HTML を取得できます。

    
                        // if the node does not exist, calling to html() will result in an exception
$html = $crawler->html();

// avoid the exception passing an argument that html() returns when node does not exist
$html = $crawler->html('Default <strong>HTML</strong> content');

Or you can get the outer HTML of the first node using outerHtml():

または、outerHtml() を使用して最初のノードの外側の HTML を取得できます。

    
                        $html = $crawler->outerHtml();

Expression Evaluation ¶

The evaluate() method evaluates the given XPath expression. The return value depends on the XPath expression. If the expression evaluates to a scalar value (e.g. HTML attributes), an array of results will be returned. If the expression evaluates to a DOM document, a new Crawler instance will be returned.

evaluate() メソッドは、指定された XPath 式を評価します。戻り値は XPath 式によって異なります。式がスカラー値 (HTML 属性など) に評価される場合、結果の配列が返されます。式が DOM ドキュメントに評価される場合、新しい Crawler インスタンスが返されます。

This behavior is best illustrated with examples:

この動作は、例で最もよく説明されています。

    
        
                
                
                        use Symfony\Component\DomCrawler\Crawler;

$html = '<html>
<body>
    <span id="article-100" class="article">Article 1</span>
    <span id="article-101" class="article">Article 2</span>
    <span id="article-102" class="article">Article 3</span>
</body>
</html>';

$crawler = new Crawler();
$crawler->addHtmlContent($html);

$crawler->filterXPath('//span[contains(@id, "article-")]')->evaluate('substring-after(@id, "-")');
/* Result:
[
    0 => '100',
    1 => '101',
    2 => '102',
];
*/

$crawler->evaluate('substring-after(//span[contains(@id, "article-")]/@id, "-")');
/* Result:
[
    0 => '100',
]
*/

$crawler->filterXPath('//span[@class="article"]')->evaluate('count(@id)');
/* Result:
[
    0 => 1.0,
    1 => 1.0,
    2 => 1.0,
]
*/

$crawler->evaluate('count(//span[@class="article"])');
/* Result:
[
    0 => 3.0,
]
*/

$crawler->evaluate('//span[1]');
// A Symfony\Component\DomCrawler\Crawler instance
                    

            

    

Links ¶

Use the filter() method to find links by their id or class attributes and use the selectLink() method to find links by their content (it also finds clickable images with that content in its alt attribute).

filter() メソッドを使用して ID または class 属性でリンクを検索し、selectLink() メソッドを使用してコンテンツでリンクを検索します (alt 属性でそのコンテンツを含むクリック可能な画像も検索します)。

Both methods return a Crawler instance with just the selected link. Use the link() method to get the Link object that represents the link:

どちらのメソッドも、選択したリンクだけを持つ Crawler インスタンスを返します。リンクを表す Link オブジェクトを取得するには、link() メソッドを使用します。

    
                        // first, select the link by id, class or content...
$linkCrawler = $crawler->filter('#sign-up');
$linkCrawler = $crawler->filter('.user-profile');
$linkCrawler = $crawler->selectLink('Log in');

// ...then, get the Link object:
$link = $linkCrawler->link();

// or do all this at once:
$link = $crawler->filter('#sign-up')->link();
$link = $crawler->filter('.user-profile')->link();
$link = $crawler->selectLink('Log in')->link();

The Link object has several useful methods to get more information about the selected link itself:

Link オブジェクトには、選択したリンク自体に関する詳細情報を取得するための便利なメソッドがいくつかあります。

    
                        // returns the proper URI that can be used to make another request
$uri = $link->getUri();

Note

ノート

The getUri() is especially useful as it cleans the href value and transforms it into how it should really be processed. For example, for a link with href="#foo", this would return the full URI of the current page suffixed with #foo. The return from getUri() is always a full URI that you can act on.

getUri() は、href 値をクリーンアップし、実際の処理方法に変換するため、特に便利です。たとえば、href="#foo" を含むリンクの場合、これは現在のページの完全な URI を #foo でサフィックスして返します。 getUri() からの戻り値は、常に操作可能な fullURI です。

Images ¶

To find an image by its alt attribute, use the selectImage method on an existing crawler. This returns a Crawler instance with just the selected image(s). Calling image() gives you a special Image object:

alt 属性で画像を検索するには、既存のクローラーで selectImage メソッドを使用します。これは、選択された画像だけを持つ Crawler インスタンスを返します。 image() を呼び出すと、specialImage オブジェクトが得られます。

    
                        $imagesCrawler = $crawler->selectImage('Kitten');
$image = $imagesCrawler->image();

// or do this all at once
$image = $crawler->selectImage('Kitten')->image();

The Image object has the same getUri() method as Link.

Image オブジェクトには、Link と同じ getUri() メソッドがあります。

Forms ¶

Special treatment is also given to forms. A selectButton() method is available on the Crawler which returns another Crawler that matches <button> or <input type="submit"> or <input type="button"> elements (or an <img> element inside them). The string given as argument is looked for in the id, alt, name, and value attributes and the text content of those elements.

フォームにも特別な処理が施されます。 ororelements (またはそれらの内部の要素) に一致する別の Crawler を返す selectButton() メソッドが Crawler で使用可能です。引数として指定された文字列は、id、alt、name、および value 属性と、これらの要素のテキストコンテンツで検索されます。

This method is especially useful because you can use it to return a Form object that represents the form that the button lives in:

このメソッドは、ボタンが存在するフォームを表す Form オブジェクトを返すために使用できるため、特に便利です。

    
                        // button example: <button id="my-super-button" type="submit">My super button</button>

// you can get button by its label
$form = $crawler->selectButton('My super button')->form();

// or by button id (#my-super-button) if the button doesn't have a label
$form = $crawler->selectButton('my-super-button')->form();

// or you can filter the whole form, for example a form has a class attribute: <form class="form-vertical" method="POST">
$crawler->filter('.form-vertical')->form();

// or "fill" the form fields with data
$form = $crawler->selectButton('my-super-button')->form([
    'name' => 'Ryan',
]);

The Form object has lots of very useful methods for working with forms:

Form オブジェクトには、フォームを操作するための非常に便利なメソッドがたくさんあります。

    
                        $uri = $form->getUri();
$method = $form->getMethod();
$name = $form->getName();

The getUri() method does more than just return the action attribute of the form. If the form method is GET, then it mimics the browser's behavior and returns the action attribute followed by a query string of all of the form's values.

getUri() メソッドは、フォームのアクション属性を返すだけではありません。フォームメソッドが GET の場合、ブラウザの動作を模倣し、アクション属性に続いてフォームのすべての値のクエリ文字列を返します。

Note

ノート

The optional formaction and formmethod button attributes are supported. The getUri() and getMethod() methods take into account those attributes to always return the right action and method depending on the button used to get the form.

オプションの formaction および formmethod ボタン属性がサポートされています。 getUri() および getMethod() メソッドは、これらの属性を考慮して、フォームの取得に使用されるボタンに応じて常に適切なアクションとメソッドを返します。

You can virtually set and get values on the form:

フォームで仮想的に値を設定および取得できます。

    
                        // sets values on the form internally
$form->setValues([
    'registration[username]' => 'symfonyfan',
    'registration[terms]'    => 1,
]);

// gets back an array of values - in the "flat" array like above
$values = $form->getValues();

// returns the values like PHP would see them,
// where "registration" is its own array
$values = $form->getPhpValues();

To work with multi-dimensional fields:

多次元フィールドを操作するには:

    
                        <form>
    <input name="multi[]"/>
    <input name="multi[]"/>
    <input name="multi[dimensional]"/>
    <input name="multi[dimensional][]" value="1"/>
    <input name="multi[dimensional][]" value="2"/>
    <input name="multi[dimensional][]" value="3"/>
</form>

Pass an array of values:

値の配列を渡します。

    
                        // sets a single field
$form->setValues(['multi' => ['value']]);

// sets multiple fields at once
$form->setValues(['multi' => [
    1             => 'value',
    'dimensional' => 'an other value',
]]);

// tick multiple checkboxes at once
$form->setValues(['multi' => [
    'dimensional' => [1, 3] // it uses the input value to determine which checkbox to tick
]]);

This is great, but it gets better! The Form object allows you to interact with your form like a browser, selecting radio values, ticking checkboxes, and uploading files:

これは素晴らしいですが、さらに良くなります！ Form オブジェクトを使用すると、ラジオの値を選択したり、チェックボックスをオンにしたり、ファイルをアップロードしたりして、ブラウザーのようにフォームを操作できます。

    
                        $form['registration[username]']->setValue('symfonyfan');

// checks or unchecks a checkbox
$form['registration[terms]']->tick();
$form['registration[terms]']->untick();

// selects an option
$form['registration[birthday][year]']->select(1984);

// selects many options from a "multiple" select
$form['registration[interests]']->select(['symfony', 'cookies']);

// fakes a file upload
$form['registration[photo]']->upload('/path/to/lucas.jpg');

Using the Form Data ¶

What's the point of doing all of this? If you're testing internally, you can grab the information off of your form as if it had just been submitted by using the PHP values:

これをすべて行う意味は何ですか？内部でテストしている場合は、PHP の値を使用して、送信されたばかりのようにフォームから情報を取得できます。

    
                        $values = $form->getPhpValues();
$files = $form->getPhpFiles();

If you're using an external HTTP client, you can use the form to grab all of the information you need to create a POST request for the form:

外部 HTTP クライアントを使用している場合は、フォームを使用して、フォームの POST リクエストを作成するために必要なすべての情報を取得できます。

    
                        $uri = $form->getUri();
$method = $form->getMethod();
$values = $form->getValues();
$files = $form->getFiles();

// now use some HTTP client and post using this information

One great example of an integrated system that uses all of this is the HttpBrowser provided by the BrowserKit component. It understands the Symfony Crawler object and can use it to submit forms directly:

これらすべてを使用する統合システムの素晴らしい例の 1 つは、BrowserKit コンポーネントによって提供される HttpBrowser です。これは Symfony Crawler オブジェクトを理解し、それを使用してフォームを直接送信できます。

    
                        use Symfony\Component\BrowserKit\HttpBrowser;
use Symfony\Component\HttpClient\HttpClient;

// makes a real request to an external site
$browser = new HttpBrowser(HttpClient::create());
$crawler = $browser->request('GET', 'https://github.com/login');

// select the form and fill in some values
$form = $crawler->selectButton('Sign in')->form();
$form['login'] = 'symfonyfan';
$form['password'] = 'anypass';

// submits the given form
$crawler = $browser->submit($form);

Selecting Invalid Choice Values ¶

By default, choice fields (select, radio) have internal validation activated to prevent you from setting invalid values. If you want to be able to set invalid values, you can use the disableValidation() method on either the whole form or specific field(s):

デフォルトでは、選択肢フィールド (select、radio) は無効な値を設定しないように内部検証が有効になっています。無効な値を設定できるようにしたい場合は、フォーム全体または特定のフィールドで disableValidation() メソッドを使用できます。

    
                        // disables validation for a specific field
$form['country']->disableValidation()->select('Invalid value');

// disables validation for the whole form
$form->disableValidation();
$form['country']->select('Invalid value');

Resolving a URI ¶

The UriResolver class takes a URI (relative, absolute, fragment, etc.) and turns it into an absolute URI against another given base URI:

UriResolver クラスは URI (相対、絶対、フラグメントなど) を受け取り、別の指定されたベース URI に対する絶対 URI に変換します。

    
                        use Symfony\Component\DomCrawler\UriResolver;

UriResolver::resolve('/foo', 'http://localhost/bar/foo/'); // http://localhost/foo
UriResolver::resolve('?a=b', 'http://localhost/bar#foo'); // http://localhost/bar?a=b
UriResolver::resolve('../../', 'http://localhost/'); // http://localhost/

Learn more ¶

Testing
テスト
The CssSelector Component
CssSelector コンポーネント