システム開発 – spatie/browsershotのメソッド一覧

参照：chrome-php / headless-chromium-php

1. クラスの作成
2. 初期設定
   • node及びnpmの実行ファイルの指定 – setNodeBinary() / setNpmBinary()
   • node及びnpmの実行ファイルのあるディレクトリの変更 – setIncludePath()
   • 別のnode_modulesの指定 – setNodeModulePath()
   • 別のスクリプトの指定 – setBinPath()
   • 他の場所にあるchrome/chromiumの実行ファイルの指定 – setChromePath()
   • 引数をChromiumに渡す – addChromiumArguments()
3. 対象の設定
   • 対象のURL又はHTMLの設定 – url() / setUrl() / html() / setHtml()
4. 書き出し
   • ファイルの保存 – save()
   • 明示的なPDFの保存 – savePdf()
   • 画像をブラウザに直接出力 – screenshot()
   • PDFをブラウザに直接出力 – pdf()
   • HTMLソースの取得 – bodyHtml()
   • base64として画像の取得 – base64Screenshot()
   • ページが出力した全リクエストの配列を取得 – triggeredRequests()
5. 画像の設定
   • 画像のフォーマット – setScreenshotType()
   • 画像のエフェクト効果
   • 画像サイズの設定 – windowSize()
   • ページの一部を取得 – clip()
   • ページ全体の画像を取得 – fullPage()
6. PDFの設定
   • PDFのサイズ設定 – paperSize()
   • 定義済みのフォーマットの使用 – format()
   • マージンの設定 – margins()
   • ヘッダーとフッター – showBrowserHeaderAndFooter() / hideBrowserHeaderAndFooter() / hideHeader() / hideFooter()
   • カスタムヘッダー/フッターの表示 – headerHtml() / footerHtml()
   • ドキュメントの横向き設定 – landscape()
   • エクスポート範囲の指定 – pages()
7. 表示設定
   • 遅延させる – delay()
   • javascript関数 – waitForFunction()
   • Lazyロードの待機 – waitUntilNetworkIdle()
   • 遅延スクリーンショット – setDelay()
   • Javascriptを無効にする – disableJavascript()
   • 画像を無効にする – disableImages()
   • URL/ドメインのブロック – blockUrls() – blockDomains()
   • 背景の設定 – hideBackground() / showBackground()
   • デバイススケールの設定 – deviceScaleFactor()
8.  エミュレート
   • モバイルエミュレーション – mobile()
   • デバイスエミュレーション – device()
   • ユーザーエージェントの設定 – userAgent()
   • メディアタイプ別CSSの指定 – emulateMedia()
9. 操作
   • 要素の取得 – select()
   • ページをクリック – click()
   • ページに入力 – type()
   • セレクトメニューの選択 – selectOption()
   • HTTP認証の使用 – authenticate()
   • ダイアログを閉じる – dismissDialogs()
10. 様々なsetOption
    • JS又はCSSの追加
    • 任意のオプションの設定
    • corsの問題の修正
    • ブラウザの言語の変更
11. その他
    • 評価する – evaluate()
    • タイムアウト時間の設定 – timeout()
    • サンドボックスの無効化 – noSandbox()
    • HTTPSエラーの無視 – ignoreHttpsErrors()
    • プロキシサーバーの指定 – setProxyServer()
    • HTTPヘッダーの送信 – setExtraHttpHeaders()
    • クッキーの使用 – useCookies()
    • ファイルへのオプションの書き込み – writeOptionsToFile()
    • chromium/chromeインスタンスへのリモート接続 – setRemoteInstance()
    • WebSocketの代わりにパイプの使用 – usePipe()
12. 未解説
    • __call
    • applyManipulations
    • createBodyHtmlCommand
    • createScreenshotCommand
    • createPdfCommand
    • createEvaluateCommand
    • createTriggeredRequestsListCommand
    • setWSEndpoint

クラスの作成

$urlを設定することにより、最初のURLを同時に設定できます。

書式

Browsershot(string $url = '', bool $deviceEmulate = false)

※$deviceEmulateがfalseで、windowSizeの初期値が800×600pxに設定されます。

例

use Spatie\Browsershot\Browsershot;

$url = 'http://www.yahoo.co.jp';
$bs = new Browsershot($url);

