1	<?php declare(strict_types=1);
2	/*
3	* This file is part of Aplus Framework Routing Library.
4	*
5	* (c) Natan Felles <natanfelles@gmail.com>
6	*
7	* For the full copyright and license information, please view the LICENSE
8	* file that was distributed with this source code.
9	*/
10	namespace Framework\Routing;
11
12	use Framework\HTTP\Method;
13	use Framework\HTTP\Response;
14	use Framework\HTTP\Status;
15
16	/**
17	* Interface PresenterInterface.
18	*
19	* The interface for data management via a Web Browser UI
20	* using the HTTP GET and POST methods.
21	*
22	* Note: If a presenter needs more than one parameter to get URL path information
23	* provided by placeholders, in addition to $id, do not implement this interface.
24	* But this interface can be a reference because its method names are used in
25	* {@see RouteCollection::presenter()}.
26	*
27	* @see https://developer.mozilla.org/en-US/docs/Glossary/UI
28	*
29	* @package routing
30	*/
31	interface PresenterInterface
32	{
33	/**
34	* Handles a GET request for /.
35	*
36	* Common usage: Show a list of paginated items.
37	*
38	* @see Method::GET
39	*
40	* @return mixed
41	*/
42	public function index() : mixed;
43
44	/**
45	* Handles a GET request for /new.
46	*
47	* Common usage: Show a form with inputs to create a new item.
48	* The POST action must go to the 'create' method URL.
49	*
50	* @see PresenterInterface::create()
51	* @see Method::GET
52	*
53	* @return mixed
54	*/
55	public function new() : mixed;
56
57	/**
58	* Handles a POST request for /.
59	*
60	* Common usage: Try to create a new item. On success, redirect to the 'show' or
61	* 'edit' method URL. On fail, back to the 'new' method URL.
62	*
63	* @see PresenterInterface::edit()
64	* @see PresenterInterface::new()
65	* @see PresenterInterface::show()
66	* @see Method::POST
67	* @see Response::redirect()
68	*
69	* @return mixed
70	*/
71	public function create() : mixed;
72
73	/**
74	* Handles a GET request for /$id.
75	*
76	* Common usage: Show a specific item based on the $id.
77	*
78	* @param string $id
79	*
80	* @see Method::GET
81	* @see Status::NOT_FOUND
82	*
83	* @return mixed
84	*/
85	public function show(string $id) : mixed;
86
87	/**
88	* Handles a GET request for /$id/edit.
89	*
90	* Common usage: Show a form to edit a specific item based on the $id.
91	* The POST action must go to the 'update' method URL.
92	*
93	* @param string $id
94	*
95	* @see PresenterInterface::update()
96	* @see Method::GET
97	*
98	* @return mixed
99	*/
100	public function edit(string $id) : mixed;
101
102	/**
103	* Handles a POST request for /$id/update.
104	*
105	* Common usage: Try to update an item based on the $id. After the process, back
106	* to the 'edit' method URL and show a message.
107	*
108	* @param string $id
109	*
110	* @see PresenterInterface::edit()
111	* @see Method::POST
112	* @see Response::redirect()
113	*
114	* @return mixed
115	*/
116	public function update(string $id) : mixed;
117
118	/**
119	* Handles a GET request for /$id/remove.
120	*
121	* Common usage: Show an alert message about the item to be deleted based on the
122	* $id. The confirmation action must call a POST request to the 'delete'
123	* method URL.
124	*
125	* @param string $id
126	*
127	* @see PresenterInterface::delete()
128	* @see Method::GET
129	*
130	* @return mixed
131	*/
132	public function remove(string $id) : mixed;
133
134	/**
135	* Handles a POST request for /$id/delete.
136	*
137	* Common usage: Try to delete an item based on the $id. On success, go to the
138	* 'index' method URL and show a success message. On fail, back to the 'remove'
139	* method URL and show the error message.
140	*
141	* @param string $id
142	*
143	* @see PresenterInterface::index()
144	* @see PresenterInterface::remove()
145	* @see Method::POST
146	* @see Response::redirect()
147	*
148	* @return mixed
149	*/
150	public function delete(string $id) : mixed;
151	}