Configuring a run | lighthouse-php | Spatie

 SPATIE

  Lighthouse PHP
=================

spatie.be/open-source

  [Docs](https://spatie.be/docs)  [Lighthouse-php](https://spatie.be/docs/lighthouse-php/v2)  Usage  Configuring a run

 Version   v2

 Other versions for crawler [v2](https://spatie.be/docs/lighthouse-php/v2)

- [ Introduction ](https://spatie.be/docs/lighthouse-php/v2/introduction)
- [ Support us ](https://spatie.be/docs/lighthouse-php/v2/support-us)
- [ Requirements ](https://spatie.be/docs/lighthouse-php/v2/requirements)
- [ Installation & setup ](https://spatie.be/docs/lighthouse-php/v2/installation-setup)
- [ Questions and issues ](https://spatie.be/docs/lighthouse-php/v2/questions-issues)
- [ Changelog ](https://spatie.be/docs/lighthouse-php/v2/changelog)
- [ About us ](https://spatie.be/docs/lighthouse-php/v2/about-us)

Usage
-----

- [ Generating your first report ](https://spatie.be/docs/lighthouse-php/v2/usage/generating-your-first-report)
- [ Configuring a run ](https://spatie.be/docs/lighthouse-php/v2/usage/configuring-a-run)
- [ Working with results ](https://spatie.be/docs/lighthouse-php/v2/usage/working-with-results)
- [ Saving an HTML report ](https://spatie.be/docs/lighthouse-php/v2/usage/saving-an-html-report)
- [ Using performance budgets ](https://spatie.be/docs/lighthouse-php/v2/usage/using-performance-budgets)

 Configuring a run
=================

###  On this page

1. [ Only run audits in certain categories ](#content-only-run-audits-in-certain-categories)
2. [ Skip certain audits ](#content-skip-certain-audits)
3. [ Only run specific audits ](#content-only-run-specific-audits)
4. [ Customizing the user agent ](#content-customizing-the-user-agent)
5. [ Setting extra headers ](#content-setting-extra-headers)
6. [ Specifying the form factor ](#content-specifying-the-form-factor)
7. [ Enable throttling ](#content-enable-throttling)
8. [ Customize the Lighthouse configuration ](#content-customize-the-lighthouse-configuration)
9. [ Customize the Chrome options ](#content-customize-the-chrome-options)
10. [ Setting a timeout ](#content-setting-a-timeout)

There are various methods to configure how Lighthouse should run. You can use these between the `url()` and `run()`. Here's an example where we set a custom user agent.

```
use Spatie\Lighthouse\Lighthouse;
// returns an instance of Spatie\Lighthouse\LighthouseResult
$result = Lighthouse::url('https://example.com')
    ->userAgent('my-custom-user-agent')
    ->run();
```

Only run audits in certain categories
-----------------------------------------------------------------------------------------------------------------------------------------------------------------------

By default, Lighthouse will run audits of all categories. To only run the audits of certain categories, call `categories()` and pass it one or more categories you are interested in.

```
use Spatie\Lighthouse\Enums\Category;
use Spatie\Lighthouse\Lighthouse;

$result = Lighthouse::url('https://example.com')
    ->categories(Category::BestPractices, Category::Seo)
    ->run();
```

Skip certain audits
-----------------------------------------------------------------------------------------------------------------

To lower Lighthouse's execution time, you can opt to skip audits by passing their names to `skipAudits`.

```
use Spatie\Lighthouse\Lighthouse;

$result = Lighthouse::url('https://example.com')
    ->skipAudits(['is-on-https', 'service-worker'])
    // ...
```

Only run specific audits
--------------------------------------------------------------------------------------------------------------------------------

You can opt to run only specific audits using the `onlyAudits()` method.

```
use Spatie\Lighthouse\Lighthouse;

$result = Lighthouse::url('https://example.com')
    // only these two audits can be run
    ->onlyAudits(['is-on-https', 'service-worker'])
    // ...
```

You cannot use `skipAudits` and `onlyAudits` at the same time.

If you want to run a specific audit and an entire other category. You must call `categories()` after `onlyAudits()`.

In this example we are going to run the `is-on-https` audit together with all audits from the `Seo` category.

```
use Spatie\Lighthouse\Enums\Category;
use Spatie\Lighthouse\Lighthouse;

$result = Lighthouse::url('https://example.com')
    ->onlyAudits('is-on-https')
    ->categories(Category::Seo)
```

Customizing the user agent
--------------------------------------------------------------------------------------------------------------------------------------

To use a custom user agent, pass a string to `userAgent()`.

```
use Spatie\Lighthouse\Lighthouse;

$result = Lighthouse::url('https://example.com')
    ->userAgent('my-custom-user-agent')
    ->run();
```

Setting extra headers
-----------------------------------------------------------------------------------------------------------------------

You can specify headers that will be sent along with all requests.

```
use Spatie\Lighthouse\Lighthouse;

$result = Lighthouse::url('https://example.com')
    ->headers(['MyExtraHeader' => 'value of the header'])
    ->run();
```

Specifying the form factor
--------------------------------------------------------------------------------------------------------------------------------------

By default, Lighthouse will use a "Desktop" profile to run audits. You can change this to "mobile" using the `formFactor()` method.

```
use Spatie\Lighthouse\Enums\FormFactor;
use Spatie\Lighthouse\Lighthouse;

$result = Lighthouse::url('https://example.com')
    ->formFactor(FormFactor::Mobile)
    ->run();
```

Enable throttling
-----------------------------------------------------------------------------------------------------------

By default, Lighthouse will not throttle CPU and connection speed.

To enable throttling, use these methods.

```
use Spatie\Lighthouse\Lighthouse;

$result = Lighthouse::url('https://example.com')
    ->throttleCpu()
    ->throttleNetwork()
    ->run();
```

Optionally, you can pass a `cpuSlowdownMultiplier` as an int to `throttleCpu()`. The higher the number, the more throttling is applied. You'll find more information on this number [in the lighthouse docs](https://github.com/GoogleChrome/lighthouse/blob/main/docs/throttling.md#cpu-throttling).

Customize the Lighthouse configuration
--------------------------------------------------------------------------------------------------------------------------------------------------------------------------

To have fine-grained control of which options will be sent to lighthouse, you can pass an array of options to `withConfig`.

```
use Spatie\Lighthouse\Lighthouse;

$result = Lighthouse::url('https://example.com')
    ->withConfig($arrayWithOptions)
    ->run();
```

If you don't call this method, we'll use these options by default.

```
[
    'extends' => 'lighthouse:default',
    'settings' => [
        'onlyCategories' => Category::values(),
        'emulatedFormFactor' => 'desktop',
        'output' => ['json', 'html'],
        'disableNetworkThrottling' => true,
        'disableCpuThrottling' => true,
        'throttlingMethod' => 'provided',
    ],
];
```

To get a hold of the default options, you can call `defaultLighthouseConfig()`.

Customize the Chrome options
--------------------------------------------------------------------------------------------------------------------------------------------

Under the hood, Lighthouse will run an instance of Chrome to run the audits. You can customize the options give to Chrome using `withChromeOptions()`

```
use Spatie\Lighthouse\Lighthouse;

$result = Lighthouse::url('https://example.com')
    ->withChromeOptions($arrayWithOptions)
    ->run();
```

If you don't call this method, we'll use these options by default.

```
[
    'chromeFlags' => [
        '--headless',
        '--no-sandbox',
],
```

To get a hold of the default options, you can call `defaultChromeOptions()`.

Setting a timeout
-----------------------------------------------------------------------------------------------------------

By default, if the lighthouse process takes more than 60 seconds it will be aborted and a `Symfony\Component\Process\Exception\ProcessTimedOutException` will be thrown.

You can adjust the timeout using the `timeoutInSeconds()` method.

```
use Spatie\Lighthouse\Lighthouse;

$result = Lighthouse::url('https://example.com')
    ->timeoutInSeconds(120) // allow to run 120 seconds
    ->run();
```