xref: /webtrees/app/Module/ModuleInterface.php (revision 24931b29a0237a5f5f1b8620af661ea530451af0) 
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    /**
81     * A sentence describing what this module does.
82     *
83     * @return string
84     */
85    public function description(): string;
86
87    /**
88     * Get the current access level for a module
89     *
90     * @template T of ModuleInterface
91     *
92     * @param Tree            $tree
93     * @param class-string<T> $interface
94     *
95     * @return int
96     */
97    public function accessLevel(Tree $tree, string $interface): int;
98
99    /**
100     * Get a module setting. Return a default if the setting is not set.
101     *
102     * @param string $setting_name
103     * @param string $default
104     *
105     * @return string
106     */
107    public function getPreference(string $setting_name, string $default = ''): string;
108
109    /**
110     * Set a module setting.
111     *
112     * Since module settings are NOT NULL, setting a value to NULL will cause
113     * it to be deleted.
114     *
115     * @param string $setting_name
116     * @param string $setting_value
117     *
118     * @return void
119     */
120    public function setPreference(string $setting_name, string $setting_value): void;
121
122    /**
123     * Where does this module store its resources
124     *
125     * @return string
126     */
127    public function resourcesFolder(): string;
128}
129