※以下$bsを流用

初期設定

node及びnpmの実行ファイルの指定

書式

setNodeBinary(string $nodeBinary)
setNpmBinary(string $npmBinary)

例

// nodeの実行ファイルの指定
$bs->setNodeBinary('/usr/local/bin/node');
// npmの実行ファイルの指定
$bs->setNpmBinary('/usr/local/bin/npm');

node及びnpmの実行ファイルのあるディレクトリの変更

書式

setIncludePath(string $includePath)

例

$bs->setIncludePath('$PATH:/usr/local/bin');

別のnode_modulesの指定

書式

setNodeModulePath(string $nodeModulePath)

例

$bs->setNodeModulePath("/path/to/my/project/node_modules/");

別のスクリプトの指定

書式

setBinPath(string $binPath)

例

$bs->setBinPath("/path/to/my/project/my_script.js");

他の場所にあるchrome/chromiumの実行ファイルの指定

puppeteerによりインストールされたchrome/chromiumから変更する場合に設定します。

書式

setChromePath(string $executablePath)

例

$bs->setChromePath("/path/to/my/chrome");

引数をChromiumに渡す

Chromiumに引数を渡す必要がある場合に使用します。key/valueのarray形式、または単に値で指定できます。これらの引数はすべて、自動的に接頭辞--が付きます。

書式

addChromiumArguments(array $arguments)

例

$bs->addChromiumArguments([
      'some-argument-without-a-value',
      'keyed-argument' => 'argument-value',
  ]);

keyの指定が無い場合には、引数はそのまま渡されます。

このメソッドは、一部のLinuxディストリビューション（CentOSなど）で、フォントレンダリングの問題を修正するためのフラグを渡すために利用できます。

$bs->addChromiumArguments([
      'font-render-hinting' => 'none',
  ]);

対象の設定

対象のURL又はHTMLの設定

$url又は$htmlのどちらかのみ設定可能です。両方設定しても、後から設定した方が優先されます。

書式

// URLで指定
url(string $url)
setUrl(string $url)
// HTMLを指定
html(string $html)
setHtml(string $html)

例

// URLを設定する
$url = 'http://www.yahoo.co.jp';
$bs->url($url)->save('example.pdf');
// 又は
$bs->setUrl($url)->save('example.pdf');

// HTMLを設定する
$html = '<h1>Hello world!!</h1>';
$bs->html($html)->save('example.pdf');
// 又は
$bs->setHtml($html)->save('example.pdf');

書き出し

ファイルの保存

saveメソッドに渡されたパスの拡張子がpdfの場合、PDFを作成します。

書式

save(string $targetPath)

例

// スクリーンショットの保存
$bs->save('sample.jpg');

// PDFで保存
$bs->save('example.pdf');

明示的なPDFの保存

書式

savePdf(string $targetPath)

例

$bs->savePdf('example.pdf');

画像をブラウザに直接出力

書式

screenshot(): string

例

$image = $bs->screenshot();

// 画像を表示
header('Content-type:  image/jpg');
echo $image;

PDFをブラウザに直接出力

書式

pdf(): string

例

$pdf = $bs->pdf()

// PDFを表示
header('Content-Type: application/pdf');
echo $pdf;

HTMLソースの取得

htmlタグを含む全体のソースを取得します。この場合、取得するHTMLはJavaScript実行後のHTMLです。

書式

bodyHtml(): string

例

$html = $bs->bodyHtml();

base64として画像の取得

画像をbase64にエンコードして保存したい場合に使用します。

書式

base64Screenshot(): string

例

$base64Data = $bs->base64Screenshot();

ページが出力した全リクエストの配列を取得

書式

triggeredRequests(): array

例

$requests = $bs->triggeredRequests();

foreach ($requests as $request) {
    // https://example.com/形式
    $url = $request['url'];
}

画像の設定

画像のフォーマット

デフォルトは、png形式です（Puppeteerの設定）。jpeg形式の場合は、圧縮率を変更できます。

書式

setScreenshotType(string $type, int $quality = null)

例

$bs->setScreenshotType('jpeg', 100)
   ->save($pathToImage);

画像のエフェクト効果

spatie/imageの全てのメソッドを使用できます。グレースケール画像を作成する例を下記の通りです。

