PHP RFC: Default User-Agent for cURL


PHP has a user_agent php.ini entry for decades, which can be set as a default value. But it is considered for stream based operations like file_get_contents. This RFC proposes a new curl.user_agent php.ini entry which would allow setting a default user_agent for all cURL request. This would benefit in better consistency for setting a default user_agent. This feature will mainly be used in a SAPI context in my use-case, which i will illustrate later.


Add a new php.ini entry for cURL named curl.user_agent, which will set the default User-Agent HTTP Header for all cURL related requests. Of course anyone can override the default value using curl_setopt.

An alternative approach would be to reuse the existing (global) user_agent ini setting also for cURL, but this would touch backwards compatibility, which isn't favorable.

Backward Incompatible Changes


Proposed PHP Version(s)


RFC Impact


This feature is especially useful for SAPI usage, as it allows a default header for all HTTP requests (independently if stream based or cURL based) that will allow the remote side to detect the application. At the moment you need to have a workflow or a wrapper that will ensure that the User-Agent is set for all streams and cURL requests. In our use-case the user is also allowed to create PHP scripts by himself. In this situation the user will most probably not set the User-Agent at all, but rely on the defaults.

To Existing Extensions

No impact. By default the new entry is empty and will not do anything.

To Opcache

No impact.

New Constants


php.ini Defaults

curl.user_agent is unset by default for development and production.

Open Issues

Discussion if the ini visibility should be PHP_INI_ALL or PHP_INI_SYSTEM https://github.com/php/php-src/pull/6834/files#r628774432

Unaffected PHP Functionality

This feature does not affect PHP very much and there does not collide with any currently proposed RFCs.

Future Scope

This RFC does not have any future scope.

Proposed Voting Choices

At the moment the php.ini option is proposed inside the curl section. If the discussion should not end unanimously we should consider adding a voting option if the curl section or the global section should be targeted for the user_agent entry.

Patches and Tests

Tests are included in the following PR.



Rejected Features

None yet

rfc/curl_user_agent.txt · Last modified: 2021/07/08 09:55 by paresy