1	<?php
2	/**
3	*
4	* This file is part of the phpBB Forum Software package.
5	*
6	* @copyright (c) phpBB Limited <https://www.phpbb.com>
7	* @license GNU General Public License, version 2 (GPL-2.0)
8	*
9	* For full copyright and license information, please see
10	* the docs/CREDITS.txt file.
11	*
12	*/
13
14	namespace phpbb\ban\type;
15
16	/**
17	* Interface implemented by all ban types
18	*/
19	interface type_interface
20	{
21	/**
22	* Returns the type identifier for this ban type
23	*
24	* @return string
25	*/
26	public function get_type(): string;
27
28	/**
29	* Returns the column in the users table which contains
30	* the values that should be looked for when checking a ban.
31	* If it returns null, the check method will be called when
32	* checking for bans.
33	*
34	* @return string|null
35	*/
36	public function get_user_column(): ?string;
37
38	/**
39	* Sets a user object to the ban type to have it excluded
40	* from banning.
41	*
42	* @param \phpbb\user    $user    An user object
43	*
44	* @return void
45	*/
46	public function set_user(\phpbb\user $user): void;
47
48	/**
49	* Gives the possibility to do some clean up after banning.
50	* The return value of this method will be passed through
51	* to the caller.
52	*
53	* @param array $data An array containing information about
54	*                    the bans, like the reason or the start
55	*                    and end of the ban
56	*
57	* @return array List of banned users
58	*/
59	public function after_ban(array $data): array;
60
61	/**
62	* Gives the possibility to do some clean up after unbanning.
63	* The return value of this method will be passed through
64	* to the caller.
65	*
66	* @param array $data An array containing information about
67	*                    the unbans, e.g. the unbanned items.
68	*
69	* @return array List of unbanned users
70	*/
71	public function after_unban(array $data): array;
72
73	/**
74	* In the case that get_user_column() returns null, this method
75	* is called when checking the ban status.
76	* Please note, that this method is basically called on every page,
77	* so the check should perform rather fast.
78	*
79	* Returns an array with information about the ban, like the end or
80	* the reason. False if the user is not banned.
81	*
82	* @param array $ban_rows    An array containing the ban rows retrieved
83	*                            from the database for this specific mode.
84	*                            They contain the item, reason and end of the ban.
85	* @param array $user_data    The user data
86	*
87	* @return array|bool
88	*/
89	public function check(array $ban_rows, array $user_data);
90
91	/**
92	* In case get_user_column() returns no string, this method will be called
93	* when a list of banned users is retrieved.
94	* Returns a list of banned users.
95	* The result is cached and is not used for ban checking, so the accuracy
96	* of the results is not as important as when *really* checking in check()
97	*
98	* @return array An array of banned users, where the user ids are the keys
99	*               and the value is the end of the ban (or 0 if permanent)
100	*/
101	public function get_banned_users(): array;
102
103	/**
104	* Get ban options mapping ban ID to an option to display to admins
105	*
106	* @return array
107	*/
108	public function get_ban_options(): array;
109
110	/**
111	* Prepares the given ban items before saving them in the database
112	*
113	* @param array $items
114	*
115	* @return array
116	*/
117	public function prepare_for_storage(array $items): array;
118
119	/**
120	* Does some cleanup work for the banning mode.
121	* Is called before banning and unbanning and as cron job.
122	*
123	* @return void
124	*/
125	public function tidy(): void;
126	}