$bs->greyscale()
   ->save($pathToImage);

その他のEffectメソッド

• blur(int $val)
• pixelate(int $val)
• greyscale()
• sepia()
• sharpen(int $val)

参照：spatie/image Effects

画像サイズの設定

クラスの作成時、$deviceEmulateの設定を変更しない場合は、サイズは800×600pxとなります。特に設定が無い場合のデフォルトは、デスクトップの解像度となります。

書式

windowSize(int $width, int $height)

例

$bs->windowSize(640, 480)
   ->save($pathToImage);

デスクトップのサイズとは関係なく、出力サイズを設定することもできます。サイズを1920×1080pxの解像度で変更し、200×200pxの範囲内に収まるように縮小するには下記のように記述します。

use Spatie\Image\Manipulations;

$bs->windowSize(1920, 1080)
   ->fit(Manipulations::FIT_CONTAIN, 200, 200)
   ->save($pathToImage);

その他ののResizeメソッド

• FIT_CONTAIN
• FIT_MAX
• FIT_FILL
• FIT_STRETCH
• FIT_CROP

参照：spatie/image Resizing images

ページの一部を取得

clipメソッドを使用することで、ページの一部のみを取得できます。

書式

clip(int $x, int $y, int $width, int $height)

例

$bs->clip($x, $y, $width, $height)
   ->save($pathToImage);

ページ全体の画像を取得

ページの上部から下部までの全体の画像を取得します。

書式

fullPage()

例

$bs->fullPage()
   ->save($pathToImage);

PDFの設定

PDFのサイズ設定

幅と高さで指定します。単位のデフォルトはmmです。

書式

paperSize(float $width, float $height, string $unit = 'mm')

例

$bs->paperSize($width, $height)
   ->save('example.pdf');

定義済みのフォーマットの使用

書式

format(string $format)

例

$bs->format('A4')
   ->save('example.pdf');

puppeteerで設定されているフォーマット

• Letter: 8.5×11in
• Legal: 8.5×14in
• Tabloid: 11×17in
• Ledger: 17×11in
• A0: 33.1×46.8in
• A1: 23.4×33.1in
• A2: 16.54×23.4in
• A3: 11.7×16.54in
• A4: 8.27×11.7in
• A5: 5.83×8.27in
• A6: 4.13×5.83in

マージンの設定

デフォルトの単位はmmです。

書式

margins(float $top, float $right, float $bottom, float $left, string $unit = 'mm')

例

$bs->margins($top, $right, $bottom, $left)
   ->save('example.pdf');

ヘッダーとフッターの表示

書式

// ヘッダー及びフッターの表示
showBrowserHeaderAndFooter()

// ヘッダー及びフッターを非表示
hideBrowserHeaderAndFooter()
// ヘッダーを非表示
hideHeader() 
// フッターを非表示
hideFooter()

ヘッダー

• 左上：印刷日。フォーマットはm/d/Y
• 右上：ドキュメントタイトル

フッター

• 左下：ドキュメントの場所
• 右下：ページ番号。フォーマットは、pageNumber/totalPages

例

$bs->showBrowserHeaderAndFooter()
   ->margins(15, 0, 15, 0)
   ->save('example.pdf');

※上下に適切なマージンが必要。

カスタムヘッダー/フッターの表示

ヘッダー、フッターをカスタマイズしたい場合に設定します。
表示には、上下に適切なマージン及びフォントサイズを一定のサイズに設定することで表示されます。
現段階では、確実とは言えませんが、外部CSSが効かなさそう（埋め込みのみ）で、また、flexも使用できなさそうです（要確認）。

書式

// ヘッダーHTMLの設定
headerHtml(string $html)
// フッターHTMLの設定
footerHtml(string $html)

ヘッダー及びフッターのHTMLに、次のclassを設定することで各値が挿入されます。

• date フォーマットされた印刷日
• title ドキュメントのタイトル
• url ドキュメントの場所
• pageNumber 現在のページ番号
• totalPages ドキュメントの総ページ数

例

$headerHtml = '<div id="header" style="font-size:10px;"><span class="title"></span></di>';
$footerHtml = '<div id="footer" style="font-size:10px">url:<span class="url"></span><span class="pageNumber"></span> of <span class="totalPages"></span>date:<span class="date"></span></div>';

