Bitrix\\Main\\Web\\HttpClient is a built-in client for external HTTP requests. It works in two modes: legacy (convenient get/post/download) and PSR-18 (full control, PSR-7/18 compatibility, asynchrony).
Default values are in /local/.settings.php, http_client_options section:
'http_client_options' => [\n 'value' => [\n 'socketTimeout' => 10,\n 'streamTimeout' => 30,\n 'useCurl' => true,\n 'compress' => true,\n 'redirect' => true,\n 'redirectMax' => 5,\n 'bodyLengthMax' => 10 * 1024 * 1024,\n 'disableSslVerification' => false,\n // Default privateIp is TRUE (private IPs allowed). Set false for SSRF protection:\n 'privateIp' => false,\n ],\n 'readonly' => false,\n],\nCheck: \\Bitrix\\Main\\Config\\Configuration::getValue('http_client_options').
The same keys are accepted by new HttpClient([...]) constructor — constructor overrides global ones.
socketTimeout — connection timeout (sec), default 30.streamTimeout — data reading timeout (sec).compress — accept gzip.redirect, redirectMax — follow redirects (legacy only).useCurl — use cURL instead of sockets (faster for asynchrony and https).disableSslVerification — disable SSL verification (use only for debugging).privateIp — default true = private IPs allowed. Set to false to block private/link-local addresses (SSRF protection for user-provided URLs).bodyLengthMax — response body size limit.waitResponse — false if only headers need to be parsed and connection closed.proxyHost, proxyPort, proxyUser, proxyPassword — proxy settings.debugLevel — HttpDebug::NONE|REQUEST_HEADERS|RESPONSE_HEADERS|ALL.headers, cookies — default dictionaries (legacy only).use Bitrix\\Main\\Web\\HttpClient;\n\n$http = new HttpClient([\n 'compress' => true,\n 'headers' => ['User-Agent' => 'VendorBot/1.0'],\n 'socketTimeout' => 5,\n 'streamTimeout' => 15,\n]);\n\n$body = $http->get('https://api.example.com/items');\n\nif ($body === false)\n{\n throw new \\RuntimeException('HTTP error: ' . $http->getError()[0] ?? 'unknown');\n}\n\n$status = $http->getStatus(); // int\n$headers = $http->getHeaders(); // HttpHeaders\n$data = \\Bitrix\\Main\\Web\\Json::decode($body);\n$http->post('https://api.example.com/form', ['login' => 'admin', 'pass' => '***']);\n$http->setHeader('Content-Type', 'application/json');\n$http->setHeader('Authorization', 'Bearer ' . $token);\n$response = $http->post('https://api.example.com/users', \\Bitrix\\Main\\Web\\Json::encode(['name' => 'Ivan']));\n$http->download(\n 'https://files.example.com/report.csv',\n $_SERVER['DOCUMENT_ROOT'] . '/upload/tmp/report.csv',\n);\n$http->query('GET', $loginUrl);\n$cookies = $http->getCookies()->toArray();\n$http->setCookies($cookies);\n$http->post($apiUrl, $payload);\nTo avoid downloading megabytes for \"reconnaissance\":
\n$http->shouldFetchBody(\n fn (\\Bitrix\\Main\\Web\\Http\\Response $r) =>\n str_starts_with($r->getHeadersCollection()->getContentType() ?? '', 'application/json')\n);\nBuild a Request and call sendRequest:
use Bitrix\\Main\\Web\\HttpClient;\nuse Bitrix\\Main\\Web\\Uri;\nuse Bitrix\\Main\\Web\\Http\\{Request, Method, Stream, ClientException, NetworkException, RequestException};\n\n$http = new HttpClient(['compress' => true, 'useCurl' => true]);\n\n$body = new Stream('php://temp', 'r+');\n$body->write(\\Bitrix\\Main\\Web\\Json::encode(['id' => 42]));\n$body->rewind();\n\n$request = (new Request(\n Method::POST,\n new Uri('https://api.example.com/items'),\n ['Content-Type' => 'application/json', 'Authorization' => 'Bearer ' . $token],\n $body,\n));\n\ntry\n{\n $response = $http->sendRequest($request);\n\n $status = $response->getStatusCode();\n $payload = \\Bitrix\\Main\\Web\\Json::decode((string)$response->getBody());\n}\ncatch (NetworkException $e) { /* connection failed */ }\ncatch (RequestException $e) { /* incorrect request */ }\ncatch (ClientException $e) { /* general client error */ }\nPSR-7 objects are immutable — withHeader, withUri, withMethod return a copy.
use Bitrix\\Main\\Web\\Http\\MultipartStream;\n\n$fh = fopen('/tmp/report.pdf', 'r');\n$body = new MultipartStream([\n 'title' => 'Monthly report',\n 'file' => ['resource' => $fh, 'filename' => 'report.pdf'],\n]);\n\n$request = new Request(\n Method::POST,\n new Uri('https://api.example.com/upload'),\n ['Content-Type' => 'multipart/form-data; boundary=' . $body->getBoundary()],\n $body,\n);\n\n$response = $http->sendRequest($request);\nfclose($fh);\nIn PSR-18, redirects are not followed automatically:
\ndo {\n $response = $http->sendRequest($request);\n if ($response->hasHeader('Location'))\n {\n $request = $request->withUri(new Uri($response->getHeader('Location')[0]));\n }\n} while ($response->hasHeader('Location'));\n$promises = [];\nforeach ($urls as $url)\n{\n $promises[$url] = $http->sendAsyncRequest(new Request(Method::GET, new Uri($url)));\n}\n\nforeach ($promises as $url => $promise)\n{\n try {\n $response = $promise->wait();\n // ...\n } catch (\\Throwable $e) { /* ... */ }\n}\nWait for all:
\nuse Bitrix\\Main\\Web\\Http\\Promise;\n\nPromise::all($promises)->then(\n fn (array $responses) => /* ... */,\n fn (array $errors) => /* ... */\n)->wait();\nHttpClient uses the PSR-3 logger main.HttpClient. Configure in .settings.php:
'loggers' => [\n 'value' => [\n 'main.HttpClient' => [\n 'constructor' => static function (\n \\Bitrix\\Main\\Web\\Http\\DebugInterface $debug,\n \\Psr\\Http\\Message\\RequestInterface $request,\n ) {\n $debug->setDebugLevel(\\Bitrix\\Main\\Web\\HttpDebug::ALL);\n return new \\Bitrix\\Main\\Diag\\FileLogger(\n '/var/log/bitrix/http-' . spl_object_hash($request) . '.log',\n );\n },\n 'level' => \\Psr\\Log\\LogLevel::DEBUG,\n ],\n ],\n],\nHttpClient property $privateIp defaults to true (private IPs are allowed).
'privateIp' => false — blocks 127.0.0.1, 192.168.*, 10.*, 169.254.* (AWS/GCP metadata), etc.true) when the client must call trusted internal services.Canonical entry: Bitrix\\Main\\Service\\GeoIp\\Manager — do not call built-in handler classes directly.
| Need | \nAPI | \n
|---|---|
| One attribute; empty string on miss OK | \ngetCountryCode(), getCityName(), getTimezoneName(), … | \n
Lat/lon pair; null on miss | \ngetGeoPosition() | \n
Several fields + isSuccess() / handler metadata | \ngetDataResult($ip, $lang, $required) | \n
Client IP with X-Forwarded-For awareness | \ngetRealIp() | \n
use Bitrix\\Main\\Service\\GeoIp\\Manager;\n\n$code = Manager::getCountryCode(); // current request IP\n$result = Manager::getDataResult($storedIp, 'en', ['cityName', 'latitude']);\nif ($result && $result->isSuccess())\n{\n $data = $result->getGeoData();\n}\nRules:
\n$ip for stored/proxied addresses; empty $ip only as shorthand for current request (getRealIp()).$required in getDataResult when you depend on specific fields so unsuitable handlers are skipped.getDataResult → null; convenience getters → ''; getGeoPosition → null.Manager is IPv4-oriented — do not assume identical IPv6 persistence.Manager::cleanCache() (or handler cascade), not ad hoc deletes under geoip_manager.onMainGeoIpHandlersBuildList + subclass of GeoIp\\Base. Post-process only via onGeoIpGetResult.Logger id for this subsystem: main.GeoIpManager (see bitrix-logger).
useCurl is enabled (requires php-curl).socketTimeout, streamTimeout) are set and reasonable.2xx before decoding.privateIp => false (default is true = private IPs allowed).download() or streams, not read entirely into memory.GeoIp\\Manager with explicit IP when not the current request.See skill bitrix-security for SSRF protection details.