1<?php 2/** 3 * This file is part of phpDocumentor. 4 * 5 * For the full copyright and license information, please view the LICENSE 6 * file that was distributed with this source code. 7 * 8 * @copyright 2010-2015 Mike van Riel<mike@phpdoc.org> 9 * @license http://www.opensource.org/licenses/mit-license.php MIT 10 * @link http://phpdoc.org 11 */ 12 13namespace phpDocumentor\Reflection\DocBlock; 14 15use phpDocumentor\Reflection\Types\Context as TypeContext; 16 17interface TagFactory 18{ 19 /** 20 * Adds a parameter to the service locator that can be injected in a tag's factory method. 21 * 22 * When calling a tag's "create" method we always check the signature for dependencies to inject. One way is to 23 * typehint a parameter in the signature so that we can use that interface or class name to inject a dependency 24 * (see {@see addService()} for more information on that). 25 * 26 * Another way is to check the name of the argument against the names in the Service Locator. With this method 27 * you can add a variable that will be inserted when a tag's create method is not typehinted and has a matching 28 * name. 29 * 30 * Be aware that there are two reserved names: 31 * 32 * - name, representing the name of the tag. 33 * - body, representing the complete body of the tag. 34 * 35 * These parameters are injected at the last moment and will override any existing parameter with those names. 36 * 37 * @param string $name 38 * @param mixed $value 39 * 40 * @return void 41 */ 42 public function addParameter($name, $value); 43 44 /** 45 * Registers a service with the Service Locator using the FQCN of the class or the alias, if provided. 46 * 47 * When calling a tag's "create" method we always check the signature for dependencies to inject. If a parameter 48 * has a typehint then the ServiceLocator is queried to see if a Service is registered for that typehint. 49 * 50 * Because interfaces are regularly used as type-hints this method provides an alias parameter; if the FQCN of the 51 * interface is passed as alias then every time that interface is requested the provided service will be returned. 52 * 53 * @param object $service 54 * @param string $alias 55 * 56 * @return void 57 */ 58 public function addService($service); 59 60 /** 61 * Factory method responsible for instantiating the correct sub type. 62 * 63 * @param string $tagLine The text for this tag, including description. 64 * @param TypeContext $context 65 * 66 * @throws \InvalidArgumentException if an invalid tag line was presented. 67 * 68 * @return Tag A new tag object. 69 */ 70 public function create($tagLine, TypeContext $context = null); 71 72 /** 73 * Registers a handler for tags. 74 * 75 * If you want to use your own tags then you can use this method to instruct the TagFactory to register the name 76 * of a tag with the FQCN of a 'Tag Handler'. The Tag handler should implement the {@see Tag} interface (and thus 77 * the create method). 78 * 79 * @param string $tagName Name of tag to register a handler for. When registering a namespaced tag, the full 80 * name, along with a prefixing slash MUST be provided. 81 * @param string $handler FQCN of handler. 82 * 83 * @throws \InvalidArgumentException if the tag name is not a string 84 * @throws \InvalidArgumentException if the tag name is namespaced (contains backslashes) but does not start with 85 * a backslash 86 * @throws \InvalidArgumentException if the handler is not a string 87 * @throws \InvalidArgumentException if the handler is not an existing class 88 * @throws \InvalidArgumentException if the handler does not implement the {@see Tag} interface 89 * 90 * @return void 91 */ 92 public function registerTagHandler($tagName, $handler); 93} 94