includes/config/ServiceOptions.php

   1 <?php
   2
   3 namespace MediaWiki\Config;
   4
   5 use Config;
   6 use InvalidArgumentException;
   7 use Wikimedia\Assert\Assert;
   8
   9 /**
  10  * A class for passing options to services. It can be constructed from a Config, and in practice
  11  * most options will be taken from site configuration, but they don't have to be. The options passed
  12  * are copied and will not reflect subsequent updates to site configuration (assuming they're not
  13  * objects).
  14  *
  15  * Services that take this type as a parameter to their constructor should specify a list of the
  16  * keys they expect to receive in an array. The convention is to make it a public static variable
  17  * called $constructorOptions. (When we drop HHVM support -- see T192166 -- it should become a
  18  * const.) In the constructor, they should call assertRequiredOptions() to make sure that they
  19  * weren't passed too few or too many options. This way it's clear what each class depends on, and
  20  * that it's getting passed the correct set of options. (This means there are no optional options.
  21  * This makes sense for services, since they shouldn't be constructed by outside code.)
  22  *
  23  * @since 1.34
  24  */
  25 class ServiceOptions {
  26         private $keys = [];
  27         private $options = [];
  28
  29         /**
  30          * @param string[] $keys Which keys to extract from $sources
  31          * @param Config|array ...$sources Each source is either a Config object or an array. If the
  32          *  same key is present in two sources, the first one takes precedence. Keys that are not in
  33          *  $keys are ignored.
  34          * @throws InvalidArgumentException if one of $keys is not found in any of $sources
  35          */
  36         public function __construct( array $keys, ...$sources ) {
  37                 $this->keys = $keys;
  38                 foreach ( $keys as $key ) {
  39                         foreach ( $sources as $source ) {
  40                                 if ( $source instanceof Config ) {
  41                                         if ( $source->has( $key ) ) {
  42                                                 $this->options[$key] = $source->get( $key );
  43                                                 continue 2;
  44                                         }
  45                                 } else {
  46                                         if ( array_key_exists( $key, $source ) ) {
  47                                                 $this->options[$key] = $source[$key];
  48                                                 continue 2;
  49                                         }
  50                                 }
  51                         }
  52                         throw new InvalidArgumentException( "Key \"$key\" not found in input sources" );
  53                 }
  54         }
  55
  56         /**
  57          * Assert that the list of options provided in this instance exactly match $expectedKeys,
  58          * without regard for order.
  59          *
  60          * @param string[] $expectedKeys
  61          */
  62         public function assertRequiredOptions( array $expectedKeys ) {
  63                 if ( $this->keys !== $expectedKeys ) {
  64                         $extraKeys = array_diff( $this->keys, $expectedKeys );
  65                         $missingKeys = array_diff( $expectedKeys, $this->keys );
  66                         Assert::precondition( !$extraKeys && !$missingKeys,
  67                                 (
  68                                 $extraKeys
  69                                         ? 'Unsupported options passed: ' . implode( ', ', $extraKeys ) . '!'
  70                                         : ''
  71                                 ) . ( $extraKeys && $missingKeys ? ' ' : '' ) . (
  72                                 $missingKeys
  73                                         ? 'Required options missing: ' . implode( ', ', $missingKeys ) . '!'
  74                                         : ''
  75                                 )
  76                         );
  77                 }
  78         }
  79
  80         /**
  81          * @param string $key
  82          * @return mixed
  83          */
  84         public function get( $key ) {
  85                 if ( !array_key_exists( $key, $this->options ) ) {
  86                         throw new InvalidArgumentException( "Unrecognized option \"$key\"" );
  87                 }
  88                 return $this->options[$key];
  89         }
  90 }