---
title: PHP per-directory INI settings
source: https://docs.newrelic.com/docs/apm/agents/php-agent/configuration/php-directory-ini-settings
---

Most [PHP agent configuration variables](https://docs.newrelic.com/docs/php/php-agent-phpini-settings) can be set on a per-directory basis. This option is often used when there is a single web server serving multiple applications, and you want to adjust settings (for example, the app name) on an application-by-application basis.

The process for setting per-directory values depends on the environment. This document describes the three most common environments:

-   [Apache](#perdir-apache)
-   [PHP-FPM](#php-fpm_per-dir)
-   [NGINX](#PHP-FPM_nginix)

For other app naming options, see [Name your PHP application](https://docs.newrelic.com/docs/agents/php-agent/configuration/name-your-php-application).

## Apache per-directory settings for PHP [#perdir-apache]

When using the PHP module, Apache provides two mechanisms for setting PHP variables outside the INI file:

**Edit the `httpd.conf` file or one of the files it includes.**

Use the syntax from the INI file examples when your web server serves up multiple domains. To view each of these domains separately in New Relic:

1.  For your main domain, set `newrelic.appname = "My Main Domain"` in your global INI file.
2.  Override the value for each of the virtual hosts by adding `php_value` entries as part of your virtual host configuration.

    > #### ⚠️ IMPORTANT
    >
    > Ensure you use the proper module name for your PHP install. Replace `PHP_MODULE` in the examples below with the name of the installed PHP5 module. This name depends on the Linux and/or PHP distribution being used. For example, common names include `php5_module`, `mod_php5`, `php_module`, etc. Capitalization may vary.

    For Apache servers, you can find the module names in one of the following ways. Each will generate a list of installed modules.

-   From the command line, run:

    ```bash
    apachectl -t -D DUMP_MODULES
    ```

    **OR**

-   From within a webpage, use:

    ```php
    <?php
      print_r(apache_get_modules());
    ?>
    ```

    **Setting appname by domain**

    Here is an example of separating domains, where `PHP_MODULE` is the name of your PHP5 module.

    ````apacheconf
    <VirtualHost 192.168.42.43>
      ServerName www.myvhost1.com
      DocumentRoot "/path/to/vhost1/"
      ...
      <IfModule PHP_MODULE>
        php_value newrelic.appname "Virtual Host 1"
      </IfModule>
    </VirtualHost>

    <VirtualHost 192.168.123.45>
      ServerName www.myvhost2.com
      DocumentRoot "/path/to/vhost2/"
      ...
      <IfModule PHP_MODULE>
        php_value newrelic.appname "Virtual Host 2"
      </IfModule>
    </VirtualHost>
    ```

    In the above example, `newrelic.appname` is set to a different value for each virtual host.

    ````

    For string and number values, use `php_value name VALUE`, where:

-   `name` is the name of the INI setting to modify as listed in the [PHP INI settings](https://docs.newrelic.com/docs/php/php-agent-phpini-settings).

-   `VALUE` is the value you want to set to for that particular virtual host.

    Be sure to surround string values in quotes marks `"`.

    If you want to change a boolean setting, use the syntax `php_flag name VALUE`, where `name` is the variable name as listed in the [PHP INI settings](https://docs.newrelic.com/docs/php/php-agent-phpini-settings), and `VALUE` is either `on` or `off`.

    To disable the New Relic agent completely for a virtual host, use a boolean flag:

    ```apacheconf
    <VirtualHost 192.168.56.78>
      ServerName www.myvhost3.com
      DocumentRoot "/path/to/vhost3/"
      ...
      <IfModule PHP_MODULE>
        php_flag newrelic.enabled off
      </IfModule>
    </VirtualHost>
    ```

**Edit the `.htaccess` file.**

Use the syntax from the INI file examples inside an `.htaccess` file. For example:

````apacheconf
php_value newrelic.appname "My Blog App"
```

This allows you to control settings on a per-directory basis from within the directories.

In this example, your web server has its document root at `/data/webroot`. You also have two sub-directories for specialized applications:

* Your <DNT>**`/data/webroot/blog`**</DNT> contains a blog application.
* Your `/data/webroot/shop` contains a shopping cart application.

To have all three portions of your site reported as distinct applications in the New Relic UI:

1. Set the name of your main application in your INI file.
2. Override that name using an `.htaccess` file in each of the specialized directories.

Any part of your web server (for example, `/data/webroot/something`) that does not have a specific `.htaccess` file will use the global application name defined in the INI file.

<Callout variant="important">
  The `.htaccess` file must be in the top-level directory for that application. Objects in that directory, or its subdirectories, will use the value specified in the `.htaccess` file.
</Callout>

For more information about using and securing <DNT>**`.htaccess`**</DNT> files, see the [Apache HTTP server tutorial](http://httpd.apache.org/docs/2.2/howto/htaccess.html "Link opens in a new window").

````

## PHP-FPM per-directory settings [#php-fpm_per-dir]

The FastCGI Process Manager (**PHP-FPM**) is dedicated to PHP. It spawns a number of worker processes that wait for requests. It increases performance by not re-initializing the PHP engine on each invocation, allowing each process to deal with a number of requests before it recycles.

For more information on PHP-FPM, see [PHP-FPM's about page](http://php-fpm.org/about/ "Link opens in a new window") and [FastCGI Process Manager](http://www.php.net/manual/en/install.fpm.php "Link opens in a new window") on [php.net](http://www.php.net/ "Link opens in a new window").

When using PHP-FPM, there are two mechanisms for setting PHP variables outside the INI file and one special technique for **NGINX**:

**Edit the PHP-FPM pool per-directory settings**

> #### ⚠️ IMPORTANT
>
> Changing variables on a per-directory basis can be more difficult if you use **PHP-FPM**. You must use multiple PHP-FPM pools, one for each virtual host or unique application.

A **pool** is a dedicated set of worker children that will only serve requests for that pool. Because it requires dedicated worker children, PHP-FPM scales poorly if you have a large number of virtual hosts or applications for which you want to set individual options.

To configure PHP-FPM on a per-directory basis:

1.  Set the main application name in the INI file.
2.  Set up two pools for the two additional applications.
3.  Override the application name setting in those pools.

    Each pool has to have a unique connection mechanism (so you can identify which pool to use in your web server configuration file). Here is an example of `php-fpm.conf`:

    ```ini
    [app1]
    listen=/tmp/pool-app1.sock
    php_value[newrelic.appname] = "My App 1"

    [app2]
    listen=/tmp/pool-app2.sock
    php_value[newrelic.appname] = "My App 2"

    [app3]
    listen=/tmp/pool-app3.sock
    php_flag[newrelic.enabled] = off
    ```

    The general format of the per-pool variable settings is `php_value[name] = VALUE` for string or numeric variables, or `php_flag[name] = VALUE` for boolean values. Always surround string values with quote marks `"`. Boolean values must be either `on` or `off`.

    Once the configuration file is set up, the web server must be instructed to use the different pools for different parts of the website. For more information, refer to the documentation for your web server.

**Create a `.user.ini` file.**

You can use the syntax from the INI file example for CGI/FastCGI in a `.user.ini` file. This is similar to a `.htaccess` file for Apache but is unique to PHP-FPM. The directory that PHP is executed in is scanned for a `.user.ini` file. More information about this feature is available in the [PHP `user.ini` files documentation](http://php.net/manual/en/configuration.file.per-user.php).

Change the name of the app using the following steps In the root directory of the web page.

1.  Create the `.user.ini` file

2.  Add the setting you wish to change  
    `newrelic.appname = "New Appname"`

3.  Save the file.

    By default, the **`.user.ini` file** is read every five minutes so no restart is necessary

    This is useful in the following scenarios:

4.  The server config doesn't work. In NGINX/PHP-FPM setup, there can be a lack of communication between FastCGI and PHP and the information from  
    `fastcgi_param PHP_VALUE newrelic.appname="Appname"`  
    never reaches PHP.

5.  The `.htaccess` doesn't work, such as where PHP is implemented with suPHP

**Edit the NGINX config file.**

> #### ⚠️ IMPORTANT
>
> This section applies only to PHP 5.3.3 or higher.

Here is a small fragment of an NGINX config file showing the general procedure to pass values to your FastCGI manager based on an NGINX location.

````nginx
location /blog {
  fastcgi_param PHP_VALUE "newrelic.appname=My Blog";
  ...
}

location /shop {
  fastcgi_param PHP_VALUE "newrelic.appname=Shopping Cart";
  ...
}

location /admin{
  fastcgi_param PHP_VALUE "newrelic.enabled=false";
  ...
}
```

````

## Another option: API calls [#api-calls]

Although we recommend changing the application name with global or per-directory INI settings, in some cases that may not be possible. For example, provider limitations may prevent you from modifying configuration files.

Another option is to use the [`newrelic_set_appname()`](https://docs.newrelic.com/docs/agents/php-agent/php-agent-api/newrelic_set_appname) API call. For other settings that you can modify with the API, see [PHP agent API](https://docs.newrelic.com/docs/php/the-php-api).

Before getting started, we recommend you read the [API call guidelines](https://docs.newrelic.com/docs/apm/agents/php-agent/php-agent-api/newrelic_set_appname/#call-and-location-behavior) for [`newrelic_set_appname()`](https://docs.newrelic.com/docs/agents/php-agent/php-agent-api/newrelic_set_appname) to ensure the most complete capture of transaction traces assigned to your application name.

If you don't have access to the code for your application, or if you need to isolate your applications to their own virtual hosts for other reasons, then use the following per-directory settings to override any [configuration file settings](https://docs.newrelic.com/docs/agents/php-agent/configuration/php-agent-configuration).

## Roll-up application names [#perdir-rollup]

If you want to have an overall view of how the server is performing across all virtual hosts or all applications, it is convenient to be able to report to more than one application at a time. For example, report to a virtual host specific application as well as a roll-up application.

To do this, set more than one application name for the [`newrelic.appname`](https://docs.newrelic.com/docs/php/php-agent-phpini-settings#inivar-appname) parameter by separating each application name with a semicolon. The primary application name is first, and the secondary application names next. You can define up to two extra application names.

For example:

```ini
newrelic.appname="Virtual Host 1;All Virtual Hosts"
```

This will report to two New Relic applications: "Virtual Host 1" and "All Virtual Hosts".