?  search:
summary | log | graphiclog1 | graphiclog2 | commit | commitdiff | tree | refs | edit | fork
blame | history | raw | HEAD
Always parse query string, on the main request or on sub-requests
[kohana-core.git] / classes / Kohana / Request.php
blob6cd8cc59fa5906295c276fc7bd939f4d1e0d2cc1
1 <?php defined('SYSPATH') OR die('No direct script access.');
2 /**
3 * Request. Uses the [Route] class to determine what
4 * [Controller] to send the request to.
5 *
6 * @package Kohana
7 * @category Base
8 * @author Kohana Team
9 * @copyright (c) 2008-2012 Kohana Team
10 * @license http://kohanaframework.org/license
11 */
12 class Kohana_Request implements HTTP_Request {
13
14 /**
15 * @var string client user agent
16 */
17 public static $user_agent = '';
18
19 /**
20 * @var string client IP address
21 */
22 public static $client_ip = '0.0.0.0';
23
24 /**
25 * @var string trusted proxy server IPs
26 */
27 public static $trusted_proxies = array('127.0.0.1', 'localhost', 'localhost.localdomain');
28
29 /**
30 * @var Request main request instance
31 */
32 public static $initial;
33
34 /**
35 * @var Request currently executing request instance
36 */
37 public static $current;
38
39 /**
40 * Creates a new request object for the given URI. New requests should be
41 * Created using the [Request::factory] method.
42 *
43 * $request = Request::factory($uri);
44 *
45 * If $cache parameter is set, the response for the request will attempt to
46 * be retrieved from the cache.
47 *
48 * @param string $uri URI of the request
49 * @param array $client_params An array of params to pass to the request client
50 * @param bool $allow_external Allow external requests? (deprecated in 3.3)
51 * @param array $injected_routes An array of routes to use, for testing
52 * @return void|Request
53 * @throws Request_Exception
54 * @uses Route::all
55 * @uses Route::matches
56 */
57 public static function factory($uri = TRUE, $client_params = array(), $allow_external = TRUE, $injected_routes = array())
58 {
59 // If this is the initial request
60 if ( ! Request::$initial)
61 {
62 $protocol = HTTP::$protocol;
63
64 if (isset($_SERVER['REQUEST_METHOD']))
65 {
66 // Use the server request method
67 $method = $_SERVER['REQUEST_METHOD'];
68 }
69 else
70 {
71 // Default to GET requests
72 $method = HTTP_Request::GET;
73 }
74
75 if (( ! empty($_SERVER['HTTPS']) AND filter_var($_SERVER['HTTPS'], FILTER_VALIDATE_BOOLEAN))
76 OR (isset($_SERVER['HTTP_X_FORWARDED_PROTO'])
77 AND $_SERVER['HTTP_X_FORWARDED_PROTO'] === 'https')
78 AND in_array($_SERVER['REMOTE_ADDR'], Request::$trusted_proxies))
79 {
80 // This request is secure
81 $secure = TRUE;
82 }
83
84 if (isset($_SERVER['HTTP_REFERER']))
85 {
86 // There is a referrer for this request
87 $referrer = $_SERVER['HTTP_REFERER'];
88 }
89
90 if (isset($_SERVER['HTTP_USER_AGENT']))
91 {
92 // Browser type
93 Request::$user_agent = $_SERVER['HTTP_USER_AGENT'];
94 }
95
96 if (isset($_SERVER['HTTP_X_REQUESTED_WITH']))
97 {
98 // Typically used to denote AJAX requests
99 $requested_with = $_SERVER['HTTP_X_REQUESTED_WITH'];
100 }
101
102 if (isset($_SERVER['HTTP_X_FORWARDED_FOR'])
103 AND isset($_SERVER['REMOTE_ADDR'])
104 AND in_array($_SERVER['REMOTE_ADDR'], Request::$trusted_proxies))
105 {
106 // Use the forwarded IP address, typically set when the
107 // client is using a proxy server.
108 // Format: "X-Forwarded-For: client1, proxy1, proxy2"
109 $client_ips = explode(',', $_SERVER['HTTP_X_FORWARDED_FOR']);
110
111 Request::$client_ip = array_shift($client_ips);
112
113 unset($client_ips);
114 }
115 elseif (isset($_SERVER['HTTP_CLIENT_IP'])
116 AND isset($_SERVER['REMOTE_ADDR'])
117 AND in_array($_SERVER['REMOTE_ADDR'], Request::$trusted_proxies))
118 {
119 // Use the forwarded IP address, typically set when the
120 // client is using a proxy server.
121 $client_ips = explode(',', $_SERVER['HTTP_CLIENT_IP']);
122
123 Request::$client_ip = array_shift($client_ips);
124
125 unset($client_ips);
126 }
127 elseif (isset($_SERVER['REMOTE_ADDR']))
128 {
129 // The remote IP address
130 Request::$client_ip = $_SERVER['REMOTE_ADDR'];
131 }
132
133 if ($method !== HTTP_Request::GET)
134 {
135 // Ensure the raw body is saved for future use
136 $body = file_get_contents('php://input');
137 }
138
139 if ($uri === TRUE)
140 {
141 // Attempt to guess the proper URI
142 $uri = Request::detect_uri();
143 }
144
145 $cookies = array();
146
147 if (($cookie_keys = array_keys($_COOKIE)))
148 {
149 foreach ($cookie_keys as $key)
150 {
151 $cookies[$key] = Cookie::get($key);
152 }
153 }
154
155 // Create the instance singleton
156 Request::$initial = $request = new Request($uri, $client_params, $allow_external, $injected_routes);
157
158 // Store global GET and POST data in the initial request only
159 $request->protocol($protocol)
160 ->query($_GET)
161 ->post($_POST);
162
163 if (isset($secure))
164 {
165 // Set the request security
166 $request->secure($secure);
167 }
168
169 if (isset($method))
170 {
171 // Set the request method
172 $request->method($method);
173 }
174
175 if (isset($referrer))
176 {
177 // Set the referrer
178 $request->referrer($referrer);
179 }
180
181 if (isset($requested_with))
182 {
183 // Apply the requested with variable
184 $request->requested_with($requested_with);
185 }
186
187 if (isset($body))
188 {
189 // Set the request body (probably a PUT type)
190 $request->body($body);
191 }
192
193 if (isset($cookies))
194 {
195 $request->cookie($cookies);
196 }
197 }
198 else
199 {
200 $request = new Request($uri, $client_params, $allow_external, $injected_routes);
201 }
202
203 return $request;
204 }
205
206 /**
207 * Automatically detects the URI of the main request using PATH_INFO,
208 * REQUEST_URI, PHP_SELF or REDIRECT_URL.
209 *
210 * $uri = Request::detect_uri();
211 *
212 * @return string URI of the main request
213 * @throws Kohana_Exception
214 * @since 3.0.8
215 */
216 public static function detect_uri()
217 {
218 if ( ! empty($_SERVER['PATH_INFO']))
219 {
220 // PATH_INFO does not contain the docroot or index
221 $uri = $_SERVER['PATH_INFO'];
222 }
223 else
224 {
225 // REQUEST_URI and PHP_SELF include the docroot and index
226
227 if (isset($_SERVER['REQUEST_URI']))
228 {
229 /**
230 * We use REQUEST_URI as the fallback value. The reason
231 * for this is we might have a malformed URL such as:
232 *
233 * http://localhost/http://example.com/judge.php
234 *
235 * which parse_url can't handle. So rather than leave empty
236 * handed, we'll use this.
237 */
238 $uri = $_SERVER['REQUEST_URI'];
239
240 if ($request_uri = parse_url($_SERVER['REQUEST_URI'], PHP_URL_PATH))
241 {
242 // Valid URL path found, set it.
243 $uri = $request_uri;
244 }
245
246 // Decode the request URI
247 $uri = rawurldecode($uri);
248 }
249 elseif (isset($_SERVER['PHP_SELF']))
250 {
251 $uri = $_SERVER['PHP_SELF'];
252 }
253 elseif (isset($_SERVER['REDIRECT_URL']))
254 {
255 $uri = $_SERVER['REDIRECT_URL'];
256 }
257 else
258 {
259 // If you ever see this error, please report an issue at http://dev.kohanaphp.com/projects/kohana3/issues
260 // along with any relevant information about your web server setup. Thanks!
261 throw new Kohana_Exception('Unable to detect the URI using PATH_INFO, REQUEST_URI, PHP_SELF or REDIRECT_URL');
262 }
263
264 // Get the path from the base URL, including the index file
265 $base_url = parse_url(Kohana::$base_url, PHP_URL_PATH);
266
267 if (strpos($uri, $base_url) === 0)
268 {
269 // Remove the base URL from the URI
270 $uri = (string) substr($uri, strlen($base_url));
271 }
272
273 if (Kohana::$index_file AND strpos($uri, Kohana::$index_file) === 0)
274 {
275 // Remove the index file from the URI
276 $uri = (string) substr($uri, strlen(Kohana::$index_file));
277 }
278 }
279
280 return $uri;
281 }
282
283 /**
284 * Return the currently executing request. This is changed to the current
285 * request when [Request::execute] is called and restored when the request
286 * is completed.
287 *
288 * $request = Request::current();
289 *
290 * @return Request
291 * @since 3.0.5
292 */
293 public static function current()
294 {
295 return Request::$current;
296 }
297
298 /**
299 * Returns the first request encountered by this framework. This will should
300 * only be set once during the first [Request::factory] invocation.
301 *
302 * // Get the first request
303 * $request = Request::initial();
304 *
305 * // Test whether the current request is the first request
306 * if (Request::initial() === Request::current())
307 * // Do something useful
308 *
309 * @return Request
310 * @since 3.1.0
311 */
312 public static function initial()
313 {
314 return Request::$initial;
315 }
316
317 /**
318 * Returns information about the initial user agent.
319 *
320 * @param mixed $value array or string to return: browser, version, robot, mobile, platform
321 * @return mixed requested information, FALSE if nothing is found
322 * @uses Request::$user_agent
323 * @uses Text::user_agent
324 */
325 public static function user_agent($value)
326 {
327 return Text::user_agent(Request::$user_agent, $value);
328 }
329
330 /**
331 * Returns the accepted content types. If a specific type is defined,
332 * the quality of that type will be returned.
333 *
334 * $types = Request::accept_type();
335 *
336 * [!!] Deprecated in favor of using [HTTP_Header::accepts_at_quality].
337 *
338 * @deprecated since version 3.3.0
339 * @param string $type Content MIME type
340 * @return mixed An array of all types or a specific type as a string
341 * @uses Request::_parse_accept
342 */
343 public static function accept_type($type = NULL)
344 {
345 static $accepts;
346
347 if ($accepts === NULL)
348 {
349 // Parse the HTTP_ACCEPT header
350 $accepts = Request::_parse_accept($_SERVER['HTTP_ACCEPT'], array('*/*' => 1.0));
351 }
352
353 if (isset($type))
354 {
355 // Return the quality setting for this type
356 return isset($accepts[$type]) ? $accepts[$type] : $accepts['*/*'];
357 }
358
359 return $accepts;
360 }
361
362 /**
363 * Returns the accepted languages. If a specific language is defined,
364 * the quality of that language will be returned. If the language is not
365 * accepted, FALSE will be returned.
366 *
367 * $langs = Request::accept_lang();
368 *
369 * [!!] Deprecated in favor of using [HTTP_Header::accepts_language_at_quality].
370 *
371 * @deprecated since version 3.3.0
372 * @param string $lang Language code
373 * @return mixed An array of all types or a specific type as a string
374 * @uses Request::_parse_accept
375 */
376 public static function accept_lang($lang = NULL)
377 {
378 static $accepts;
379
380 if ($accepts === NULL)
381 {
382 // Parse the HTTP_ACCEPT_LANGUAGE header
383 $accepts = Request::_parse_accept($_SERVER['HTTP_ACCEPT_LANGUAGE']);
384 }
385
386 if (isset($lang))
387 {
388 // Return the quality setting for this lang
389 return isset($accepts[$lang]) ? $accepts[$lang] : FALSE;
390 }
391
392 return $accepts;
393 }
394
395 /**
396 * Returns the accepted encodings. If a specific encoding is defined,
397 * the quality of that encoding will be returned. If the encoding is not
398 * accepted, FALSE will be returned.
399 *
400 * $encodings = Request::accept_encoding();
401 *
402 * [!!] Deprecated in favor of using [HTTP_Header::accepts_encoding_at_quality].
403 *
404 * @deprecated since version 3.3.0
405 * @param string $type Encoding type
406 * @return mixed An array of all types or a specific type as a string
407 * @uses Request::_parse_accept
408 */
409 public static function accept_encoding($type = NULL)
410 {
411 static $accepts;
412
413 if ($accepts === NULL)
414 {
415 // Parse the HTTP_ACCEPT_LANGUAGE header
416 $accepts = Request::_parse_accept($_SERVER['HTTP_ACCEPT_ENCODING']);
417 }
418
419 if (isset($type))
420 {
421 // Return the quality setting for this type
422 return isset($accepts[$type]) ? $accepts[$type] : FALSE;
423 }
424
425 return $accepts;
426 }
427
428 /**
429 * Determines if a file larger than the post_max_size has been uploaded. PHP
430 * does not handle this situation gracefully on its own, so this method
431 * helps to solve that problem.
432 *
433 * @return boolean
434 * @uses Num::bytes
435 * @uses Arr::get
436 */
437 public static function post_max_size_exceeded()
438 {
439 // Make sure the request method is POST
440 if (Request::$initial->method() !== HTTP_Request::POST)
441 return FALSE;
442
443 // Get the post_max_size in bytes
444 $max_bytes = Num::bytes(ini_get('post_max_size'));
445
446 // Error occurred if method is POST, and content length is too long
447 return (Arr::get($_SERVER, 'CONTENT_LENGTH') > $max_bytes);
448 }
449
450 /**
451 * Process a request to find a matching route
452 *
453 * @param object $request Request
454 * @param array $routes Route
455 * @return array
456 */
457 public static function process(Request $request, $routes = NULL)
458 {
459 // Load routes
460 $routes = (empty($routes)) ? Route::all() : $routes;
461 $params = NULL;
462
463 foreach ($routes as $name => $route)
464 {
465 // Use external routes for reverse routing only
466 if ($route->is_external())
467 {
468 continue;
469 }
470
471 // We found something suitable
472 if ($params = $route->matches($request))
473 {
474 return array(
475 'params' => $params,
476 'route' => $route,
477 );
478 }
479 }
480
481 return NULL;
482 }
483
484 /**
485 * Parses an accept header and returns an array (type => quality) of the
486 * accepted types, ordered by quality.
487 *
488 * $accept = Request::_parse_accept($header, $defaults);
489 *
490 * @param string $header Header to parse
491 * @param array $accepts Default values
492 * @return array
493 */
494 protected static function _parse_accept( & $header, array $accepts = NULL)
495 {
496 if ( ! empty($header))
497 {
498 // Get all of the types
499 $types = explode(',', $header);
500
501 foreach ($types as $type)
502 {
503 // Split the type into parts
504 $parts = explode(';', $type);
505
506 // Make the type only the MIME
507 $type = trim(array_shift($parts));
508
509 // Default quality is 1.0
510 $quality = 1.0;
511
512 foreach ($parts as $part)
513 {
514 // Prevent undefined $value notice below
515 if (strpos($part, '=') === FALSE)
516 continue;
517
518 // Separate the key and value
519 list ($key, $value) = explode('=', trim($part));
520
521 if ($key === 'q')
522 {
523 // There is a quality for this type
524 $quality = (float) trim($value);
525 }
526 }
527
528 // Add the accept type and quality
529 $accepts[$type] = $quality;
530 }
531 }
532
533 // Make sure that accepts is an array
534 $accepts = (array) $accepts;
535
536 // Order by quality
537 arsort($accepts);
538
539 return $accepts;
540 }
541
542 /**
543 * @var string the x-requested-with header which most likely
544 * will be xmlhttprequest
545 */
546 protected $_requested_with;
547
548 /**
549 * @var string method: GET, POST, PUT, DELETE, HEAD, etc
550 */
551 protected $_method = 'GET';
552
553 /**
554 * @var string protocol: HTTP/1.1, FTP, CLI, etc
555 */
556 protected $_protocol;
557
558 /**
559 * @var boolean
560 */
561 protected $_secure = FALSE;
562
563 /**
564 * @var string referring URL
565 */
566 protected $_referrer;
567
568 /**
569 * @var Route route matched for this request
570 */
571 protected $_route;
572
573 /**
574 * @var Route array of routes to manually look at instead of the global namespace
575 */
576 protected $_routes;
577
578 /**
579 * @var Kohana_HTTP_Header headers to sent as part of the request
580 */
581 protected $_header;
582
583 /**
584 * @var string the body
585 */
586 protected $_body;
587
588 /**
589 * @var string controller directory
590 */
591 protected $_directory = '';
592
593 /**
594 * @var string controller to be executed
595 */
596 protected $_controller;
597
598 /**
599 * @var string action to be executed in the controller
600 */
601 protected $_action;
602
603 /**
604 * @var string the URI of the request
605 */
606 protected $_uri;
607
608 /**
609 * @var boolean external request
610 */
611 protected $_external = FALSE;
612
613 /**
614 * @var array parameters from the route
615 */
616 protected $_params = array();
617
618 /**
619 * @var array query parameters
620 */
621 protected $_get = array();
622
623 /**
624 * @var array post parameters
625 */
626 protected $_post = array();
627
628 /**
629 * @var array cookies to send with the request
630 */
631 protected $_cookies = array();
632
633 /**
634 * @var Kohana_Request_Client
635 */
636 protected $_client;
637
638 /**
639 * Creates a new request object for the given URI. New requests should be
640 * Created using the [Request::factory] method.
641 *
642 * $request = new Request($uri);
643 *
644 * If $cache parameter is set, the response for the request will attempt to
645 * be retrieved from the cache.
646 *
647 * @param string $uri URI of the request
648 * @param array $client_params Array of params to pass to the request client
649 * @param bool $allow_external Allow external requests? (deprecated in 3.3)
650 * @param array $injected_routes An array of routes to use, for testing
651 * @return void
652 * @throws Request_Exception
653 * @uses Route::all
654 * @uses Route::matches
655 */
656 public function __construct($uri, $client_params = array(), $allow_external = TRUE, $injected_routes = array())
657 {
658 $client_params = is_array($client_params) ? $client_params : array();
659
660 // Initialise the header
661 $this->_header = new HTTP_Header(array());
662
663 // Assign injected routes
664 $this->_routes = $injected_routes;
665
666 // Cleanse query parameters from URI (faster that parse_url())
667 $split_uri = explode('?', $uri);
668 $uri = array_shift($split_uri);
669
670 if ($split_uri)
671 {
672 parse_str($split_uri[0], $this->_get);
673 }
674
675 // Detect protocol (if present)
676 // $allow_external = FALSE prevents the default index.php from
677 // being able to proxy external pages.
678 if ( ! $allow_external OR strpos($uri, '://') === FALSE)
679 {
680 // Remove leading and trailing slashes from the URI
681 $this->_uri = trim($uri, '/');
682
683 // Apply the client
684 $this->_client = new Request_Client_Internal($client_params);
685 }
686 else
687 {
688 // Create a route
689 $this->_route = new Route($uri);
690
691 // Store the URI
692 $this->_uri = $uri;
693
694 // Set the security setting if required
695 if (strpos($uri, 'https://') === 0)
696 {
697 $this->secure(TRUE);
698 }
699
700 // Set external state
701 $this->_external = TRUE;
702
703 // Setup the client
704 $this->_client = Request_Client_External::factory($client_params);
705 }
706 }
707
708 /**
709 * Returns the response as the string representation of a request.
710 *
711 * echo $request;
712 *
713 * @return string
714 */
715 public function __toString()
716 {
717 return $this->render();
718 }
719
720 /**
721 * Sets and gets the uri from the request.
722 *
723 * @param string $uri
724 * @return mixed
725 */
726 public function uri($uri = NULL)
727 {
728 if ($uri === NULL)
729 {
730 // Act as a getter
731 return ($this->_uri === '') ? '/' : $this->_uri;
732 }
733
734 // Act as a setter
735 $this->_uri = $uri;
736
737 return $this;
738 }
739
740 /**
741 * Create a URL string from the current request. This is a shortcut for:
742 *
743 * echo URL::site($this->request->uri(), $protocol);
744 *
745 * @param mixed $protocol protocol string or Request object
746 * @return string
747 * @since 3.0.7
748 * @uses URL::site
749 */
750 public function url($protocol = NULL)
751 {
752 if ($this->is_external())
753 {
754 // If it's an external request return the URI
755 return $this->uri();
756 }
757
758 // Create a URI with the current route, convert to a URL and returns
759 return URL::site($this->uri(), $protocol);
760 }
761
762 /**
763 * Retrieves a value from the route parameters.
764 *
765 * $id = $request->param('id');
766 *
767 * @param string $key Key of the value
768 * @param mixed $default Default value if the key is not set
769 * @return mixed
770 */
771 public function param($key = NULL, $default = NULL)
772 {
773 if ($key === NULL)
774 {
775 // Return the full array
776 return $this->_params;
777 }
778
779 return isset($this->_params[$key]) ? $this->_params[$key] : $default;
780 }
781
782 /**
783 * Sets and gets the referrer from the request.
784 *
785 * @param string $referrer
786 * @return mixed
787 */
788 public function referrer($referrer = NULL)
789 {
790 if ($referrer === NULL)
791 {
792 // Act as a getter
793 return $this->_referrer;
794 }
795
796 // Act as a setter
797 $this->_referrer = (string) $referrer;
798
799 return $this;
800 }
801
802 /**
803 * Sets and gets the route from the request.
804 *
805 * @param string $route
806 * @return mixed
807 */
808 public function route(Route $route = NULL)
809 {
810 if ($route === NULL)
811 {
812 // Act as a getter
813 return $this->_route;
814 }
815
816 // Act as a setter
817 $this->_route = $route;
818
819 return $this;
820 }
821
822 /**
823 * Sets and gets the directory for the controller.
824 *
825 * @param string $directory Directory to execute the controller from
826 * @return mixed
827 */
828 public function directory($directory = NULL)
829 {
830 if ($directory === NULL)
831 {
832 // Act as a getter
833 return $this->_directory;
834 }
835
836 // Act as a setter
837 $this->_directory = (string) $directory;
838
839 return $this;
840 }
841
842 /**
843 * Sets and gets the controller for the matched route.
844 *
845 * @param string $controller Controller to execute the action
846 * @return mixed
847 */
848 public function controller($controller = NULL)
849 {
850 if ($controller === NULL)
851 {
852 // Act as a getter
853 return $this->_controller;
854 }
855
856 // Act as a setter
857 $this->_controller = (string) $controller;
858
859 return $this;
860 }
861
862 /**
863 * Sets and gets the action for the controller.
864 *
865 * @param string $action Action to execute the controller from
866 * @return mixed
867 */
868 public function action($action = NULL)
869 {
870 if ($action === NULL)
871 {
872 // Act as a getter
873 return $this->_action;
874 }
875
876 // Act as a setter
877 $this->_action = (string) $action;
878
879 return $this;
880 }
881
882 /**
883 * Provides access to the [Request_Client].
884 *
885 * @return Request_Client
886 * @return self
887 */
888 public function client(Request_Client $client = NULL)
889 {
890 if ($client === NULL)
891 return $this->_client;
892 else
893 {
894 $this->_client = $client;
895 return $this;
896 }
897 }
898
899 /**
900 * Gets and sets the requested with property, which should
901 * be relative to the x-requested-with pseudo header.
902 *
903 * @param string $requested_with Requested with value
904 * @return mixed
905 */
906 public function requested_with($requested_with = NULL)
907 {
908 if ($requested_with === NULL)
909 {
910 // Act as a getter
911 return $this->_requested_with;
912 }
913
914 // Act as a setter
915 $this->_requested_with = strtolower($requested_with);
916
917 return $this;
918 }
919
920 /**
921 * Processes the request, executing the controller action that handles this
922 * request, determined by the [Route].
923 *
924 * 1. Before the controller action is called, the [Controller::before] method
925 * will be called.
926 * 2. Next the controller action will be called.
927 * 3. After the controller action is called, the [Controller::after] method
928 * will be called.
929 *
930 * By default, the output from the controller is captured and returned, and
931 * no headers are sent.
932 *
933 * $request->execute();
934 *
935 * @return Response
936 * @throws Request_Exception
937 * @throws HTTP_Exception_404
938 * @uses [Kohana::$profiling]
939 * @uses [Profiler]
940 */
941 public function execute()
942 {
943 if ( ! $this->_external)
944 {
945 $processed = Request::process($this, $this->_routes);
946
947 if ($processed)
948 {
949 // Store the matching route
950 $this->_route = $processed['route'];
951 $params = $processed['params'];
952
953 // Is this route external?
954 $this->_external = $this->_route->is_external();
955
956 if (isset($params['directory']))
957 {
958 // Controllers are in a sub-directory
959 $this->_directory = $params['directory'];
960 }
961
962 // Store the controller
963 $this->_controller = $params['controller'];
964
965 // Store the action
966 $this->_action = (isset($params['action']))
967 ? $params['action']
968 : Route::$default_action;
969
970 // These are accessible as public vars and can be overloaded
971 unset($params['controller'], $params['action'], $params['directory']);
972
973 // Params cannot be changed once matched
974 $this->_params = $params;
975 }
976 }
977
978 if ( ! $this->_route instanceof Route)
979 {
980 return HTTP_Exception::factory(404, 'Unable to find a route to match the URI: :uri', array(
981 ':uri' => $this->_uri,
982 ))->request($this)
983 ->get_response();
984 }
985
986 if ( ! $this->_client instanceof Request_Client)
987 {
988 throw new Request_Exception('Unable to execute :uri without a Kohana_Request_Client', array(
989 ':uri' => $this->_uri,
990 ));
991 }
992
993 return $this->_client->execute($this);
994 }
995
996 /**
997 * Returns whether this request is the initial request Kohana received.
998 * Can be used to test for sub requests.
999 *
1000 * if ( ! $request->is_initial())
1001 * // This is a sub request
1002 *
1003 * @return boolean
1004 */
1005 public function is_initial()
1006 {
1007 return ($this === Request::$initial);
1008 }
1009
1010 /**
1011 * Readonly access to the [Request::$_external] property.
1012 *
1013 * if ( ! $request->is_external())
1014 * // This is an internal request
1015 *
1016 * @return boolean
1017 */
1018 public function is_external()
1019 {
1020 return $this->_external;
1021 }
1022
1023 /**
1024 * Returns whether this is an ajax request (as used by JS frameworks)
1025 *
1026 * @return boolean
1027 */
1028 public function is_ajax()
1029 {
1030 return ($this->requested_with() === 'xmlhttprequest');
1031 }
1032
1033 /**
1034 * Gets or sets the HTTP method. Usually GET, POST, PUT or DELETE in
1035 * traditional CRUD applications.
1036 *
1037 * @param string $method Method to use for this request
1038 * @return mixed
1039 */
1040 public function method($method = NULL)
1041 {
1042 if ($method === NULL)
1043 {
1044 // Act as a getter
1045 return $this->_method;
1046 }
1047
1048 // Act as a setter
1049 $this->_method = strtoupper($method);
1050
1051 return $this;
1052 }
1053
1054 /**
1055 * Gets or sets the HTTP protocol. If there is no current protocol set,
1056 * it will use the default set in HTTP::$protocol
1057 *
1058 * @param string $protocol Protocol to set to the request
1059 * @return mixed
1060 */
1061 public function protocol($protocol = NULL)
1062 {
1063 if ($protocol === NULL)
1064 {
1065 if ($this->_protocol)
1066 return $this->_protocol;
1067 else
1068 return $this->_protocol = HTTP::$protocol;
1069 }
1070
1071 // Act as a setter
1072 $this->_protocol = strtoupper($protocol);
1073 return $this;
1074 }
1075
1076 /**
1077 * Getter/Setter to the security settings for this request. This
1078 * method should be treated as immutable.
1079 *
1080 * @param boolean $secure is this request secure?
1081 * @return mixed
1082 */
1083 public function secure($secure = NULL)
1084 {
1085 if ($secure === NULL)
1086 return $this->_secure;
1087
1088 // Act as a setter
1089 $this->_secure = (bool) $secure;
1090 return $this;
1091 }
1092
1093 /**
1094 * Gets or sets HTTP headers oo the request. All headers
1095 * are included immediately after the HTTP protocol definition during
1096 * transmission. This method provides a simple array or key/value
1097 * interface to the headers.
1098 *
1099 * @param mixed $key Key or array of key/value pairs to set
1100 * @param string $value Value to set to the supplied key
1101 * @return mixed
1102 */
1103 public function headers($key = NULL, $value = NULL)
1104 {
1105 if ($key instanceof HTTP_Header)
1106 {
1107 // Act a setter, replace all headers
1108 $this->_header = $key;
1109
1110 return $this;
1111 }
1112
1113 if (is_array($key))
1114 {
1115 // Act as a setter, replace all headers
1116 $this->_header->exchangeArray($key);
1117
1118 return $this;
1119 }
1120
1121 if ($this->_header->count() === 0 AND $this->is_initial())
1122 {
1123 // Lazy load the request headers
1124 $this->_header = HTTP::request_headers();
1125 }
1126
1127 if ($key === NULL)
1128 {
1129 // Act as a getter, return all headers
1130 return $this->_header;
1131 }
1132 elseif ($value === NULL)
1133 {
1134 // Act as a getter, single header
1135 return ($this->_header->offsetExists($key)) ? $this->_header->offsetGet($key) : NULL;
1136 }
1137
1138 // Act as a setter for a single header
1139 $this->_header[$key] = $value;
1140
1141 return $this;
1142 }
1143
1144 /**
1145 * Set and get cookies values for this request.
1146 *
1147 * @param mixed $key Cookie name, or array of cookie values
1148 * @param string $value Value to set to cookie
1149 * @return string
1150 * @return mixed
1151 */
1152 public function cookie($key = NULL, $value = NULL)
1153 {
1154 if (is_array($key))
1155 {
1156 // Act as a setter, replace all cookies
1157 $this->_cookies = $key;
1158 return $this;
1159 }
1160 elseif ($key === NULL)
1161 {
1162 // Act as a getter, all cookies
1163 return $this->_cookies;
1164 }
1165 elseif ($value === NULL)
1166 {
1167 // Act as a getting, single cookie
1168 return isset($this->_cookies[$key]) ? $this->_cookies[$key] : NULL;
1169 }
1170
1171 // Act as a setter for a single cookie
1172 $this->_cookies[$key] = (string) $value;
1173
1174 return $this;
1175 }
1176
1177 /**
1178 * Gets or sets the HTTP body of the request. The body is
1179 * included after the header, separated by a single empty new line.
1180 *
1181 * @param string $content Content to set to the object
1182 * @return mixed
1183 */
1184 public function body($content = NULL)
1185 {
1186 if ($content === NULL)
1187 {
1188 // Act as a getter
1189 return $this->_body;
1190 }
1191
1192 // Act as a setter
1193 $this->_body = $content;
1194
1195 return $this;
1196 }
1197
1198 /**
1199 * Returns the length of the body for use with
1200 * content header
1201 *
1202 * @return integer
1203 */
1204 public function content_length()
1205 {
1206 return strlen($this->body());
1207 }
1208
1209 /**
1210 * Renders the HTTP_Interaction to a string, producing
1211 *
1212 * - Protocol
1213 * - Headers
1214 * - Body
1215 *
1216 * If there are variables set to the `Kohana_Request::$_post`
1217 * they will override any values set to body.
1218 *
1219 * @return string
1220 */
1221 public function render()
1222 {
1223 if ( ! $post = $this->post())
1224 {
1225 $body = $this->body();
1226 }
1227 else
1228 {
1229 $body = http_build_query($post, NULL, '&');
1230 $this->body($body)
1231 ->headers('content-type', 'application/x-www-form-urlencoded; charset='.Kohana::$charset);
1232 }
1233
1234 // Set the content length
1235 $this->headers('content-length', (string) $this->content_length());
1236
1237 // If Kohana expose, set the user-agent
1238 if (Kohana::$expose)
1239 {
1240 $this->headers('user-agent', Kohana::version());
1241 }
1242
1243 // Prepare cookies
1244 if ($this->_cookies)
1245 {
1246 $cookie_string = array();
1247
1248 // Parse each
1249 foreach ($this->_cookies as $key => $value)
1250 {
1251 $cookie_string[] = $key.'='.$value;
1252 }
1253
1254 // Create the cookie string
1255 $this->_header['cookie'] = implode('; ', $cookie_string);
1256 }
1257
1258 $output = $this->method().' '.$this->uri().' '.$this->protocol()."\r\n";
1259 $output .= (string) $this->_header;
1260 $output .= $body;
1261
1262 return $output;
1263 }
1264
1265 /**
1266 * Gets or sets HTTP query string.
1267 *
1268 * @param mixed $key Key or key value pairs to set
1269 * @param string $value Value to set to a key
1270 * @return mixed
1271 * @uses Arr::path
1272 */
1273 public function query($key = NULL, $value = NULL)
1274 {
1275 if (is_array($key))
1276 {
1277 // Act as a setter, replace all query strings
1278 $this->_get = $key;
1279
1280 return $this;
1281 }
1282
1283 if ($key === NULL)
1284 {
1285 // Act as a getter, all query strings
1286 return $this->_get;
1287 }
1288 elseif ($value === NULL)
1289 {
1290 // Act as a getter, single query string
1291 return Arr::path($this->_get, $key);
1292 }
1293
1294 // Act as a setter, single query string
1295 $this->_get[$key] = $value;
1296
1297 return $this;
1298 }
1299
1300 /**
1301 * Gets or sets HTTP POST parameters to the request.
1302 *
1303 * @param mixed $key Key or key value pairs to set
1304 * @param string $value Value to set to a key
1305 * @return mixed
1306 * @uses Arr::path
1307 */
1308 public function post($key = NULL, $value = NULL)
1309 {
1310 if (is_array($key))
1311 {
1312 // Act as a setter, replace all fields
1313 $this->_post = $key;
1314
1315 return $this;
1316 }
1317
1318 if ($key === NULL)
1319 {
1320 // Act as a getter, all fields
1321 return $this->_post;
1322 }
1323 elseif ($value === NULL)
1324 {
1325 // Act as a getter, single field
1326 return Arr::path($this->_post, $key);
1327 }
1328
1329 // Act as a setter, single field
1330 $this->_post[$key] = $value;
1331
1332 return $this;
1333 }
1334
1335 }