$bs->showBrowserHeaderAndFooter()
   ->headerHtml($headerHtml)
   ->footerHtml($footerHtml)
   ->margins(15, 0, 15, 0)
   ->save('example.pdf');

※上記の例では、各フォントサイズを10px、上下に15mmのマージンを取っています。

ドキュメントの横向き設定

書式

landscape(bool $landscape = true)

例

$bs->landscape()
   ->save('example.pdf');

エクスポート範囲の指定

エクスポートする範囲を指定します。指定方法は、1、1-3、 1-5, 8, 11-13のように行います。

書式

pages(string $pages)

例

$bs->pages('1-5, 8, 11-13')
   ->save('example.pdf');

表示設定

遅延させる

書式

delay(int $delayInMilliseconds)

例

$bs->delay($millisecondsToWait)
   ...;;

javascript関数

waitForFunction()メソッドを使用して、javascriptの関数がtrueを返すまで待たせることができます。これは、ネットワークスの状態に関係していないJavaScriptで結果を待つ場合に利用できます。

書式

waitForFunction(string $function, $polling = self::POLLING_REQUEST_ANIMATION_FRAME, int $timeout = 0)

例

$bs->waitForFunction('window.innerWidth < 100', $pollingInMilliseconds, $timeoutInMilliseconds)
   ->save($pathToImage);

Lazyロードの待機

一部のWebサイトでは、ajaxで追加のリソースを遅延ロードしたり、画像の取得時に表示しきれないWebフォントを使用していたりします。このwaitUntilNetworkIdle()メソッドを使用すると、画像の取得前に、ネットワークのアイドル状態で500ミリ秒待機するようにBrowsershotに指示し、すべての追加リソースがロードされたことを確認します。

書式

waitUntilNetworkIdle(bool $strict = true)

例

$bs->waitUntilNetworkIdle()
   ->save($pathToImage);

また、$strictをfalseにすることにより、曖昧な使用をすることもできます。これにより、500ミリ秒の待機中に2つのネットワーク接続を可能にするので、スクリプトがajaxで定期的にpingを実行するWebサイトで利用できます。

遅延スクリーンショット

setDelay()メソッドにより、画像の取得を遅らせることができます 。これは、JavaScriptの完了を待つ必要がある場合や、遅延読み込みされたリソースをキャプチャしようとする場合に利用できます。

書式

setDelay(int $delayInMilliseconds)

例

$bs->setDelay($delayInMilliseconds)
   ->save($pathToImage);

Javascriptを無効にする

ページをキャプチャするときにJavaScriptを無効にする場合に使用します。一部のサイトはjavascriptがないと正しくレンダリングされないことに注意してください。

書式

disableJavascript()

例

$bs->disableJavascript()
   ->save($pathToImage);

画像を無効にする

Webページのキャプチャ時に、すべての画像や要素を削除します

書式

disableImages()

例

$bs->disableJavascript()
   ->save($pathToImage);

URL/ドメインのブロック

特定のURLへの接続をブロックします。画像作成の高速化のため、広告やトラッカーをブロックする場合に利用します。

書式

// URLのブロック
blockUrls($array)
// ドメインのブロック
blockDomains($array)

例

// ブロックするURLの配列を作成
$urlsList = array("example.com/cm-notify?pi=outbrain", "sync.outbrain.com/cookie-sync?p=bidswitch");
// 対象のURLをブロック
$bs->blockDomains($urlsList)
   ->save($pathToImage);

// ブロックするドメインの配列を作成
$domainsList = array("googletagmanager.com", "googlesyndication.com", "doubleclick.net", "google-analytics.com");
Browsershot::url('https://example.com')
    ->blockDomains($domainsList)
    ->save($pathToImage);

背景の設定

キャプチャの際、Webサイトの背景の表示を設定します。

書式

// 背景の非表示
hideBackground()
// 背景の表示（デフォルト）
showBackground()

例

// 画像の取得
$bs->hideBackground()
   ->save($pathToImage);

// PDFの作成
$bs->hideBackground()
   ->save('example.pdf');

デバイススケールの設定

2または3（デフォルトは1）のデバイスごとの拡大率の値を設定することで、より高いピクセル密度でWebページをキャプチャできます。これは、Webページがretina/xhdpiディスプレイに表示される方法と同様です。

