1	<?php
2	declare(strict_types=1);
3
4	namespace Korobochkin\WPKit\Pages;
5
6	use Korobochkin\WPKit\Pages\Views\PageViewInterface;
7	use Symfony\Component\Form\FormFactoryInterface;
8	use Symfony\Component\Form\FormInterface;
9	use Symfony\Component\HttpFoundation\Request;
10
11	/**
12	* Interface PageInterface represents single admin page in WordPress.
13	*
14	* Use this interface to create your page or use predefined classes which implements
15	* this interface.
16	*/
17	interface PageInterface
18	{
19	/**
20	* Called to late construct the page instance.
21	*
22	* Usually defining priority of calling this method defined in register method.
23	*
24	* Called only if user can see this page (have required capability).
25	*
26	* Validation process in wp-admin/includes/menu.php
27	* 1. admin.php:138
28	* 2. require(ABSPATH . 'wp-admin/menu.php') (138 line)
29	* 3. require_once(ABSPATH . 'wp-admin/includes/menu.php') (282 line).
30	* 4. if ( !user_can_access_admin_page() ) (333 line).
31	*
32	* @see register
33	*
34	* @return $this For chain calls.
35	*/
36	public function lateConstruct();
37
38	/**
39	* Returns name of the page.
40	*
41	* @return string Name of the page.
42	*/
43	public function getName();
44
45	/**
46	* Sets name of the page.
47	*
48	* @param $name string Name of the page.
49	*
50	* @return $this For chain calls.
51	*/
52	public function setName($name);
53
54	/**
55	* Returns the page title.
56	*
57	* @return string Title of the page.
58	*/
59	public function getPageTitle();
60
61	/**
62	* Setups the page title.
63	*
64	* @param $title string Title of the page.
65	*
66	* @return $this For chain calls.
67	*/
68	public function setPageTitle($title);
69
70	/**
71	* Returns the menu page title.
72	*
73	* Used as label (title) in WordPress aside menu.
74	*
75	* @return string Menu title of the page.
76	*/
77	public function getMenuTitle();
78
79	/**
80	* Sets the menu page title.
81	*
82	* @param $title string Menu title of the page.
83	*
84	* @return $this For chain calls.
85	*/
86	public function setMenuTitle($title);
87
88	/**
89	* Returns capability needed to access to the page.
90	*
91	* @return string Capability.
92	*/
93	public function getCapability();
94
95	/**
96	* Sets capability needed to access to the page.
97	*
98	* @param $capability string WordPress capability.
99	*
100	* @return $this For chain calls.
101	*/
102	public function setCapability($capability);
103
104	/**
105	* Returns page menu slug.
106	*
107	* Used in URL.
108	*
109	* @return string Menu slug.
110	*/
111	public function getMenuSlug();
112
113	/**
114	* Sets page menu slug.
115	*
116	* @param $menuSlug string Menu slug.
117	*
118	* @return $this For chain calls.
119	*/
120	public function setMenuSlug($menuSlug);
121
122	/**
123	* Returns page view instance.
124	*
125	* This instance will render the page.
126	*
127	* @return PageViewInterface Page view instance.
128	*/
129	public function getView();
130
131	/**
132	* Sets page view instance.
133	*
134	* @param PageViewInterface $view Page view.
135	*
136	* @return $this For chain calls.
137	*/
138	public function setView(PageViewInterface $view);
139
140	/**
141	* Render the page with PageView instance.
142	*
143	* This method outputting HTML.
144	*/
145	public function render();
146
147	/**
148	* Returns HTTP request.
149	*
150	* @return Request HTTP Request.
151	*/
152	public function getRequest();
153
154	/**
155	* Sets HTTP request.
156	*
157	* @param Request $request HTTP request.
158	*
159	* @return $this For chain calls.
160	*/
161	public function setRequest(Request $request);
162
163	/**
164	* Register the page in WordPress Pages-Settings API.
165	*
166	* After calling this method the page available in WordPress.
167	*
168	* @return $this For chain calls.
169	*/
170	public function register();
171
172	/**
173	* Un register the page in WordPress Pages-Settings API.
174	*
175	* @throws \Exception If page not removed (WordPress not found this page as registered page).
176	*
177	* @return $this For chain calls.
178	*/
179	public function unRegister();
180
181	/**
182	* Returns the page url.
183	*
184	* @return string The page url.
185	*/
186	public function getURL();
187
188	/** The methods bellow used to work with forms. */
189
190	/**
191	* Returns form factory.
192	*
193	* @return FormFactoryInterface Form factory for building forms.
194	*/
195	public function getFormFactory();
196
197	/**
198	* Sets the form factory to build forms.
199	*
200	* @param $formFactory FormFactoryInterface Form factory.
201	*
202	* @return $this For chain calls.
203	*/
204	public function setFormFactory(FormFactoryInterface $formFactory);
205
206	/**
207	* Returns the form for this page.
208	*
209	* @return FormInterface HTML form.
210	*/
211	public function getForm();
212
213	/**
214	* Sets the form for this page.
215	*
216	* @param FormInterface $form HTML form.
217	*
218	* @return $this For chain calls.
219	*/
220	public function setForm(FormInterface $form);
221
222	/**
223	* Returns the form data entity.
224	*
225	* @return object Form entity.
226	*/
227	public function getFormEntity();
228
229	/**
230	* Sets the form entity.
231	*
232	* @param object $formEntity form data-entity.
233	*
234	* @return $this For chain calls.
235	*/
236	public function setFormEntity($formEntity);
237
238	/**
239	* Returns tabs.
240	*
241	* @return Tabs\TabsInterface Tabs for page.
242	*/
243	public function getTabs();
244
245	/**
246	* Sets tabs.
247	*
248	* @param Tabs\TabsInterface $tabs Tabs for page.
249	*
250	* @return $this For chain calls.
251	*/
252	public function setTabs(Tabs\TabsInterface $tabs);
253
254	/**
255	* Be sure to call it only from $this->lateConstruct()
256	* to prevent illegal access to the page handling.
257	*/
258	public function handleRequest();
259	}