# Configuration

PHP

> **Note**
>
> **Probe Lifecycle**
>
> Blackfire Probes follow a 180-day decommissioning policy: A specific Probe version remains supported for 180 days after a newer version is released, or 180 days after its upstream runtime reaches end-of-life.
>
> - [View the full deprecation policy](../up-and-running/deprecation-policy)
> - [Go to the upgrade guide](../up-and-running/update)

## Configuring the Probe via Environment Variables

It's preferable that you configure the PHP probe using environment variables. It allows you to change the configuration without modifying your code. You can use the following environment variables:

- `BLACKFIRE_CLIENT_ID` / `BLACKFIRE_CLIENT_TOKEN`

    Sets the client ID and client Token used to authenticate with Blackfire.
- `BLACKFIRE_LOG_LEVEL`

    Sets the verbosity of the Probe's log output. Default value is `1` (error).

    ```bash
    # 1: error
    # 2: warning
    # 3: info
    # 4: debug
    BLACKFIRE_LOG_LEVEL=1
    ```
- `BLACKFIRE_LOG_FILE`

    Defines where the output of the probe logs is sent. Default value is empty.

    ```bash
    BLACKFIRE_LOG_FILE="/tmp/probe.log"
    ```
- `BLACKFIRE_DEBUG_SIGSEGV_HANDLER`

    Add the stacktrace to the probe logs when a segmentation fault occurs.

    Default value is `0` (stacktrace not collected).

    This debug option is inactive on Windows and Alpine.

    ```bash
    BLACKFIRE_DEBUG_SIGSEGV_HANDLER=0
    ```
- `BLACKFIRE_AGENT_SOCKET`

    Defines which socket the Probe contacts the Agent on. Possible values can be a Unix socket or a TCP address.

    The default value is platform dependent, as detailed below.

    On Linux:

    ```bash
    BLACKFIRE_AGENT_SOCKET="unix:///var/run/blackfire/agent.sock"
    ```

    On macOS:

    ```bash
    # amd64
    BLACKFIRE_AGENT_SOCKET="unix:///usr/local/var/run/blackfire-agent.sock"
    
    # arm64 (M1)
    BLACKFIRE_AGENT_SOCKET="unix:///opt/homebrew/var/run/blackfire-agent.sock"
    ```

    On Windows:

    ```bash
    BLACKFIRE_AGENT_SOCKET="tcp://127.0.0.1:8307"
    ```
- `BLACKFIRE_ENDPOINT`

    Defines which API endpoint the profile data is sent to.

    ```bash
    BLACKFIRE_ENDPOINT="https://blackfire.io"
    ```
- `BLACKFIRE_APM_ENABLED`

    Enables or disables Blackfire Monitoring.

    ```bash
    BLACKFIRE_APM_ENABLED=1
    ```
- `BLACKFIRE_APM_ENABLE_AUTOMATIC_BROWSER_PROBE`

    Controls Front-end Observability tracking snippet injection.

    ```bash
    BLACKFIRE_APM_ENABLE_AUTOMATIC_BROWSER_PROBE=1
    ```
- `BLACKFIRE_SERVER_ID` / `BLACKFIRE_SERVER_TOKEN`

    Sets the server ID and server Token used to authenticate with Blackfire. This is optional. Prefer configuring your server credentials in the Agent.

You can set these environment variables in the local `.env` file of your project if supported. Alternatively, you can set them in your global shell configuration file (such as `~/.bashrc` or `~/.zshrc`):

```bash
export BLACKFIRE_CLIENT_ID=xxx
export BLACKFIRE_CLIENT_TOKEN=yyy
export BLACKFIRE_LOG_LEVEL=4
export BLACKFIRE_LOG_FILE=/tmp/probe.log
```

## Configuring the Probe via the Blackfire CLI Client Configuration File

When environment variables are not set, the probe reads its default configuration from the configuration of the Blackfire CLI client. The location of this file depends on the operating system you use. [Read more about the CLI configuration](../up-and-running/configuration/cli).

## Configuring the Probe via the php.ini Configuration File

You can also configure the PHP probe via your `php.ini` configuration file:

