src/applications/config/option/PhabricatorCoreConfigOptions.php

   1 <?php
   2
   3 final class PhabricatorCoreConfigOptions
   4   extends PhabricatorApplicationConfigOptions {
   5
   6   public function getName() {
   7     return pht('Core');
   8   }
   9
  10   public function getDescription() {
  11     return pht('Configure core options, including URIs.');
  12   }
  13
  14   public function getIcon() {
  15     return 'fa-bullseye';
  16   }
  17
  18   public function getGroup() {
  19     return 'core';
  20   }
  21
  22   public function getOptions() {
  23     if (phutil_is_windows()) {
  24       $paths = array();
  25     } else {
  26       $paths = array(
  27         '/bin',
  28         '/usr/bin',
  29         '/usr/local/bin',
  30       );
  31     }
  32
  33     $path = getenv('PATH');
  34
  35     $proto_doc_href = PhabricatorEnv::getDoclink(
  36       'User Guide: Prototype Applications');
  37     $proto_doc_name = pht('User Guide: Prototype Applications');
  38     $applications_app_href = '/applications/';
  39
  40     $silent_description = $this->deformat(pht(<<<EOREMARKUP
  41 This option allows you to stop Phabricator from sending data to most external
  42 services: it will disable email, SMS, repository mirroring, remote builds,
  43 Doorkeeper writes, and webhooks.
  44
  45 This option is intended to allow a Phabricator instance to be exported, copied,
  46 imported, and run in a test environment without impacting users. For example,
  47 if you are migrating to new hardware, you could perform a test migration first
  48 with this flag set, make sure things work, and then do a production cutover
  49 later with higher confidence and less disruption.
  50
  51 Without making use of this flag to silence the temporary test environment,
  52 users would receive duplicate email during the time the test instance and old
  53 production instance were both in operation.
  54 EOREMARKUP
  55       ));
  56
  57     $timezone_description = $this->deformat(pht(<<<EOREMARKUP
  58 PHP date functions will emit a warning if they are called when no default
  59 server timezone is configured.
  60
  61 Usually, you configure a default timezone in `php.ini` by setting the
  62 configuration value `date.timezone`.
  63
  64 If you prefer, you can configure a default timezone here instead. To configure
  65 a default timezone, select a timezone from the
  66 [[ %s | PHP List of Supported Timezones ]].
  67 EOREMARKUP
  68 ,
  69       'https://php.net/manual/timezones.php'));
  70
  71
  72     return array(
  73       $this->newOption('phabricator.base-uri', 'string', null)
  74         ->setLocked(true)
  75         ->setSummary(pht('URI where Phabricator is installed.'))
  76         ->setDescription(
  77           pht(
  78             'Set the URI where Phabricator is installed. Setting this '.
  79             'improves security by preventing cookies from being set on other '.
  80             'domains, and allows daemons to send emails with links that have '.
  81             'the correct domain.'))
  82         ->addExample('http://phabricator.example.com/', pht('Valid Setting')),
  83       $this->newOption('phabricator.production-uri', 'string', null)
  84         ->setSummary(
  85           pht('Primary install URI, for multi-environment installs.'))
  86         ->setDescription(
  87           pht(
  88             'If you have multiple Phabricator environments (like a '.
  89             'development/staging environment for working on testing '.
  90             'Phabricator, and a production environment for deploying it), '.
  91             'set the production environment URI here so that emails and other '.
  92             'durable URIs will always generate with links pointing at the '.
  93             'production environment. If unset, defaults to `%s`. Most '.
  94             'installs do not need to set this option.',
  95             'phabricator.base-uri'))
  96         ->addExample('http://phabricator.example.com/', pht('Valid Setting')),
  97       $this->newOption('phabricator.allowed-uris', 'list<string>', array())
  98         ->setLocked(true)
  99         ->setSummary(pht('Alternative URIs that can access Phabricator.'))
 100         ->setDescription(
 101           pht(
 102             "These alternative URIs will be able to access 'normal' pages ".
 103             "on your Phabricator install. Other features such as OAuth ".
 104             "won't work. The major use case for this is moving installs ".
 105             "across domains."))
 106         ->addExample(
 107           "http://phabricator2.example.com/\n".
 108           "http://phabricator3.example.com/",
 109           pht('Valid Setting')),
 110       $this->newOption('phabricator.timezone', 'string', null)
 111         ->setSummary(
 112           pht('The timezone Phabricator should use.'))
 113         ->setDescription($timezone_description)
 114         ->addExample('America/New_York', pht('US East (EDT)'))
 115         ->addExample('America/Chicago', pht('US Central (CDT)'))
 116         ->addExample('America/Boise', pht('US Mountain (MDT)'))
 117         ->addExample('America/Los_Angeles', pht('US West (PDT)')),
 118       $this->newOption('phabricator.cookie-prefix', 'string', null)
 119         ->setLocked(true)
 120         ->setSummary(
 121           pht(
 122             'Set a string Phabricator should use to prefix cookie names.'))
 123         ->setDescription(
 124           pht(
 125             'Cookies set for x.com are also sent for y.x.com. Assuming '.
 126             'Phabricator instances are running on both domains, this will '.
 127             'create a collision preventing you from logging in.'))
 128         ->addExample('dev', pht('Prefix cookie with "%s"', 'dev')),
 129       $this->newOption('phabricator.show-prototypes', 'bool', false)
 130         ->setLocked(true)
 131         ->setBoolOptions(
 132           array(
 133             pht('Enable Prototypes'),
 134             pht('Disable Prototypes'),
 135           ))
 136         ->setSummary(
 137           pht(
 138             'Install applications which are still under development.'))
 139         ->setDescription(
 140           pht(
 141             "IMPORTANT: The upstream does not provide support for prototype ".
 142             "applications.".
 143             "\n\n".
 144             "Phabricator includes prototype applications which are in an ".
 145             "**early stage of development**. By default, prototype ".
 146             "applications are not installed, because they are often not yet ".
 147             "developed enough to be generally usable. You can enable ".
 148             "this option to install them if you're developing Phabricator ".
 149             "or are interested in previewing upcoming features.".
 150             "\n\n".
 151             "To learn more about prototypes, see [[ %s | %s ]].".
 152             "\n\n".
 153             "After enabling prototypes, you can selectively uninstall them ".
 154             "(like normal applications).",
 155             $proto_doc_href,
 156             $proto_doc_name)),
 157       $this->newOption('phabricator.serious-business', 'bool', false)
 158         ->setBoolOptions(
 159           array(
 160             pht('Serious business'),
 161             pht('Shenanigans'), // That should be interesting to translate. :P
 162           ))
 163         ->setSummary(
 164           pht('Allows you to remove levity and jokes from the UI.'))
 165         ->setDescription(
 166           pht(
 167             'By default, Phabricator includes some flavor text in the UI, '.
 168             'like a prompt to "Weigh In" rather than "Add Comment" in '.
 169             'Maniphest. If you\'d prefer more traditional UI strings like '.
 170             '"Add Comment", you can set this flag to disable most of the '.
 171             'extra flavor.')),
 172       $this->newOption(
 173         'remarkup.ignored-object-names',
 174         'string',
 175
 176         // Q1, Q2, etc., are common abbreviations for "Quarter".
 177         // V1, V2, etc., are common abbreviations for "Version".
 178         // P1, P2, etc., are common abbreviations for "Priority".
 179
 180         // M1 is a computer chip manufactured by Apple.
 181         // M2 (commonly spelled "M.2") is an expansion slot on motherboards.
 182         // M4 is a carbine.
 183         // M8 is a phonetic spelling of "mate", used in culturally significant
 184         // copypasta about navy seals.
 185
 186         '/^(Q|V|M|P)\d$/')
 187         ->setSummary(
 188           pht('Text values that match this regex and are also object names '.
 189           'will not be linked.'))
 190         ->setDescription(
 191           pht(
 192             'By default, Phabricator links object names in Remarkup fields '.
 193             'to the corresponding object. This regex can be used to modify '.
 194             'this behavior; object names that match this regex will not be '.
 195             'linked.')),
 196       $this->newOption('environment.append-paths', 'list<string>', $paths)
 197         ->setSummary(
 198           pht(
 199             'These paths get appended to your %s environment variable.',
 200             '$PATH'))
 201         ->setDescription(
 202           pht(
 203             "Phabricator occasionally shells out to other binaries on the ".
 204             "server. An example of this is the `%s` command, used to ".
 205             "syntax-highlight code written in languages other than PHP. By ".
 206             "default, it is assumed that these binaries are in the %s of the ".
 207             "user running Phabricator (normally 'apache', 'httpd', or ".
 208             "'nobody'). Here you can add extra directories to the %s ".
 209             "environment variable, for when these binaries are in ".
 210             "non-standard locations.\n\n".
 211             "Note that you can also put binaries in `%s` (for example, by ".
 212             "symlinking them).\n\n".
 213             "The current value of PATH after configuration is applied is:\n\n".
 214             "  lang=text\n".
 215             "  %s",
 216             'pygmentize',
 217             '$PATH',
 218             '$PATH',
 219             'phabricator/support/bin/',
 220             $path))
 221         ->setLocked(true)
 222         ->addExample('/usr/local/bin', pht('Add One Path'))
 223         ->addExample("/usr/bin\n/usr/local/bin", pht('Add Multiple Paths')),
 224       $this->newOption('config.lock', 'set', array())
 225         ->setLocked(true)
 226         ->setDescription(pht('Additional configuration options to lock.')),
 227       $this->newOption('config.hide', 'set', array())
 228         ->setLocked(true)
 229         ->setDescription(pht('Additional configuration options to hide.')),
 230       $this->newOption('config.ignore-issues', 'set', array())
 231         ->setLocked(true)
 232         ->setDescription(pht('Setup issues to ignore.')),
 233       $this->newOption('phabricator.env', 'string', null)
 234         ->setLocked(true)
 235         ->setDescription(pht('Internal.')),
 236       $this->newOption('test.value', 'wild', null)
 237         ->setLocked(true)
 238         ->setDescription(pht('Unit test value.')),
 239       $this->newOption('phabricator.uninstalled-applications', 'set', array())
 240         ->setLocked(true)
 241         ->setLockedMessage(pht(
 242           'Use the %s to manage installed applications.',
 243           phutil_tag(
 244             'a',
 245             array(
 246               'href' => $applications_app_href,
 247             ),
 248             pht('Applications application'))))
 249         ->setDescription(
 250           pht('Array containing list of uninstalled applications.')),
 251       $this->newOption('phabricator.application-settings', 'wild', array())
 252         ->setLocked(true)
 253         ->setDescription(
 254           pht('Customized settings for Phabricator applications.')),
 255       $this->newOption('phabricator.cache-namespace', 'string', 'phabricator')
 256         ->setLocked(true)
 257         ->setDescription(pht('Cache namespace.')),
 258       $this->newOption('phabricator.silent', 'bool', false)
 259         ->setLocked(true)
 260         ->setBoolOptions(
 261           array(
 262             pht('Run Silently'),
 263             pht('Run Normally'),
 264           ))
 265         ->setSummary(pht('Stop Phabricator from sending any email, etc.'))
 266         ->setDescription($silent_description),
 267       );
 268
 269   }
 270
 271   protected function didValidateOption(
 272     PhabricatorConfigOption $option,
 273     $value) {
 274
 275     $key = $option->getKey();
 276     if ($key == 'phabricator.base-uri' ||
 277         $key == 'phabricator.production-uri') {
 278
 279       $uri = new PhutilURI($value);
 280       $protocol = $uri->getProtocol();
 281       if ($protocol !== 'http' && $protocol !== 'https') {
 282         throw new PhabricatorConfigValidationException(
 283           pht(
 284             'Config option "%s" is invalid. The URI must start with '.
 285             '"%s" or "%s".',
 286             $key,
 287             'http://',
 288             'https://'));
 289       }
 290
 291       $domain = $uri->getDomain();
 292       if (strpos($domain, '.') === false) {
 293         throw new PhabricatorConfigValidationException(
 294           pht(
 295             'Config option "%s" is invalid. The URI must contain a dot '.
 296             '("%s"), like "%s", not just a bare name like "%s". Some web '.
 297             'browsers will not set cookies on domains with no TLD.',
 298             $key,
 299             '.',
 300             'http://example.com/',
 301             'http://example/'));
 302       }
 303
 304       $path = $uri->getPath();
 305       if ($path !== '' && $path !== '/') {
 306         throw new PhabricatorConfigValidationException(
 307           pht(
 308             "Config option '%s' is invalid. The URI must NOT have a path, ".
 309             "e.g. '%s' is OK, but '%s' is not. Phabricator must be installed ".
 310             "on an entire domain; it can not be installed on a path.",
 311             $key,
 312             'http://phabricator.example.com/',
 313             'http://example.com/phabricator/'));
 314       }
 315     }
 316
 317
 318     if ($key === 'phabricator.timezone') {
 319       $old = date_default_timezone_get();
 320       $ok = @date_default_timezone_set($value);
 321       @date_default_timezone_set($old);
 322
 323       if (!$ok) {
 324         throw new PhabricatorConfigValidationException(
 325           pht(
 326             'Config option "%s" is invalid. The timezone identifier must '.
 327             'be a valid timezone identifier recognized by PHP, like "%s".',
 328             $key,
 329             'America/Los_Angeles'));
 330       }
 331     }
 332   }
 333
 334
 335 }