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