Skip to content
This repository
Browse code

Taking the time, while I read through the documentation again, to mak…

…e a few minor grammar adjustments and correcting the odd typo that slipped through as they always manage to do =) just as polish to an already amazing write up.


Awesome stuff thanx for all the hard work! You guys rock.
  • Loading branch information...
commit 9cc575abb9cf2a0d8e2013db148bbd2b2e5a4c3e 1 parent ea2eec8
Nick Lombard nickl- authored

Showing 1 changed file with 63 additions and 63 deletions. Show diff stats Hide diff stats

  1. +63 63 README.md
126 README.md
Source Rendered
@@ -25,7 +25,7 @@ Bootstrapping is easy. Just create an instance of Respect\Rest\Router.
25 25
26 26 $r3 = new Router;
27 27
28   -This assumes you have an `.htaccess` file that redirects every request to this PHP file and
  28 +This assumes you have a `.htaccess` file that redirects every request to this PHP file and
29 29 you're running this from the domain root (http://example.com/ without any subfolder).
30 30
31 31 If you want to use it from a subfolder, you can pass the virtual root to the Router:
@@ -34,12 +34,12 @@ If you want to use it from a subfolder, you can pass the virtual root to the Rou
34 34
35 35 This will instruct the router to work from http://example.com/myapp/.
36 36
37   -You can also use the Router without an `.htaccess` file. This uses the CGI `PATH_INFO` variable,
  37 +You can also use the Router without a `.htaccess` file. This uses the CGI `PATH_INFO` variable,
38 38 and can be declared as:
39 39
40 40 $r3 = new Router('/index.php/');
41 41
42   -Also using folders:
  42 +The same goes for folders:
43 43
44 44 $r3 = new Router('/myapp/index.php/');
45 45
@@ -48,7 +48,7 @@ This assumes that every URL in the project will begin with these namespaces.
48 48 ### Dispatching
49 49
50 50 The Router is auto-dispatched, which means that you don't have to call anything more than
51   -declaring routes to run it. If you want to ommit this behavior, you can set:
  51 +declaring routes to run it. If you want to omit this behavior, you can set:
52 52
53 53 $r3->autoDispatched = false;
54 54
@@ -61,14 +61,14 @@ test and integrate the Router into existing applications.
61 61
62 62 ### Simple Routing
63 63
64   -The Hello World route is something like this:
  64 +The Hello World route goes something like this:
65 65
66 66 $r3->get('/', function() {
67 67 return 'Hello World';
68 68 });
69 69
70 70 Hitting `http://localhost/` (consider your local configuration for this) will print
71   -"Hello World" on the browser. You can declare as many routes as you want:
  71 +"Hello World" in the browser. You can declare as many routes as you want:
72 72
73 73 $r3->get('/hello', function() {
74 74 return 'Hello from Path';
@@ -78,15 +78,15 @@ Hitting `http://localhost/hello` will now print "Hello from Path".
78 78
79 79 ### Using Parameters
80 80
81   -You can declare routes that receives parameters by the URL. For this, every parameter
  81 +You can declare routes that receives parameters from the URL. For this, every parameter
82 82 is a `/*` on the route path. Considering the previous sample model:
83 83
84 84 $r3->get('/users/*', function($screenName) {
85 85 echo "User {$screenName}";
86 86 });
87 87
88   -Accessing `http://localhost/users/alganet` with any username instead of `alganet` will
89   -now print "User alganet" (or any username you pass to it).
  88 +Accessing `http://localhost/users/alganet` or any other username besides `alganet` will
  89 +now print "User alganet" (or the username of your choosing).
90 90
91 91 Multiple parameters can be defined:
92 92
@@ -95,8 +95,8 @@ Multiple parameters can be defined:
95 95 });
96 96
97 97 Last parameters on the route path are optional by default, so declaring just
98   -a `->get('/posts/*'` will match for `http://localhost/posts/` without any
99   -parameter. You can declare a second `->get('/posts'`, then the Router will
  98 +a `->get('/posts/*'` will match `http://localhost/posts/` without any
  99 +parameter. You can declare a second `->get('/posts'`, now the Router will
