1	<?php
2
3	namespace Dynart\Micro;
4
5	/**
6	* Handles the routing
7	*
8	* Every web application needs a router for handling routes. A route is a HTTP method and path for a specific action.
9	*
10	* Example routes:
11	* * GET /books - returns a list of books
12	* * GET /books/123 - returns the details of a book with ID 123
13	* * POST /books/123/save - saves the details of a book with ID 123
14	*/
15	interface RouterInterface {
16	/**
17	* Returns with the current route
18	*
19	* The route HTTP query parameter name can be configured with the `router.route_parameter`.
20	* If no parameter exists the default will be the home route '/'
21	*
22	* @see Config
23	*/
24	public function currentRoute(): string;
25
26	/**
27	* Returns with a segment value of the current route by index
28	*/
29	public function currentSegment(int $index, mixed $default = null): mixed;
30
31	/**
32	* Adds a prefix variable callable for all of the routes
33	*
34	* For example, if you have a prefix variable that calls the `Translation::locale()` method
35	* and then you call the `url` method with '/something' and you configured the `app.base_url`
36	* to 'https://example.com' it will return with
37	*
38	* <pre>
39	* https://example.com/en/something
40	* </pre>
41	*
42	* @link https://www.php.net/manual/en/language.types.callable.php
43	*
44	* @return int The segment index of the newly added prefix variable
45	*/
46	public function addPrefixVariable(callable|array $callable): int;
47
48	/**
49	* Matches the current route and returns with the associated callable and parameters
50	*
51	* For example, the current route is '/books/123/comments/45',
52	* the stored route is '/books/?/comments/?' and it matches
53	* then the result will be:
54	*
55	* <p>[the stored callable for the route, ['123', '45']]</p>
56	*
57	* If no match for the current route it will return with `ROUTE_NOT_FOUND` alias [null, null]
58	*
59	* @return array The associated callable and parameters with the current route in [callable, [parameters]] format
60	*/
61	public function matchCurrentRoute(): array;
62
63	/**
64	* Returns with a URL for the given route
65	*
66	* Heavily depends on the configuration of the application.
67	*
68	* For example the parameters are the following:
69	* * `$route` = '/books/123'
70	* * `$params` = ['name' => 'joe']
71	* * `$amp` = '&'
72	*
73	* and the application config is the following:
74	*
75	* <pre>
76	* app.base_url = "http://example.com"
77	* router.use_rewrite = false
78	* router.index_file = "index.php"
79	* router.route_parameter = "route"
80	* </pre>
81	*
82	* then the result will be:
83	*
84	* <pre>
85	* http://example.com/index.php?route=/books/123&name=joe
86	* </pre>
87	*
88	* If the `router.use_rewrite` set to true, the `router.index_file` and the `router.route_parameter` will not be
89	* in the result, but for this you have to configure your webserver to redirect non existing
90	* file &amp; directory HTTP queries to your /index.php?route={URI}
91	*
92	* <pre>
93	* http://example.com/books/123?name=joe
94	* </pre>
95	*
96	* If you have a prefix variable added (usually locale) and that has the value 'en', the result will be:
97	*
98	* <pre>
99	* http://example.com/en/books/123?name=joe
100	* </pre>
101	*/
102	public function url(?string $route = null, array $params = [], string $amp = '&'): string;
103
104	/**
105	* Stores a route with a callable
106	*
107	* The `$callable` can use the [ExampleClass::class, 'exampleMethod'] format too.
108	*
109	* The route can have variables with question mark: '/route/?'
110	* then the callable method in this case must have one parameter!
111	*
112	* The `$method` can be any of the HTTP methods or BOTH. BOTH will add the route to the GET and to the POST as well.
113	*
114	* For example, the route is GET /books/?:
115	*
116	* <pre>
117	* $router->add('/books/?', [BooksController::class, 'view']);
118	* </pre>
119	*
120	* then the callable should look like
121	*
122	* <pre>
123	* class BooksController {
124	*   function view($id) {
125	*   }
126	* }
127	* </pre>
128	*/
129	public function add(string $route, callable|array $callable, string $method = 'GET'): void;
130
131	/**
132	* Returns with all the stored routes
133	*
134	* The result format will be ['HTTP method' => ['/route' => callable]]
135	*/
136	public function routes(): array;
137
138	public function prefixVariables(): array;
139	}