ServiceContainer.php

Go to the documentation of this file.

<?php
 
namespace Wikimedia\Services;
 
use InvalidArgumentException;
use Psr\Container\ContainerInterface;
use RuntimeException;
use Wikimedia\Assert\Assert;
use Wikimedia\ScopedCallback;
 
class ServiceContainer implements ContainerInterface, DestructibleService {
 
    private $services = [];
 
    private $serviceInstantiators = [];
 
    private $serviceManipulators = [];
 
    private $disabled = [];
 
    private $extraInstantiationParams;
 
    private $destroyed = false;
 
    private $servicesBeingCreated = [];
 
    public function __construct( array $extraInstantiationParams = [] ) {
        $this->extraInstantiationParams = $extraInstantiationParams;
    }
 
    public function destroy() {
        foreach ( $this->getServiceNames() as $name ) {
            $service = $this->peekService( $name );
            if ( $service !== null && $service instanceof DestructibleService ) {
                $service->destroy();
            }
        }
 
        // Break circular references due to the $this reference in closures, by
        // erasing the instantiator array. This allows the ServiceContainer to
        // be deleted when it goes out of scope.
        $this->serviceInstantiators = [];
        // Also remove the services themselves, to avoid confusion.
        $this->services = [];
        $this->destroyed = true;
    }
 
    public function loadWiringFiles( array $wiringFiles ) {
        foreach ( $wiringFiles as $file ) {
            // the wiring file is required to return an array of instantiators.
            $wiring = require $file;
 
            Assert::postcondition(
                is_array( $wiring ),
                "Wiring file $file is expected to return an array!"
            );
 
            $this->applyWiring( $wiring );
        }
    }
 
    public function applyWiring( array $serviceInstantiators ) {
        Assert::parameterElementType( 'callable', $serviceInstantiators, '$serviceInstantiators' );
 
        foreach ( $serviceInstantiators as $name => $instantiator ) {
            $this->defineService( $name, $instantiator );
        }
    }
 
    public function importWiring( ServiceContainer $container, $skip = [] ) {
        $newInstantiators = array_diff_key(
            $container->serviceInstantiators,
            array_flip( $skip )
        );
 
        $this->serviceInstantiators = array_merge(
            $this->serviceInstantiators,
            $newInstantiators
        );
 
        $newManipulators = array_diff(
            array_keys( $container->serviceManipulators ),
            $skip
        );
 
        foreach ( $newManipulators as $name ) {
            if ( isset( $this->serviceManipulators[$name] ) ) {
                $this->serviceManipulators[$name] = array_merge(
                    $this->serviceManipulators[$name],
                    $container->serviceManipulators[$name]
                );
            } else {
                $this->serviceManipulators[$name] = $container->serviceManipulators[$name];
            }
        }
    }
 
    public function hasService( $name ) {
        return isset( $this->serviceInstantiators[$name] );
    }
 
    public function has( $name ) {
        return $this->hasService( $name );
    }
 
    public function peekService( $name ) {
        if ( !$this->hasService( $name ) ) {
            throw new NoSuchServiceException( $name );
        }
 
        return $this->services[$name] ?? null;
    }
 
    public function getServiceNames() {
        return array_keys( $this->serviceInstantiators );
    }
 
    public function defineService( $name, callable $instantiator ) {
        Assert::parameterType( 'string', $name, '$name' );
 
        if ( $this->hasService( $name ) ) {
            throw new ServiceAlreadyDefinedException( $name );
        }
 
        $this->serviceInstantiators[$name] = $instantiator;
    }
 
    public function redefineService( $name, callable $instantiator ) {
        Assert::parameterType( 'string', $name, '$name' );
 
        if ( !$this->hasService( $name ) ) {
            throw new NoSuchServiceException( $name );
        }
 
        if ( isset( $this->services[$name] ) ) {
            throw new CannotReplaceActiveServiceException( $name );
        }
 
        $this->serviceInstantiators[$name] = $instantiator;
        unset( $this->disabled[$name] );
    }
 
    public function addServiceManipulator( $name, callable $manipulator ) {
        Assert::parameterType( 'string', $name, '$name' );
 
        if ( !$this->hasService( $name ) ) {
            throw new NoSuchServiceException( $name );
        }
 
        if ( isset( $this->services[$name] ) ) {
            throw new CannotReplaceActiveServiceException( $name );
        }
 
        $this->serviceManipulators[$name][] = $manipulator;
    }
 
    public function disableService( $name ) {
        $this->resetService( $name );
 
        $this->disabled[$name] = true;
    }
 
    final protected function resetService( $name, $destroy = true ) {
        Assert::parameterType( 'string', $name, '$name' );
 
        $instance = $this->peekService( $name );
 
        if ( $destroy && $instance instanceof DestructibleService ) {
            $instance->destroy();
        }
 
        unset( $this->services[$name] );
        unset( $this->disabled[$name] );
    }
 
    public function getService( $name ) {
        if ( $this->destroyed ) {
            throw new ContainerDisabledException();
        }
 
        if ( isset( $this->disabled[$name] ) ) {
            throw new ServiceDisabledException( $name );
        }
 
        if ( !isset( $this->services[$name] ) ) {
            $this->services[$name] = $this->createService( $name );
        }
 
        return $this->services[$name];
    }
 
    public function get( $name ) {
        return $this->getService( $name );
    }
 
    private function createService( $name ) {
        if ( isset( $this->serviceInstantiators[$name] ) ) {
            if ( isset( $this->servicesBeingCreated[$name] ) ) {
                throw new RuntimeException( "Circular dependency when creating service! " .
                    implode( ' -> ', array_keys( $this->servicesBeingCreated ) ) . " -> $name" );
            }
            $this->servicesBeingCreated[$name] = true;
            $removeFromStack = new ScopedCallback( function () use ( $name ) {
                unset( $this->servicesBeingCreated[$name] );
            } );
 
            $service = ( $this->serviceInstantiators[$name] )(
                $this,
                ...$this->extraInstantiationParams
            );
 
            if ( isset( $this->serviceManipulators[$name] ) ) {
                foreach ( $this->serviceManipulators[$name] as $callback ) {
                    $ret = call_user_func_array(
                        $callback,
                        array_merge( [ $service, $this ], $this->extraInstantiationParams )
                    );
 
                    // If the manipulator callback returns an object, that object replaces
                    // the original service instance. This allows the manipulator to wrap
                    // or fully replace the service.
                    if ( $ret !== null ) {
                        $service = $ret;
                    }
                }
            }
 
            $removeFromStack->consume();
 
            // NOTE: when adding more wiring logic here, make sure importWiring() is kept in sync!
        } else {
            throw new NoSuchServiceException( $name );
        }
 
        return $service;
    }
 
    public function isServiceDisabled( $name ) {
        return isset( $this->disabled[$name] );
    }
}
 
class_alias( ServiceContainer::class, 'MediaWiki\Services\ServiceContainer' );