100 100 match it properly, or treat the missing parameter yourself by making them
101 101 `null`able on the passed function:
102 102
@@ -128,25 +128,25 @@ Routes with catch-all parameters like this:
128 128
129 129 ### Route Matching
130 130
131   -Things now got more deeper. We got simple routes, routes with parameters, optional
  131 +Things can became very complex quick. We have simple routes, routes with parameters, optional
132 132 parameters and catch-all parameters. A simple rule to keep in mind is that Respect\Rest
133 133 matches the routes from the most specific to the most generic.
134 134
135   - * Routes with most slashes `/` are more specific and match first.
  135 + * Routes with the most slashes `/` are more specific and will be matched first.
136 136 * Routes with parameters are less specific than routes without parameters.
137   - * Routes with multiple parameters are even less specific.
138   - * Routes with catch-all parameters are the most generic ones.
  137 + * Routes with multiple parameters are even less specific than a route with one parameter.
  138 + * Routes with catch-all parameters are the least specific and will be matched last.
139 139
140   -Summing up: Slashes and asterisks places your route at the top to match first.
  140 +Summing up: Slashes and asterisks places your route at the top of the priority list to match first.
141 141
142   -Respect\Rest does this automatically, but is highly recommended to declare routes
  142 +Respect\Rest sort routes automatically, but it is highly recommended to declare routes
143 143 from the most specific to the most generic. This will improve performance and
144   -manutenibility of the code.
  144 +maintainability of the code.
145 145
146 146 ### Matching any HTTP Method
147 147
148   -Sometimes you need to use the router to proxy request to some other router or map
149   -requests to a class. Using the `any` magic method you can pass any method to the given
  148 +Sometimes you need to use a router to proxy requests to some other router or map
  149 +requests to a class. By using the magic method `any`, you can pass any HTTP method to a given
