1	<?php
2
3	/**
4	* Tree builder interface for phpMyFAQ category trees.
5	*
6	* This Source Code Form is subject to the terms of the Mozilla Public License,
7	* v. 2.0. If a copy of the MPL was not distributed with this file, You can
8	* obtain one at https://mozilla.org/MPL/2.0/.
9	*
10	* @package   phpMyFAQ
11	* @author    Thorsten Rinne <thorsten@phpmyfaq.de>
12	* @copyright 2025 phpMyFAQ Team
13	* @license   https://www.mozilla.org/MPL/2.0/ Mozilla Public License Version 2.0
14	* @link      https://www.phpmyfaq.de
15	* @since     2025-10-20
16	*/
17
18	declare(strict_types=1);
19
20	namespace phpMyFAQ\Category\Tree;
21
22	interface TreeBuilderInterface
23	{
24	/**
25	* Builds a linear tree structure with indentation levels.
26	*
27	* @param array<int, array<string, mixed>> $categories
28	* @return array<int, array<string, mixed>>
29	*/
30	public function buildLinearTree(array $categories, int $parentId = 0, int $indent = 0): array;
31
32	/**
33	* Builds the admin category tree structure.
34	*
35	* @param array<int, array<string, mixed>> $categories
36	* @return array<int, array<array-key, mixed>>
37	*/
38	public function buildAdminCategoryTree(array $categories, int $parentId = 0): array;
39
40	/**
41	* Builds a hierarchical tree structure from flat category data.
42	*
43	* @param array<int, array<string, mixed>> $categoryNames
44	* @param array<int, array<int, array<string, mixed>>> $children
45	* @return array<int, string>
46	*/
47	public function buildTree(array $categoryNames, array $children, int $categoryId): array;
48
49	/**
50	* Gets direct children IDs of a category.
51	*
52	* @param array<int, array<int, array<string, mixed>>> $childrenMap
53	* @return array<int>
54	*/
55	public function getChildren(array $childrenMap, int $categoryId): array;
56
57	/**
58	* Gets all descendant IDs of a category (recursively).
59	*
60	* @param array<int, array<int, array<string, mixed>>> $childrenMap
61	* @return array<int>
62	*/
63	public function getChildNodes(array $childrenMap, int $categoryId): array;
64
65	/**
66	* Gets the path from root to a category (list of ancestor IDs).
67	*
68	* @param array<int, array<string, mixed>> $categoryNames
69	* @return array<int>
70	*/
71	public function getNodes(array $categoryNames, int $categoryId): array;
72
73	/**
74	* Gets sibling category IDs (including the category itself).
75	*
76	* @param array<int, array<string, mixed>> $categoryNames
77	* @param array<int, array<int, array<string, mixed>>> $children
78	* @return array<int>
79	*/
80	public function getBrothers(array $categoryNames, array $children, int $categoryId): array;
81
82	/**
83	* Computes the depth level of a category in the tree.
84	*
85	* @param array<int, array<string, mixed>> $categoryNames
86	*/
87	public function computeLevel(array $categoryNames, int $categoryId): int;
88	}