Page MenuHomeClusterLabs Projects
Diviner Tech Docs PhabricatorEnv

final class PhabricatorEnv
Phorge Technical Documentation ()

Manages the execution environment configuration, exposing APIs to read configuration settings and other similar values that are derived directly from configuration settings.

Reading Configuration

The primary role of this class is to provide an API for reading Phabricator configuration, getEnvConfig():

$value = PhabricatorEnv::getEnvConfig('some.key', $default);

The class also handles some URI construction based on configuration, via the methods getURI(), getProductionURI(), getCDNURI(), and getDoclink().

For configuration which allows you to choose a class to be responsible for some functionality (e.g., which mail adapter to use to deliver email), newObjectFromConfig() provides a simple interface that validates the configured value.

Unit Test Support

In unit tests, you can use beginScopedEnv() to create a temporary, mutable environment. The method returns a scope guard object which restores the environment when it is destroyed. For example:

public function testExample() {
  $env = PhabricatorEnv::beginScopedEnv();
  $env->overrideEnv('some.key', 'new-value-for-this-test');

  // Some test which depends on the value of 'some.key'.

}

Your changes will persist until the $env object leaves scope or is destroyed.

You should not use this in normal code.

Tasks

Reading Configuration

  • public static function getEnvConfig($key) — Get the current configuration setting for a given key.
  • public static function getEnvConfigIfExists($key, $default) — Get the current configuration setting for a given key. If the key does not exist, return a default value instead of throwing. This is primarily useful for migrations involving keys which are slated for removal.
  • public static function getURI($path) — Get the fully-qualified URI for a path.
  • public static function getProductionURI($path) — Get the fully-qualified production URI for a path.
  • public static function getCDNURI($path) — Get the fully-qualified production URI for a static resource path.
  • public static function getDoclink($resource, $type) — Get the fully-qualified production URI for a documentation resource.
  • public static function newObjectFromConfig($key, $args) — Build a concrete object from a configuration key.

URI Validation

  • public static function isValidURIForLink($uri) — Detect if a URI satisfies either @{method:isValidLocalURIForLink} or @{method:isValidRemoteURIForLink}, i.e. is a page on this server or the URI of some other resource which has a valid protocol. This rejects garbage URIs and URIs with protocols which do not appear in the `uri.allowed-protocols` configuration, notably 'javascript:' URIs.
  • public static function isValidLocalURIForLink($uri) — Detect if a URI identifies some page on this server.
  • public static function isValidRemoteURIForLink($uri) — Detect if a URI identifies some valid linkable remote resource.
  • public static function requireValidRemoteURIForLink($raw_uri) — Detect if a URI identifies a valid linkable remote resource, throwing a detailed message if it does not.
  • public static function isValidRemoteURIForFetch($uri, $protocols) — Detect if a URI identifies a valid fetchable remote resource.
  • public static function requireValidRemoteURIForFetch($raw_uri, $protocols) — Detect if a URI identifies a valid fetchable remote resource, throwing a detailed message if it does not.

Unit Test Support

Internals

Other Methods

Methods

public static function initializeWebEnvironment()

This method is not documented.
Return
wild

public static function initializeScriptEnvironment($config_optional)

This method is not documented.
Parameters
$config_optional
Return
wild

private static function initializeCommonEnvironment($config_optional)

This method is not documented.
Parameters
$config_optional
Return
wild

public static function beginScopedLocale($locale_code)

This method is not documented.
Parameters
$locale_code
Return
wild

public static function getLocaleCode()

This method is not documented.
Return
wild

public static function setLocaleCode($locale_code)

This method is not documented.
Parameters
$locale_code
Return
wild

private static function buildConfigurationSourceStack($config_optional)

This method is not documented.
Parameters
$config_optional
Return
wild

public static function repairConfig($key, $value)

This method is not documented.
Parameters
$key
$value
Return
wild

public static function overrideConfig($key, $value)

This method is not documented.
Parameters
$key
$value
Return
wild

public static function getUnrepairedEnvConfig($key, $default)

This method is not documented.
Parameters
$key
$default
Return
wild

public static function getSelectedEnvironmentName()

This method is not documented.
Return
wild

public static function getEnvConfig($key)

Get the current configuration setting for a given key.

If the key is not found, then throw an Exception.

Parameters
$key
Return
wild

public static function getEnvConfigIfExists($key, $default)

Get the current configuration setting for a given key. If the key does not exist, return a default value instead of throwing. This is primarily useful for migrations involving keys which are slated for removal.

Parameters
$key
$default
Return
wild

public static function getURI($path)

Get the fully-qualified URI for a path.

Parameters
$path
Return
wild

public static function getProductionURI($path)

Get the fully-qualified production URI for a path.

Parameters
$path
Return
wild

