1 | <?php |
||
30 | class ProjectDescriptorBuilder |
||
31 | { |
||
32 | /** @var string */ |
||
33 | public const DEFAULT_PROJECT_NAME = 'Untitled project'; |
||
34 | |||
35 | /** @var AssemblerFactory $assemblerFactory */ |
||
36 | protected $assemblerFactory; |
||
37 | |||
38 | /** @var Filter $filter */ |
||
39 | protected $filter; |
||
40 | |||
41 | /** @var ProjectDescriptor $project */ |
||
42 | protected $project; |
||
43 | |||
44 | /** @var string */ |
||
45 | private $defaultPackage = ''; |
||
46 | |||
47 | /** @var iterable<WithCustomSettings> */ |
||
48 | private $servicesWithCustomSettings; |
||
49 | |||
50 | /** @var ApiSpecification */ |
||
51 | private $apiSpecification; |
||
52 | |||
53 | /** |
||
54 | * @param iterable<WithCustomSettings> $servicesWithCustomSettings |
||
|
|||
55 | */ |
||
56 | 1 | public function __construct( |
|
57 | AssemblerFactory $assemblerFactory, |
||
58 | Filter $filterManager, |
||
59 | iterable $servicesWithCustomSettings = [] |
||
60 | ) { |
||
61 | 1 | $this->assemblerFactory = $assemblerFactory; |
|
62 | 1 | $this->filter = $filterManager; |
|
63 | 1 | $this->servicesWithCustomSettings = $servicesWithCustomSettings; |
|
64 | 1 | } |
|
65 | |||
66 | 2 | public function createProjectDescriptor() : void |
|
67 | { |
||
68 | 2 | $this->project = new ProjectDescriptor(self::DEFAULT_PROJECT_NAME); |
|
69 | 2 | } |
|
70 | |||
71 | /** |
||
72 | * Returns the project descriptor that is being built. |
||
73 | */ |
||
74 | 2 | public function getProjectDescriptor() : ProjectDescriptor |
|
75 | { |
||
76 | 2 | return $this->project; |
|
77 | } |
||
78 | |||
79 | /** |
||
80 | * Takes the given data and attempts to build a Descriptor from it. |
||
81 | * |
||
82 | * @param class-string<TDescriptor> $type |
||
83 | * |
||
84 | * @return TDescriptor|null |
||
85 | * |
||
86 | * @throws InvalidArgumentException If no Assembler could be found that matches the given data. |
||
87 | * |
||
88 | * @template TDescriptor of Descriptor |
||
89 | */ |
||
90 | public function buildDescriptor(object $data, string $type) : ?Descriptor |
||
91 | { |
||
92 | $assembler = $this->getAssembler($data, $type); |
||
93 | if (!$assembler) { |
||
94 | throw new InvalidArgumentException( |
||
95 | 'Unable to build a Descriptor; the provided data did not match any Assembler ' . |
||
96 | get_class($data) |
||
97 | ); |
||
98 | } |
||
99 | |||
100 | if ($assembler instanceof Builder\AssemblerAbstract) { |
||
101 | $assembler->setBuilder($this); |
||
102 | } |
||
103 | |||
104 | // create Descriptor and populate with the provided data |
||
105 | return $this->filterDescriptor($assembler->create($data)); |
||
106 | } |
||
107 | |||
108 | /** |
||
109 | * Attempts to find an assembler matching the given data. |
||
110 | * |
||
111 | * @param TInput $data |
||
112 | * @param class-string<TDescriptor> $type |
||
113 | * |
||
114 | * @return AssemblerInterface<TDescriptor, TInput>|null |
||
115 | * |
||
116 | * @template TInput as object |
||
117 | * @template TDescriptor as Descriptor |
||
118 | */ |
||
119 | public function getAssembler(object $data, string $type) : ?AssemblerInterface |
||
120 | { |
||
121 | return $this->assemblerFactory->get($data, $type); |
||
122 | } |
||
123 | |||
124 | /** |
||
125 | * Analyzes a Descriptor and alters its state based on its state or even removes the descriptor. |
||
126 | * |
||
127 | * @param TDescriptor $descriptor |
||
128 | * |
||
129 | * @return TDescriptor|null |
||
130 | * |
||
131 | * @template TDescriptor as Filterable |
||
132 | */ |
||
133 | public function filter(Filterable $descriptor) : ?Filterable |
||
134 | { |
||
135 | return $this->filter->filter($descriptor, $this->apiSpecification); |
||
136 | } |
||
137 | |||
138 | /** |
||
139 | * Filters a descriptor, validates it, stores the validation results and returns the transmuted object or null |
||
140 | * if it is supposed to be removed. |
||
141 | * |
||
142 | * @param TDescriptor $descriptor |
||
143 | * |
||
144 | * @return TDescriptor|null |
||
145 | * |
||
146 | * @template TDescriptor as Descriptor |
||
147 | */ |
||
148 | protected function filterDescriptor(Descriptor $descriptor) : ?Descriptor |
||
149 | { |
||
150 | if (!$descriptor instanceof Filterable) { |
||
151 | return $descriptor; |
||
152 | } |
||
153 | |||
154 | // filter the descriptor; this may result in the descriptor being removed! |
||
155 | $descriptor = $this->filter($descriptor); |
||
156 | |||
157 | return $descriptor; |
||
158 | } |
||
159 | |||
160 | public function setApiSpecification(ApiSpecification $apiSpecification) : void |
||
161 | { |
||
162 | $this->apiSpecification = $apiSpecification; |
||
163 | } |
||
164 | |||
165 | public function createApiDocumentationSet(Project $project) : void |
||
166 | { |
||
167 | $packageName = $project->getRootNamespace()->getFqsen()->getName(); |
||
168 | $this->defaultPackage = $packageName; |
||
169 | |||
170 | $customSettings = $this->getProjectDescriptor()->getSettings()->getCustom(); |
||
171 | foreach ($this->servicesWithCustomSettings as $service) { |
||
172 | // We assume that the custom settings have the non-default settings and we should not override those; |
||
173 | // that is why we merge the custom settings on top of the default settings; this will cause the overrides |
||
174 | // to remain in place. |
||
175 | $customSettings = array_merge($service->getDefaultSettings(), $customSettings); |
||
176 | } |
||
177 | |||
178 | $this->getProjectDescriptor()->getSettings()->setCustom($customSettings); |
||
179 | |||
180 | foreach ($project->getFiles() as $file) { |
||
181 | $descriptor = $this->buildDescriptor($file, FileDescriptor::class); |
||
182 | if ($descriptor === null) { |
||
183 | continue; |
||
184 | } |
||
185 | |||
186 | $this->getProjectDescriptor()->getFiles()->set($descriptor->getPath(), $descriptor); |
||
187 | } |
||
188 | |||
189 | $namespaces = $this->getProjectDescriptor()->getIndexes()->fetch('namespaces', new Collection()); |
||
190 | |||
191 | foreach ($project->getNamespaces() as $namespace) { |
||
192 | $namespaces->set( |
||
193 | (string) $namespace->getFqsen(), |
||
194 | $this->buildDescriptor($namespace, NamespaceDescriptor::class) |
||
195 | ); |
||
196 | } |
||
197 | } |
||
198 | |||
199 | public function getDefaultPackage() : string |
||
203 | |||
204 | 1 | public function setVisibility(int $visibility) : void |
|
205 | { |
||
206 | 1 | $this->project->getSettings()->setVisibility($visibility); |
|
207 | 1 | } |
|
208 | |||
209 | public function shouldIncludeSource() : bool |
||
210 | { |
||
211 | return $this->apiSpecification['include-source']; |
||
212 | } |
||
213 | |||
214 | public function setName(string $title) : void |
||
215 | { |
||
216 | $this->project->setName($title); |
||
217 | } |
||
218 | |||
219 | /** |
||
220 | * @param Collection<string> $partials |
||
221 | */ |
||
222 | public function setPartials(Collection $partials) : void |
||
223 | { |
||
224 | $this->project->setPartials($partials); |
||
225 | } |
||
226 | |||
227 | /** |
||
228 | * @param array<string, string> $customSettings |
||
229 | */ |
||
230 | public function setCustomSettings(array $customSettings) : void |
||
234 | |||
235 | public function addVersion(VersionDescriptor $version) : void |
||
236 | { |
||
237 | $this->project->getVersions()->add($version); |
||
239 | } |
||
240 |
This check marks PHPDoc comments that could not be parsed by our parser. To see which comment annotations we can parse, please refer to our documentation on supported doc-types.