xref: /webtrees/app/Module/ModuleInterface.php (revision 3cd40af69d340ac971a1172bf21e4696be693063) 
1<?php
2
3/**
4 * webtrees: online genealogy
5 * Copyright (C) 2023 webtrees development team
6 * This program is free software: you can redistribute it and/or modify
7 * it under the terms of the GNU General Public License as published by
8 * the Free Software Foundation, either version 3 of the License, or
9 * (at your option) any later version.
10 * This program is distributed in the hope that it will be useful,
11 * but WITHOUT ANY WARRANTY; without even the implied warranty of
12 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
13 * GNU General Public License for more details.
14 * You should have received a copy of the GNU General Public License
15 * along with this program. If not, see <https://www.gnu.org/licenses/>.
16 */
17
18declare(strict_types=1);
19
20namespace Fisharebest\Webtrees\Module;
21
22use Fisharebest\Webtrees\Tree;
23
24/**
25 * Interface ModuleInterface - Classes and libraries for module system
26 */
27interface ModuleInterface
28{
29    /**
30     * Early initialisation.  Called before most of the middleware.
31     */
32    public function boot(): void;
33
34    /**
35     * A unique internal name for this module (based on the installation folder).
36     *
37     * @param string $name
38     *
39     * @return void
40     */
41    public function setName(string $name): void;
42
43    /**
44     * A unique internal name for this module (based on the installation folder).
45     *
46     * @return string
47     */
48    public function name(): string;
49
50    /**
51     * Has the module been disabled in the control panel?
52     *
53     * @param bool $enabled
54     *
55     * @return self
56     */
57    public function setEnabled(bool $enabled): self;
58
59    /**
60     * Has the module been disabled in the control panel?
61     *
62     * @return bool
63     */
64    public function isEnabled(): bool;
65
66    /**
67     * Should this module be enabled when it is first installed?
68     *
69     * @return bool
70     */
71    public function isEnabledByDefault(): bool;
72
73    /**
74     * How should this module be identified in the control panel, etc.?
75     *
76     * @return string
77     */
78    public function title(): string;
79
80    public function description(): string;
81
82    /**
83     * Get the current access level for a module
84     *
85     * @template T of ModuleInterface
86     *
87     * @param Tree            $tree
88     * @param class-string<T> $interface
89     *
90     * @return int
91     */
92    public function accessLevel(Tree $tree, string $interface): int;
93
94    /**
95     * Get a module setting. Return a default if the setting is not set.
96     *
97     * @param string $setting_name
98     * @param string $default
99     *
100     * @return string
101     */
102    public function getPreference(string $setting_name, string $default = ''): string;
103
104    /**
105     * Set a module setting.
106     *
107     * Since module settings are NOT NULL, setting a value to NULL will cause
108     * it to be deleted.
109     *
110     * @param string $setting_name
111     * @param string $setting_value
112     *
113     * @return void
114     */
115    public function setPreference(string $setting_name, string $setting_value): void;
116
117    /**
118     * Where does this module store its resources
119     *
120     * @return string
121     */
122    public function resourcesFolder(): string;
123}
124