150 150 function.
151 151
152 152 $r3->any('/users/*', function($userName) {
@@ -158,7 +158,7 @@ function.
158 158
159 159 ### Class Controllers
160 160
161   -The `any` is highly useful to bind classes to controllers, one of the Respect\Rest most
  161 +The `any` method is extremely useful to bind classes to controllers, one of Respect\Rest's most
162 162 awesome features:
163 163
164 164 use Respect\Rest\Routable;
@@ -171,17 +171,16 @@ awesome features:
171 171
172 172 $r3->any('/article/*', 'MyArticle');
173 173
174   - 1. The above will bind the class methods to the HTTP methods using the same
175   - path.
176   - 2. Parameters will be sent to the class methods just like the callbacks on
177   - the other samples.
  174 + 1. This route will bind the class methods to the HTTP methods for the given path.
  175 + 2. Parameters will be sent to the class methods just like the callbacks from
  176 + the previous examples.
178 177 3. Controllers are lazy loaded and persistent. The *MyArticle* class will
179   - be instantiated only when a route matches one of his methods, and this
180   - instance will be reused on other requests (redirects, etc).
  178 + be instantiated only when a route matches one of its methods, and this
  179 + instance will be reused on subsequent callbacks (redirects, etc).
181 180 4. Classes must implement the interface Respect\Rest\Routable for safety reasons.
182 181 (Imagine someone mapping HTTP to a PDO class automatically, that wouldn't be right).
183 182
184   -Passing construtor arguments to the class is also possible:
  183 +Passing constructor arguments to the class is also possible:
185 184
186 185 $r3->any('/images/*', 'ImageController', array($myImageHandler, $myDb));
187 186
@@ -206,8 +205,8 @@ And you can even use a factory or DI container to build the controller class:
206 205
207 206 ### Routing Streams
208 207
209   -Sometimes you need to route users to streams. The Router doesn't need to handle
210   -large files or wait for streams to finish to begin serving them.
  208 +Sometimes you need to route users to streams. The Router doesn't have to first handle
  209 +large files or wait for streams to finish before serving them.
211 210
212 211 $r3->get('/images/*/hi-res', function($imageName) {
213 212 header('Content-type: image/jpg');
@@ -217,19 +216,19 @@ large files or wait for streams to finish to begin serving them.
217 216 This will redirect the file directly to the browser without keeping it in
218 217 memory.
219 218
220   -CAUTION: We did a very wrong thing in the sample: passing a parameter
221   -directly to a `fopen` handle. Please validate the parameter before using it. This
222   -is demonstrational only.
  219 +CAUTION: We created a possible security vulnerability in the sample: passing a parameter
  220 +directly to a `fopen` handle. Please validate user input parameters before using them.
  221 +This is for demonstrational purposes only.
223 222
224 223 ### Routing Static Values
225 224
226   -No secret here, you can make a route return a plain string:
  225 +No surprises here, you can make a route return a plain string:
227 226
228 227 $r3->get('/greetings', 'Hello!');
229 228
230 229 ### Forwarding Routes
231 230
232   -Respect\Rest has an internal forwarding mechanism. First you need to know that
  231 +Respect\Rest has an internal forwarding mechanism. First you'll need to understand that
233 232 every route declaration returns an instance:
234 233
235 234 $usersRoute = $r3->any('/users', 'UsersController');
@@ -242,7 +241,7 @@ Then you can `use` and `return` this route in another one:
242 241 }
243 242 });
244 243
245   -Illustrative sample above will redirect internally when an user is not premium to
  244 +Illustrative sample above will redirect internally when an user is not privileged to
246 245 another route that handle normal users.
247 246
248 247 ### When Routine (if)
@@ -260,13 +259,13 @@ Respect\Rest uses a different approach to validate route parameters:
260 259 condition (but does not need to appear in the same order).
261 260 3. You can specify more than one parameter per condition callback.
262 261 4. You can specify more than one callback: `when($cb1)->when($cb2)->when($etc)`
263   - 5. Conditions will also sync with parameters on binded classes and instances
  262 + 5. Conditions will also sync with parameters on binded classes and instance
264 263 methods.
265 264
266   -This makes possible to the user to validate parameters using any custom routine and
267   -not just data types as `int` or `string`.
  265 +This makes it possible for the user to validate parameters using any custom routine and
  266 +not just data types such as `int` or `string`.
268 267
269   -We highly recommend you to use a strong validation library when using this. Consider
  268 +We highly recommend that you use a strong validation library when using this. Consider
270 269 [Respect\Validation](http://github.com/Respect/Validation).
271 270
272 271 $r3->get('/images/*/hi-res', function($imageName) {
@@ -289,14 +288,14 @@ useful for logging, authentication and similar purposes.
289 288 $myLogger->logAlbumVisit($albumName);
290 289 });
291 290
292   - 1. This will execute the callback defined on *by* before the route action.
293   - The route needs to match.
294   - 2. Parameters are also synced by name, not order, like `when`.
  291 + 1. This will execute the callback defined with *by* before the route action
  292 + which needs to match a route.
  293 + 2. Parameters are also synced by name and not by order, like with `when`.
295 294 3. You can specify more than one parameter per proxy callback.
296 295 4. You can specify more than one proxy: `by($cb1)->by($cb2)->by($etc)`
297   - 5. A `return false` on a proxy will stop the execution of following proxies
298   - and the route action.
299   - 6. Proxies will also sync with parameters on binded classes and instances
  296 + 5. A `return false` from a proxy will stop the execution of any following proxies
  297 + as well as the route action.
  298 + 6. Proxies will also sync with parameters on binded classes and instance
300 299 methods.
301 300
302 301 If your By routine returns `false`, then the route method/function will not be
@@ -317,7 +316,7 @@ saving some new information.
317 316
318 317 1. `by` proxies will be executed before the route action, `through proxies`
319 318 will be executed after.
320   - 2. You don't need to use them both at the same time.
  319 + 2. You are free to use them separately or in tandem.
321 320 3. `through` can also receive parameters by name.
322 321
323 322 Sample above allows you to do something based on the route parameters, but when
@@ -338,7 +337,7 @@ outputing the result.
338 337
339 338 ### Controller Splitting
340 339
341   -Using routines is encouraged to separate the controller logic into components. You can
  340 +When using routines you are encouraged to separate the controller logic into components. You can
342 341 reuse them:
343 342
344 343 $logRoutine = function() use ($myLogger, $r3) {
@@ -352,7 +351,7 @@ A simple way of applying routines to every route on the router is:
352 351
353 352 $r3->always('By', $logRoutine);
354 353
355   -You can use the param sync to get advantage of this:
  354 +You can use the param sync to take advantage of this:
356 355
357 356 $r3->always('When', function($user=null) {
358 357 if ($user) {
@@ -370,7 +369,7 @@ verify them all automatically by its name.
370 369
371 370 ### Content Negotiation
372 371
373   -Respect currently supports the four distinct types of content-negotiation:
  372 +Respect/Rest currently supports the four distinct types of Accept header content-negotiation:
374 373 Mimetype, Encoding, Language and Charset. Usage sample:
375 374
376 375 $r3->get('/about', function() {
@@ -386,13 +385,13 @@ Mimetype, Encoding, Language and Charset. Usage sample:
386 385 'application/json' => 'json_encode'
387 386 ));
388 387
389   -As in every routine, conneg routines are executed in the same order that
  388 +As in every routine, conneg routines are executed in the same order in which
390 389 you appended them to the route. You can also use `->always` to apply this
391 390 routine to every route on the Router.
392 391
393 392 Please note that when returning streams, conneg routines are also called.
394   -You can take advantage of this processing streams. The hardcore sample
395   -below serves a text using the deflate encoding directly to the browser:
  393 +You may take advantage of this when processing streams. The hardcore example
  394 +below serves text, using the deflate encoding, directly to the browser:
396 395
397 396 $r3->get('/text/*', function($filename) {
398 397 return fopen('data/'.$filename, 'r+');
@@ -419,7 +418,7 @@ to return true or false. True means that the user could be authenticated.
419 418
420 419 Respect\Rest will handle the authentication flow, sending the appropriate
421 420 headers when unauthenticated. You can also return another route, which will
422   -act as a internal forward (see the section about this above).
  421 +act as an internal forward (see the section on forwarding above).
423 422
424 423 ### Filtering Browsers
425 424
@@ -432,10 +431,10 @@ Below is an illustrative sample of how to block requests from mobile devices:
432 431 }
433 432 ));
434 433
435   -You can pass several itens on the array, like any conneg routine. The array
  434 +You can pass several items in the array, like any conneg routine. The array
436 435 key is a regular expression matcher without delimiters.
437 436
438   -### Input Content-Type
  437 +### Input Content-Type (input data)
439 438
440 439 Note that this is not currently implemented.
441 440
@@ -460,13 +459,13 @@ this data before doing anything:
460 459
461 460 ### HTTP Errors
462 461
463   -Respect\Rest currently implement these errors by default:
  462 +Respect\Rest currently handle the following errors by default:
464 463
465   - * 404, when no matching route path is found.
  464 + * 404, when no matching route paths are found.
466 465 * 401, when the client sends an unauthenticated request to a route using `authBasic` routine.
467   - * 405, when a matching path is found but the method don't.
  466 + * 405, when a matching path is found but the method isn't specified.
468 467 * 400, when a `when` validation fails.
469   - * 406, when the route path and method matches but content-negotiation don't.
  468 + * 406, when the route path and method matches but content-negotiation doesn't.
470 469
471 470 ### RESTful Extras
472 471
@@ -487,8 +486,9 @@ own routines by instance using:
487 486
488 487 $r3->get('/greetings', 'Hello World')->appendRoutine(new MyRoutine);
489 488
490   -In the sample above, `MyRoutine` is a provided user routine declared as a class and
491   -appended to the router. Custom routines have several different interfaces that can be implemented:
  489 +In the sample above, `MyRoutine` is a user provided routine declared as a class and
  490 +appended to the router. Custom routines have the option of several different interfaces
  491 +which can be implemented:
492 492
493 493 * IgnorableFileExtension - Instructs the router to ignore the file extension in requests
494 494 * ParamSynced - Syncs parameters with the route function/method.
@@ -498,5 +498,5 @@ appended to the router. Custom routines have several different interfaces that c
498 498 * Unique - Makes this routine be replaced, not appended, if more than one is declared for
499 499 the same type.
500 500
501   -You can use any combination of the above, and you also need to implement Routinable.
  501 +You can use any combination of the above but also need to implement the Routinable interface.
502 502

0 comments on commit 9cc575a

Please sign in to comment.
Something went wrong with that request. Please try again.