書式

deviceScaleFactor(int $deviceScaleFactor)

例

$bs->deviceScaleFactor(2)
   ->save($pathToImage);

エミュレート

モバイルエミュレーション

mobile及びtouchメソッドを使用してモバイルビューをエミュレートできます。 mobileメソッドは、モバイル版Chromeと同様に、ページのメタviewportを考慮して表示します。touchメソッドは、画面タッチの機能をエミュレートするため、タッチを感知するページのなりすましが可能になります。userAgentメソッドを使って、モバイルページの画像を効果的に取得することができます。

書式

mobile(bool $mobile = true)
touch(bool $touch = true)
userAgent(string $userAgent)

例

$bs->userAgent('My Mobile Browser 1.0')
   ->mobile()
   ->touch()
   ->save($pathToImage);

デバイスエミュレーション

直接デバイス名を使用して、モバイルエミュレーションに各デバイス用の詳細設定を追加して同様のエミュレートができます。
参照：デバイス名一覧

書式

device(string $device)

例

$bs = new Browsershot('https://example.com', true);
$bs->device('iPhone X')
   ->save($pathToImage);

下記は上記と同じです。

$bs->userAgent('Mozilla/5.0 (iPhone; CPU iPhone OS 11_0 like Mac OS X) AppleWebKit/604.1.38 (KHTML, like Gecko) Version/11.0 Mobile/15A372 Safari/604.1')
   ->windowSize(375, 812)
   ->deviceScaleFactor(3)
   ->mobile()
   ->touch()
   ->landscape(false)
   ->save($pathToImage);

ユーザーエージェントの設定

書式

userAgent(string $userAgent)

例

$bs->userAgent('My Special Snowflake Browser 1.0')
   ->save($pathToImage);

メディアタイプ別CSSの指定

メディアタイプ別のエミュレートが可能です。これによりPDF作成時に、デフォルトでページをprintバージョンでエミュレートすることができます。

書式

emulateMedia(?string $media)

例

// "screen", "print" (デフォルト)又はnull（エミュレートが無効になる）
$bs->emulateMedia('screen')
   ->savePdf($pathToPdf);

操作

要素の取得

selectメソッドを使用することで、セレクター$selectorに一致する要素を取得できます。

書式

select($selector)

例

$bs->select('.some-selector')
   ->save($pathToImage);

ページをクリック

書式

click(string $selector, string $button = 'left', int $clickCount = 1, int $delay = 0)

例

$bs->click('#selector1')
    // #selector2要素に対し右クリックを5回, 各クリックは200ミリ秒間継続
    ->click('#selector2', 'right', 5, 200);

ページに入力

フォームフィールドなど、ページに入力をします。

書式

type(string $selector, string $text = '', int $delay = 0)

例

$bs->type('#selector1', 'Hello, is it me you are looking for?');

// 入力/フォーム送信/一定時間待ち/画像取得
$bs->type('#firstName', 'My name')
    ->click('#submit')
    ->delay($millisecondsToWait)
    ->save($pathToImage);

セレクトメニューの選択

書式

selectOption(string $selector, string $value = '')

例

$bs->selectOption('#selector1', '100'):

// 入力/セレクトメニュー選択/フォーム送信/一定時間待ち/画像取得
$bs->type('#firstName', 'My name')
   ->selectOption('#state', 'MT')
   ->click('#submit')
   ->delay($millisecondsToWait)
   ->save($pathToImage);

HTTP認証の使用

BASIC認証の情報提供ができます。

書式

authenticate(string $username, string $password)

例

$bs->authenticate('username', 'password')
   ...;

ダイアログを閉じる

アラート、プロンプト、確認などのJavascriptのポップアップにより、サイトのレンダリングが停止し、画像が空になります。dismissDialogs()

メソッドを呼び出すと、そのようなポップアップが自動的に閉じられ、画像を取得することができます。

書式

dismissDialogs()

例

$bs->dismissDialogs()
   ->save($pathToImage);

様々なsetOption

JS又はCSSの追加

PuppeteerのaddScriptTag又はaddStyleTagを使用して、画像の取得や出力前にJavaScript又はCSSを追加します。

書式

setOption($key, $value)

例

