1	<?php
2
3	/**
4	* Category repository interface for phpMyFAQ.
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-18
16	*/
17
18	declare(strict_types=1);
19
20	namespace phpMyFAQ\Category;
21
22	use phpMyFAQ\Entity\CategoryEntity;
23
24	interface CategoryRepositoryInterface
25	{
26	/**
27	* Returns all categories ordered, optionally filtered by permission, activity, and language.
28	*
29	* @param int[]       $groups
30	* @return array<int, array<string, mixed>>
31	*/
32	public function findOrderedCategories(
33	array $groups,
34	int $userId,
35	?string $language,
36	bool $withPermission = true,
37	bool $withInactive = false,
38	): array;
39
40	/**
41	* @return array<int, array<string, mixed>>
42	*/
43	public function findAllCategories(?string $language = null): array;
44
45	/**
46	* @return int[]
47	*/
48	public function findAllCategoryIds(?string $language = null): array;
49
50	public function findByIdAndLanguage(int $categoryId, string $language): ?CategoryEntity;
51
52	/**
53	* @return array<int, array<string, mixed>>
54	*/
55	public function findCategoriesFromFaq(int $faqId, string $language): array;
56
57	public function findCategoryIdByName(string $categoryName): ?int;
58
59	public function create(CategoryEntity $categoryEntity): ?int;
60
61	public function update(CategoryEntity $categoryEntity): bool;
62
63	public function moveOwnership(int $currentOwner, int $newOwner): bool;
64
65	public function hasLanguage(int $categoryId, string $categoryLanguage): bool;
66
67	public function updateParentCategory(int $categoryId, int $parentId): bool;
68
69	public function delete(int $categoryId, string $categoryLang): bool;
70
71	/**
72	* @return array<string, string>
73	*/
74	public function getCategoryLanguagesTranslated(int $categoryId): array;
75
76	/**
77	* Returns categories missing in the given language (used in the admin section).
78	*
79	* @return array<int, array<string, mixed>>
80	*/
81	public function findMissingCategories(?string $language = null): array;
82
83	/**
84	* Returns the number of categories that match name, language, and parent.
85	*/
86	public function countByNameLangParent(string $name, string $lang, int $parentId): int;
87
88	/**
89	* Checks if a category has a link to a specific FAQ.
90	*/
91	public function hasLinkToFaq(int $faqId, int $categoryId): bool;
92
93	/**
94	* Returns a page of categories, optionally filtered by language,
95	* activity, and the user's group permissions.
96	*
97	* @param array<int> $groups
98	* @return array<array-key, mixed>
99	*/
100	/* @mago-expect lint:excessive-parameter-list - mirrors CategoryRepository::findCategoriesPaginated() */
101	public function findCategoriesPaginated(
102	?string $language = null,
103	int $limit = 25,
104	int $offset = 0,
105	string $sortField = 'id',
106	string $sortOrder = 'ASC',
107	bool $activeOnly = false,
108	array $groups = [-1],
109	int $userId = -1,
110	): array;
111
112	/**
113	* Returns the total number of categories matching the given filters.
114	*
115	* @param array<int> $groups
116	*/
117	public function countCategories(
118	?string $language = null,
119	bool $activeOnly = false,
120	array $groups = [-1],
121	int $userId = -1,
122	): int;
123	}