> This page is for SDK, version Legacy.
> For other versions, use one of these documentation indexes:
> - Current (default): https://buildwithfern.com/learn/sdks/current/llms.txt
> - Legacy: https://buildwithfern.com/learn/sdks/legacy/llms.txt

> For clean Markdown content of this page, append .md to this URL. For the complete documentation index, see https://buildwithfern.com/learn/llms.txt.

# PHP configuration

> Configure your PHP SDK generator with Fern. Customize client names, namespaces, package settings, and composer.json for PHP client libraries.

> **You're viewing the legacy SDK docs**
>
> These pages cover SDK generation configured with `generators.yml`. New projects use `sdk-config.yml`, so see [the Current version of this page](/learn/sdks/generators/php/configuration) for up-to-date guidance. To move an existing project, follow the [SDK Config migration guide](/learn/sdks/legacy/generators/migration-guides/sdk-config), which walks through `fern sdk migrate`, and review the [`sdk-config.yml` reference](/learn/sdks/reference/sdk-config).

You can customize the behavior of the PHP SDK generator in `generators.yml`:

**`generators.yml`**

```yaml {7-8} title="generators.yml"
groups:
  php-sdk:
    generators:
      - name: fern-php
        version: 2.30.6
        config:
          clientName: YourClientName
```

## SDK configuration options

**`auto-generate-idempotency-key`** `boolean | object` — default: false

Overrides the API-wide [`api.settings.auto-generate-idempotency-key`](/learn/sdks/legacy/reference/generators-yml#settings) for this SDK. Set `true` to attach an [idempotency-key header](/learn/sdks/legacy/deep-dives/idempotency#auto-generate-idempotency-keys) to eligible requests (`POST` and `PUT` by default) unless the caller provides one, or `false` to opt this SDK out when auto-generation is enabled API-wide. Pass an object to customize `header-name` and `methods`.

---

**`clientName`** `string`

Sets the name of the generated API client class. This determines the primary client type name that users will interact with in the generated PHP SDK.

---

**`composerJson`** `Record<string, any>`

Allows customization of the generated `composer.json` file contents. You can specify additional metadata, dependencies, or configuration that will be merged into the package's composer configuration file.

---

**`enable-wire-tests`** `boolean` — default: false

When enabled, generates [mock server (wire) tests](/learn/sdks/legacy/deep-dives/testing#mock-server-tests) to verify that the SDK sends and receives HTTP requests as expected.

---

**`encode-path-params`** `boolean` — default: false

Percent-encodes path parameter values when the generated SDK substitutes them into the request path. By default, values are inserted unencoded, so a value containing `/` or `..` changes the path the request resolves to: for an endpoint `GET /plants/{plantId}`, a `plantId` of `../plants` requests `/plants`. When enabled, the same value requests `/plants/..%2Fplants`.

---

**`inlinePathParameters`** `boolean`

When enabled, path parameters are included as properties in the request class instead of being passed as separate method parameters. This creates a more unified request structure where all parameters are grouped together in the request object.

---

**`maxRetries`** `number`

The default number of retries for failed requests. When not set, the generated SDK uses its own built-in default. SDK users can still override this per-request via request options.

---

**`namespace`** `string`

Specifies the PHP namespace for all generated code. This determines the namespace hierarchy that users will use when importing and using the SDK classes.

---

**`offsetSemantics`** `'item-index' | 'page-index'`

Controls how the offset parameter is interpreted for [auto-paginated](/learn/sdks/legacy/deep-dives/auto-pagination) endpoints.

* `item-index`: The offset counts individual items (e.g., offset 20 skips the first 20 items).
* `page-index`: The offset counts pages (e.g., offset 3 skips to page 3).

---

**`omitFernHeaders`** `boolean` — default: false

When enabled, the generated SDK omits the `X-Fern-Language`, `X-Fern-SDK-Name`, and `X-Fern-SDK-Version` headers from HTTP requests.

---

**`includePlatformHeaders`** `boolean` — default: false

When enabled, the generated SDK sends a single structured `User-Agent` header of the form `{sdkName}/{version} ({os}; {arch}) {runtime}/{runtimeVersion}` (for example, `my-sdk/0.0.1 (linux; x86_64) PHP/8.2.0`), carrying SDK, operating system, architecture, and runtime information in place of the default `User-Agent` and discrete platform headers. A configured [`user-agent`](#user-agent) template supplies the leading product token. If `omitFernHeaders` is enabled, no `User-Agent` or platform headers are sent and this option has no effect.

---

**`allowUserAgentAppInfo`** `boolean` — default: false

When enabled, the generated client accepts an optional `appInfo` client option of the shape `array{name: string, version?: string, comment?: string}`, which appends a `{name}/{version} ({comment})` [product token](https://www.rfc-editor.org/rfc/rfc9110#name-user-agent) to the `User-Agent` header so an application built on the SDK can identify itself to the API. The application passes a required `name` plus an optional `version` and `comment`; omitted or blank values are dropped from the token. An explicit `User-Agent` header takes precedence, and [`omitFernHeaders`](#omitfernheaders) suppresses the header entirely.

```php
'appInfo' => ['name' => 'partner-app', 'version' => '3.1.0', 'comment' => '+https://partner.example']
// User-Agent: my-sdk/0.0.1 (linux; x86_64) PHP/8.2.0 partner-app/3.1.0 (+https://partner.example)
```

---

**`packageName`** `string`

Sets the name of the PHP package as it will appear in Composer and Packagist. This is the name users will use to install the SDK via Composer (e.g., `composer require your/package-name`).

---

**`packagePath`** `string`

Specifies the directory path where the generated SDK source files should be placed. This determines the file system location of the generated PHP code relative to the output directory.

---

**`propertyAccess`** `'public' | 'private'`

Controls the access level of generated class properties. When set to 'public', properties are public and getter/setter methods are omitted. When set to 'private', properties are private and getter/setter methods are generated for encapsulation.

---

\<ParamField path="user-agent" type="string" default="\{packageName}/\{version}" required= toc=>
Sets a custom `User-Agent` header template for requests sent by the generated SDK. The template is resolved at generation time and supports the `{packageName}`, `{version}`, `{language}`, `{generatorVersion}`, `{organization}`, and `{apiName}` placeholders.

**`generators.yml`**

```yaml title="generators.yml"
config:
  user-agent: "plantstore-php-sdk/{version}"
```

This sends `User-Agent: plantstore-php-sdk/0.1.0`. With [`includePlatformHeaders`](#includeplatformheaders) enabled, the resolved value leads the structured header: `User-Agent: plantstore-php-sdk/0.1.0 (linux; x86_64) PHP/8.2.0`. A value that doesn't end in a version, such as `plantstore/sdk-php`, is used as-is. The [`allowUserAgentAppInfo`](#allowuseragentappinfo) token is appended after either form.
\<ParamField path="respectOptionalRequestBody" type="boolean" default="false" required= toc=>
Lets callers omit the request body argument on endpoints with an optional request body. A call that omits it sends no body and no `Content-Type` header, instead of an empty JSON object (`{}`). Enable this when your API treats a missing body differently from an empty one.

Only applies to request bodies declared as a single named type. Required bodies and inlined request properties are unaffected.\</ParamField>