public static function isSelfURI($raw_uri)

This method is not documented.
Parameters
$raw_uri
Return
wild

private static function getSelfURIMap()

This method is not documented.
Return
wild

public static function getCDNURI($path)

Get the fully-qualified production URI for a static resource path.

Parameters
$path
Return
wild

public static function getDoclink($resource, $type)

Get the fully-qualified production URI for a documentation resource.

Parameters
$resource
$type
Return
wild

public static function newObjectFromConfig($key, $args)

Build a concrete object from a configuration key.

Parameters
$key
$args
Return
wild

public static function getAnyBaseURI()

This method is not documented.
Return
wild

public static function getRequestBaseURI()

This method is not documented.
Return
wild

public static function setRequestBaseURI($uri)

This method is not documented.
Parameters
$uri
Return
wild

public static function isReadOnly()

This method is not documented.
Return
wild

public static function setReadOnly($read_only, $reason)

This method is not documented.
Parameters
$read_only
$reason
Return
wild

public static function getReadOnlyMessage()

This method is not documented.
Return
wild

public static function getReadOnlyURI()

This method is not documented.
Return
wild

public static function getReadOnlyReason()

This method is not documented.
Return
wild

public static function beginScopedEnv()

This method is not documented.
Return
wild

private static function pushTestEnvironment()

This method is not documented.
Return
wild

public static function popTestEnvironment($key)

This method is not documented.
Parameters
$key
Return
wild

public static function isValidURIForLink($uri)

Detect if a URI satisfies either isValidLocalURIForLink() or isValidRemoteURIForLink(), i.e. is a page on this server or the URI of some other resource which has a valid protocol. This rejects garbage URIs and URIs with protocols which do not appear in the uri.allowed-protocols configuration, notably 'javascript:' URIs.

NOTE: This method is generally intended to reject URIs which it may be unsafe to put in an "href" link attribute.
Parameters
string$uriURI to test.
Return
boolTrue if the URI identifies a web resource.

public static function isValidLocalURIForLink($uri)

Detect if a URI identifies some page on this server.

NOTE: This method is generally intended to reject URIs which it may be unsafe to issue a "Location:" redirect to.
Parameters
string$uriURI to test.
Return
boolTrue if the URI identifies a local page.

public static function isValidRemoteURIForLink($uri)

Detect if a URI identifies some valid linkable remote resource.

Parameters
string$uriURI to test.
Return
boolTrue if a URI identifies a remote resource with an allowed protocol.

public static function requireValidRemoteURIForLink($raw_uri)

Detect if a URI identifies a valid linkable remote resource, throwing a detailed message if it does not.

A valid linkable remote resource can be safely linked or redirected to. This is primarily a protocol whitelist check.

Parameters
string$raw_uriURI to test.
Return
void

public static function isValidRemoteURIForFetch($uri, $protocols)

Detect if a URI identifies a valid fetchable remote resource.

Parameters
string$uriURI to test.
list<string>$protocolsAllowed protocols.
Return
boolTrue if the URI is a valid fetchable remote resource.

public static function requireValidRemoteURIForFetch($raw_uri, $protocols)

Detect if a URI identifies a valid fetchable remote resource, throwing a detailed message if it does not.

A valid fetchable remote resource can be safely fetched using a request originating on this server. This is a primarily an address check against the outbound address blacklist.

Parameters
string$raw_uriURI to test.
list<string>$protocolsAllowed protocols.
Return
pair<string, string>Pre-resolved URI and domain.

public static function isBlacklistedOutboundAddress($address)

Determine if an IP address is in the outbound address blacklist.

Parameters
string$addressIP address.
Return
boolTrue if the address is blacklisted.

public static function isClusterRemoteAddress()

This method is not documented.
Return
wild

public static function isClusterAddress($address)

This method is not documented.
Parameters
$address
Return
wild

public static function getRemoteAddress()

This method is not documented.
Return
wild

public static function envConfigExists($key)

This method is not documented.
Parameters
$key
Return
wild

public static function getAllConfigKeys()

This method is not documented.
Return
wild

public static function getConfigSourceStack()

This method is not documented.
Return
wild

public static function overrideTestEnvConfig($stack_key, $key, $value)

This method is not documented.
Parameters
$stack_key
$key
$value
Return
wild

private static function dropConfigCache()

This method is not documented.
Return
wild

private static function resetUmask()

This method is not documented.
Return
wild

public static function getEmptyCWD()

Get the path to an empty directory which is readable by all of the system user accounts that Phabricator acts as.

In some cases, a binary needs some valid HOME or CWD to continue, but not all user accounts have valid home directories and even if they do they may not be readable after a sudo operation.

Return
stringPath to an empty directory suitable for use as a CWD.
Defined
src/infrastructure/env/PhabricatorEnv.php:51