---
title: newrelic_add_custom_parameter (PHP agent API)
source: https://docs.newrelic.com/docs/apm/agents/php-agent/php-agent-api/newrelic_add_custom_parameter
---

## Syntax

```php
newrelic_add_custom_parameter(string $key, scalar $value)
```

Attaches a custom attribute (key/value pair) to the current transaction and the current span (if enabled).

## Requirements

Agent version [4.4.5.35](https://docs.newrelic.com/docs/release-notes/agent-release-notes/php-release-notes/php-agent-44535) or higher.

## Description

Add a [custom attribute](https://docs.newrelic.com/docs/agents/manage-apm-agents/agent-data/collect-custom-attributes) (a key and a value data pair) to the current web transaction. (The call name is `newrelic_add_custom_parameter` because "custom attributes" were previously called "custom parameters.") For example, you can add a customer's full name from your customer database. This attribute appears in any transaction trace that results from this transaction. You can also query the [Transaction](https://docs.newrelic.com/docs/insights/explore-data/attributes/apm-default-attributes-insights) event for your custom attributes.

> #### ⚠️ IMPORTANT
>
> Security recommendation—Review your Transaction attributes configuration. Any attribute include or exclude settings specific to Transaction events, should be applied to your Span attributes configuration or your Global Attributes configuration.

> #### ⚠️ IMPORTANT
>
> If you want to use your custom attributes, avoid using any of the [reserved terms used by NRQL](https://docs.newrelic.com/docs/insights/event-data-sources/custom-events/data-requirements-limits-custom-event-data/#reserved-words).

## Parameters

| Parameter         | Description                                                                                                                                                                                                                                                                                                        |
| ----------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `$key` _string_   | Required. The name of the custom attribute. Only the first 255 characters are retained.                                                                                                                                                                                                                            |
| `$value` _scalar_ | Required. The value to associate with this custom attribute. If the value given is a **float** with a value of NaN, Infinity, denorm or negative zero, the behavior of this function is undefined. For other floating point values, the agent may discard 1 or more bits of precision (ULPs) from the given value. |

## Return values

Returns true if the parameter was added successfully.

## Examples

### Report a variable as the value [#basic-example]

```php
if (extension_loaded('newrelic')) { // Ensure PHP agent is available
    // Record custom data about this web transaction
    newrelic_add_custom_parameter('user_email', $user_email);
}
```

### Multiple calls [#same-key]

If you call `newrelic_add_custom_parameter` multiple times with the same value for the `$key` parameter in the same web transaction, the `$value` from the last call takes precedence. The value from the last call is recorded as the [custom attribute](https://docs.newrelic.com/docs/agents/manage-apm-agents/agent-data/collect-custom-attributes/) in the web transaction.

For example, if the code looks like this:

```php
if (extension_loaded('newrelic')) { // Ensure PHP agent is available
    // Record custom data about this web transaction
    newrelic_add_custom_parameter('user_email', 'billy@newrelic.com');
    newrelic_add_custom_parameter('user_email', 'samantha@newrelic.com');
}
```

The value `samantha@newrelic.com` gets recorded as the `user_email` custom attribute in the web transaction, and  `billy@newrelic.com` from the earlier call is overwritten.