```ini
[blackfire]
extension=blackfire.so
; On Windows use the following configuration:
; extension=php_blackfire.dll

; Sets fine-grained configuration for Probe.
; This should be left blank in most cases. For most installs,
; the server credentials should only be set in the agent.
;blackfire.server_id =

; Sets fine-grained configuration for Probe.
; This should be left blank in most cases. For most installs,
; the server credentials should only be set in the agent.
;blackfire.server_token =

; Log verbosity level:
;   4: debug
;   3: info
;   2: warning;
;   1: error
;blackfire.log_level = 1

; Log file (STDERR by default)
;blackfire.log_file = /tmp/blackfire.log

; Add the stacktrace to the probe logs when a segmentation fault occurs.
; Debug option inactive on Windows and Alpine.
;blackfire.debug.sigsegv_handler = 0

; Sets the socket where the agent is listening.
; Possible value can be a unix socket or a TCP address.
; Defaults values are:
;   - Linux: unix:///var/run/blackfire/agent.sock
;   - macOS amd64: unix:///usr/local/var/run/blackfire-agent.sock
;   - macOS arm64 (M1): unix:///opt/homebrew/var/run/blackfire-agent.sock
;   - Windows: tcp://127.0.0.1:8307
;blackfire.agent_socket = unix:///var/run/blackfire/agent.sock

; Enables Blackfire Monitoring
; Enabled by default since version 1.61.0
;blackfire.apm_enabled = 1

; Sets the application name used to filter Blackfire Monitoring data.
; Can also be set with the BLACKFIRE_APP_NAME environment variable.
;blackfire.app_name =

; Controls Front-end Observability tracking snippet injection.
; Enabled by default
;blackfire.apm_enable_automatic_browser_probe = 1
```

> **Note**
>
> If you don't know where your `php.ini` file is located, run this command: `php --ini`

> **Caution**
>
> **We do not recommend configuring server credentials via** `php.ini`.
>
> Make sure you configure your server credentials (server ID and server token) in the Agent. This prevents your server credentials from being shared amongst all virtual hosts.
>
> Only configure your server credentials via `php.ini` if you have multiple Blackfire environments, each with a dedicated server, and all your servers are configured to communicate with the same agent.
>
> In other specific cases, you might want to configure different credentials on a per-host/per-directory basis.

## Configuring the Probe via the Web Server Configuration

Make sure you configure your server credentials `blackfire.server_id` and `blackfire.server_token` in the agent. Only configure your server credentials on a virtual host-by-virtual host basis if you meet one of the following sets of requirements:

- You have multiple Blackfire environments, multiple virtual hosts on a server, and want to assign specific Blackfire environments to specific virtual hosts.
- You have one or more Blackfire environments, multiple virtual hosts on a server, and want to only allow Blackfire profiling on a subset of your virtual hosts.

> **Caution**
>
> The default credentials set in the Agent are used as default fallback, so **do not** set default credentials in your `php.ini` file.

### Nginx Configuration Settings

You can override the default credentials of the Probe in the Nginx configuration via the `http`, `server`, and `location` sections. For more information, see the [Nginx documentation](https://nginx.org/en/docs/http/ngx_http_fastcgi_module.html#fastcgi_param).

> **Note**
>
> Make sure you configure **all the hosts** served by a PHP-FPM pool.

> **Tip**
>
> If you want a host to use the default credentials, set empty values:
>
> ```text
> location / {
>   fastcgi_param PHP_VALUE "
>     blackfire.server_id=
>     blackfire.server_token=
> ";
> }
> ```

### Apache Configuration Settings

You can override the default credentials of the Probe in the main Apache virtual-host configuration or via a `.htaccess` file.

Use the following example to adjust your configuration. For more information, see the [PHP documentation](https://www.php.net/manual/en/configuration.changes.php).

### PHP-FPM Pool Configuration Settings

You can override the default credentials of the Probe per PHP-FPM pool. Open the `php-fpm.conf` file and amend the settings. Use the following example for reference or the [FPM documentation](https://www.php.net/manual/en/install.fpm.configuration.php).

> **Note**
>
> If your app is behind a cache server, a load balancer, or any other reverse proxy, make sure you [bypass it](../up-and-running/reverse-proxies).