// jsの追加
$bs->setOption('addScriptTag', json_encode(['content' => 'alert("Hello World")']))
   ->save($pathToImage);

// cssの追加
$bs->setOption('addStyleTag', json_encode(['content' => 'body{ font-size: 14px; }']))
   ->save($pathToImage);

書式

setOption($key, $value)

任意のオプションの設定

例

$bs->setOption('landscape', true)
   ->save($pathToImage);

corsの問題の修正

corsに関連する問題が発生した場合は、-disable-web-securityを使用してcorsチェックを無効にできます。

例

$bs->setOption('args', ['--disable-web-security'])
   ...;

ブラウザの言語の変更

特定の言語でページをロードするなど、ブラウザの言語を変更するために使用できます。

例

$bs-->setOption('args', '--lang=en-GB')
   ->save($pathToImage);

その他

評価する

htmlページの評価を取得できます。

書式

evaluate(string $pageFunction): string

例

$bs->deviceScaleFactor(2)
   ->evaluate("window.devicePixelRatio");
// return 2

タイムアウト時間の設定

デフォルトは60秒です。

書式

timeout(int $timeout)

例

$bs->timeout(120)
   ->save($pathToImage);

サンドボックスの無効化

書式

noSandbox()

例

$bs->noSandbox()
   ...;

HTTPSエラーの無視

書式

ignoreHttpsErrors()

例

$bs->ignoreHttpsErrors()
   ...;

プロキシサーバーの指定

接続時に使用するプロキシサーバーの指定ができます。setProxyServerに渡された引数は、Chromiumの--proxy-server=オプションに渡されます。詳細はこちら：https：//www.chromium.org/developers/design-documents/network-settings#TOC-Command-line-options-for-proxy-settings

書式

setProxyServer(string $proxyServer)

例

$bs->setProxyServer("1.2.3.4:8080")
   ...;

HTTPヘッダーの送信

書式

setExtraHttpHeaders(array $extraHTTPHeaders)

例

$bs->setExtraHttpHeaders(['Custom-Header-Name' => 'Custom-Header-Value'])
   ...;

クッキーの使用

書式

useCookies(array $cookies, string $domain = null)

例

// 指定されたページへCookieの追加
$bs->useCookies(['Cookie-Key' => 'Cookie-Value'])
   ...;

// ドメインに対しCookieの追加
$bs->useCookies(['Cookie-Key' => 'Cookie-Value'], 'ui.example.com')
   ...;

ファイルへのオプションの書き込み

puppeteerに与えられるオプションの量が大きくなりすぎると、コマンドラインの文字がオーバーフローするためにBrowsershotが失敗します。 Browsershotは、オプションをファイルに書き込んでpuppeteerに渡すことができるため、文字のオーバーフローによるエラーを回避できます。

書式

writeOptionsToFile()

例

$bs->writeOptionsToFile()
   ...;

chromium/chromeインスタンスへのリモート接続

実行中のchromium / chromeインスタンスのリモートエンドポイントがあり、param –remote-debugging-portで適切に構成されている場合は、setRemoteInstanceメソッドを使用して接続できます。 IPとポートを指定するだけです（デフォルトは127.0.0.1と9222です）。 特定のエンドポイントで使用可能なインスタンスがない場合（インスタンスのクラッシュ、インスタンスの再起動など）、chromiumインスタンスの起動を行います。

書式

setRemoteInstance(string $ip = '127.0.0.1', int $port = 9222): self

例

$bs->setRemoteInstance('1.2.3.4', 9222)
   ...;

WebSocketの代わりにパイプの使用

WebSocketの代わりにパイプを介してブラウザーに接続する場合に使用します。

書式

usePipe(): self

例

$bs->usePipe()
   ...;

未解説

__call

書式

__call($name, $arguments)

applyManipulations

書式

applyManipulations(string $imagePath)

createBodyHtmlCommand

書式

createBodyHtmlCommand(): array

createScreenshotCommand

書式

createScreenshotCommand($targetPath = null): array

createPdfCommand

書式

createPdfCommand($targetPath = null): array

createEvaluateCommand

書式

createEvaluateCommand(string $pageFunction): array

createTriggeredRequestsListCommand

書式

createTriggeredRequestsListCommand(): array

setWSEndpoint

書式

setWSEndpoint(string $endpoint): self