ci4

1
<?php
2

3
declare(strict_types=1);
4

5
/**
6
 * This file is part of CodeIgniter 4 framework.
7
 *
8
 * (c) CodeIgniter Foundation <admin@codeigniter.com>
9
 *
10
 * For the full copyright and license information, please view
11
 * the LICENSE file that was distributed with this source code.
12
 */
13

14
namespace CodeIgniter\Router;
15

16
use Closure;
17
use CodeIgniter\HTTP\ResponseInterface;
18

19
/**
20
 * Interface RouteCollectionInterface
21
 *
22
 * A Route Collection's sole job is to hold a series of routes. The required
23
 * number of methods is kept very small on purpose, but implementors may
24
 * add a number of additional methods to customize how the routes are defined.
25
 *
26
 * The RouteCollection provides the Router with the routes so that it can determine
27
 * which controller should be run.
28
 */
29
interface RouteCollectionInterface
30
{
31
    /**
32
     * Adds a single route to the collection.
33
     *
34
     * @param string                                                            $from    The route path (with placeholders or regex)
35
     * @param array|(Closure(mixed...): (ResponseInterface|string|void))|string $to      The route handler
36
     * @param array|null                                                        $options The route options
37
     *
38
     * @return RouteCollectionInterface
39
     */
40
    public function add(string $from, $to, ?array $options = null);
41

42
    /**
43
     * Registers a new constraint with the system. Constraints are used
44
     * by the routes as placeholders for regular expressions to make defining
45
     * the routes more human-friendly.
46
     *
47
     * You can pass an associative array as $placeholder, and have
48
     * multiple placeholders added at once.
49
     *
50
     * @param array|string $placeholder
51
     * @param string|null  $pattern     The regex pattern
52
     *
53
     * @return RouteCollectionInterface
54
     */
55
    public function addPlaceholder($placeholder, ?string $pattern = null);
56

57
    /**
58
     * Sets the default namespace to use for Controllers when no other
59
     * namespace has been specified.
60
     *
61
     * @return RouteCollectionInterface
62
     */
63
    public function setDefaultNamespace(string $value);
64

65
    /**
66
     * Sets the default controller to use when no other controller has been
67
     * specified.
68
     *
69
     * @return RouteCollectionInterface
70
     */
71
    public function setDefaultController(string $value);
72

73
    /**
74
     * Sets the default method to call on the controller when no other
75
     * method has been set in the route.
76
     *
77
     * @return RouteCollectionInterface
78
     */
79
    public function setDefaultMethod(string $value);
80

81
    /**
82
     * Tells the system whether to convert dashes in URI strings into
83
     * underscores. In some search engines, including Google, dashes
84
     * create more meaning and make it easier for the search engine to
85
     * find words and meaning in the URI for better SEO. But it
86
     * doesn't work well with PHP method names....
87
     *
88
     * @return RouteCollectionInterface
89
     */
90
    public function setTranslateURIDashes(bool $value);
91

92
    /**
93
     * If TRUE, the system will attempt to match the URI against
94
     * Controllers by matching each segment against folders/files
95
     * in APPPATH/Controllers, when a match wasn't found against
96
     * defined routes.
97
     *
98
     * If FALSE, will stop searching and do NO automatic routing.
99
     */
100
    public function setAutoRoute(bool $value): self;
101

102
    /**
103
     * Sets the class/method that should be called if routing doesn't
104
     * find a match. It can be either a closure or the controller/method
105
     * name exactly like a route is defined: Users::index
106
     *
107
     * This setting is passed to the Router class and handled there.
108
     *
109
     * @param callable|null $callable
110
     */
111
    public function set404Override($callable = null): self;
112

113
    /**
114
     * Returns the 404 Override setting, which can be null, a closure
115
     * or the controller/string.
116
     *
117
     * @return (Closure(string): (ResponseInterface|string|void))|string|null
118
     */
119
    public function get404Override();
120

121
    /**
122
     * Returns the name of the default controller. With Namespace.
123
     *
124
     * @return string
125
     */
126
    public function getDefaultController();
127

128
    /**
129
     * Returns the name of the default method to use within the controller.
130
     *
131
     * @return string
132
     */
133
    public function getDefaultMethod();
134

135
    /**
136
     * Returns the current value of the translateURIDashes setting.
137
     *
138
     * @return bool
139
     */
140
    public function shouldTranslateURIDashes();
141

142
    /**
143
     * Returns the flag that tells whether to autoRoute URI against Controllers.
144
     *
145
     * @return bool
146
     */
147
    public function shouldAutoRoute();
148

149
    /**
150
     * Returns the raw array of available routes.
151
     *
152
     * @return array
153
     */
154
    public function getRoutes();
155

156
    /**
157
     * Returns the current HTTP Verb being used.
158
     *
159
     * @return string
160
     */
161
    public function getHTTPVerb();
162

163
    /**
164
     * Attempts to look up a route based on its destination.
165
     *
166
     * If a route exists:
167
     *
168
     *      'path/(:any)/(:any)' => 'Controller::method/$1/$2'
169
     *
170
     * This method allows you to know the Controller and method
171
     * and get the route that leads to it.
172
     *
173
     *      // Equals 'path/$param1/$param2'
174
     *      reverseRoute('Controller::method', $param1, $param2);
175
     *
176
     * @param string     $search    Named route or Controller::method
177
     * @param int|string ...$params
178
     *
179
     * @return false|string The route (URI path relative to baseURL) or false if not found.
180
     */
181
    public function reverseRoute(string $search, ...$params);
182

183
    /**
184
     * Determines if the route is a redirecting route.
185
     */
186
    public function isRedirect(string $routeKey): bool;
187

188
    /**
189
     * Grabs the HTTP status code from a redirecting Route.
190
     */
191
    public function getRedirectCode(string $routeKey): int;
192

193
    /**
194
     * Get the flag that limit or not the routes with {locale} placeholder to App::$supportedLocales
195
     */
196
    public function shouldUseSupportedLocalesOnly(): bool;
197
}
198