src/Core/Hooks/Capabilities/ICanManageInstances.php

   1 <?php
   2 /**
   3  * @copyright Copyright (C) 2010-2023, the Friendica project
   4  *
   5  * @license GNU AGPL version 3 or any later version
   6  *
   7  * This program is free software: you can redistribute it and/or modify
   8  * it under the terms of the GNU Affero General Public License as
   9  * published by the Free Software Foundation, either version 3 of the
  10  * License, or (at your option) any later version.
  11  *
  12  * This program is distributed in the hope that it will be useful,
  13  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  14  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  15  * GNU Affero General Public License for more details.
  16  *
  17  * You should have received a copy of the GNU Affero General Public License
  18  * along with this program.  If not, see <https://www.gnu.org/licenses/>.
  19  *
  20  */
  21
  22 namespace Friendica\Core\Hooks\Capabilities;
  23
  24 use Friendica\Core\Hooks\Exceptions\HookInstanceException;
  25 use Friendica\Core\Hooks\Exceptions\HookRegisterArgumentException;
  26
  27 /**
  28  * Managing special instance and decorator treatments for classes
  29  */
  30 interface ICanManageInstances
  31 {
  32         /**
  33          * Register a class(strategy) for a given interface with a unique name.
  34          *
  35          * @see https://refactoring.guru/design-patterns/strategy
  36          *
  37          * @param string $interface The interface, which the given class implements
  38          * @param string $name      An arbitrary identifier for the given class, which will be used for factories, dependency injections etc.
  39          * @param string $class     The fully-qualified given class name
  40          * @param ?array  $arguments Additional arguments, which can be passed to the constructor
  41          *
  42          * @return $this This interface for chain-calls
  43          *
  44          * @throws HookRegisterArgumentException in case the given class for the interface isn't valid or already set
  45          */
  46         public function registerStrategy(string $interface, string $name, string $class, array $arguments = null): self;
  47
  48         /**
  49          * Register a new decorator for a given class or interface
  50          * @see https://refactoring.guru/design-patterns/decorator
  51          *
  52          * @note Decorator attach new behaviors to classes without changing them or without letting them know about it.
  53          *
  54          * @param string $class          The fully-qualified class or interface name, which gets decorated by a class
  55          * @param string $decoratorClass The fully-qualified name of the class which mimics the given class or interface and adds new functionality
  56          * @param array  $arguments      Additional arguments, which can be passed to the constructor of "decoratorClass"
  57          *
  58          * @return $this This interface for chain-calls
  59          *
  60          * @throws HookRegisterArgumentException in case the given class for the class or interface isn't valid
  61          */
  62         public function registerDecorator(string $class, string $decoratorClass, array $arguments = []): self;
  63
  64         /**
  65          * Returns a new instance of a given class for the corresponding name
  66          *
  67          * The instance will be build based on the registered strategy and the (unique) name
  68          *
  69          * In case, there are registered decorators for this class as well, all decorators of the list will be wrapped
  70          * around the instance before returning it
  71          *
  72          * @param string $class     The fully-qualified name of the given class or interface which will get returned
  73          * @param string $name      The name of the concrete class, wich
  74          * @param array  $arguments Additional arguments, which can be passed to the constructor of "$class" at runtime
  75          *
  76          * @return object The concrete instance of the type "$class"
  77          *
  78          * @throws HookInstanceException In case the class cannot get created
  79          */
  80         public function getInstance(string $class, string $name, array $arguments = []): object;
  81 }