classes/kohana/response.php

   1 <?php defined('SYSPATH') or die('No direct script access.');
   2 /**
   3  * Response wrapper. Created as the result of any [Request] execution
   4  * or utility method (i.e. Redirect). Implements standard HTTP
   5  * response format.
   6  *
   7  * @package    Kohana
   8  * @category   Base
   9  * @author     Kohana Team
  10  * @copyright  (c) 2008-2009 Kohana Team
  11  * @license    http://kohanaphp.com/license
  12  * @since      3.1.0
  13  */
  14 class Kohana_Response implements Serializable {
  15
  16         /**
  17          * Factory method to create a new [Response]. Pass properties
  18          * in using an associative array.
  19          *
  20          *      // Create a new response
  21          *      $response = Response::factory();
  22          *
  23          *      // Create a new response with headers
  24          *      $response = Response::factory(array('status' => 200));
  25          *
  26          * @param   array    setup the response object
  27          * @return  [Kohana_Response]
  28          */
  29         public static function factory(array $config = array())
  30         {
  31                 return new Response($config);
  32         }
  33
  34         /**
  35          * Generates a [Cache-Control HTTP](http://en.wikipedia.org/wiki/List_of_HTTP_headers)
  36          * header based on the supplied array.
  37          *
  38          *     // Set the cache control headers you want to use
  39          *     $cache_control = array(
  40          *         'max-age'          => 3600,
  41          *         'must-revalidate'  => NULL,
  42          *         'public'           => NULL
  43          *     );
  44          *
  45          *     // Create the cache control header, creates :
  46          *     // Cache-Control: max-age=3600, must-revalidate, public
  47          *     $response->headers['Cache-Control'] = Response::create_cache_control($cache_control);
  48          *
  49          * @param   array    cache_control parts to render
  50          * @return  string
  51          */
  52         public static function create_cache_control(array $cache_control)
  53         {
  54                 // Create a buffer
  55                 $parts = array();
  56
  57                 // Foreach cache control entry
  58                 foreach ($cache_control as $key => $value)
  59                 {
  60                         // Create a cache control fragment
  61                         $parts[] = empty($value) ? $key : $key.'='.$value;
  62                 }
  63                 // Return the rendered parts
  64                 return implode(', ', $parts);
  65         }
  66
  67         /**
  68          * Parses the Cache-Control header and returning an array representation of the Cache-Control
  69          * header.
  70          *
  71          *     // Create the cache control header
  72          *     $response->headers['Cache-Control'] = 'max-age=3600, must-revalidate, public';
  73          *
  74          *     // Parse the cache control header
  75          *     if($cache_control = Request::parse_cache_control($response->headers))
  76          *     {
  77          *          // Cache-Control header was found
  78          *          $maxage = $cache_control['max-age'];
  79          *     }
  80          *
  81          * @param   array    headers
  82          * @return  boolean|array
  83          * @since   3.1.0
  84          */
  85         public static function parse_cache_control(array $headers)
  86         {
  87                 // If there is no Cache-Control header
  88                 if ( ! isset($headers['Cache-Control']))
  89                 {
  90                         if (isset($headers['Expires']) and ($timestamp = strtotime($headers['Expires'])) !== FALSE)
  91                         {
  92                                 // Return a parsed version of the Expires header
  93                                 return Response::create_cache_control(array(
  94                                         'max-age'          => $timestamp - time(),
  95                                         'must-revalidate'  => NULL,
  96                                         'public'           => NULL
  97                                 ));
  98                         }
  99                         else
 100                         {
 101                                 // return
 102                                 return FALSE;
 103                         }
 104                 }
 105
 106                 // If no Cache-Control parts are detected
 107                 if ( (bool) preg_match_all('/(?<key>[a-z\-]+)=?(?<value>\w+)?/', $headers['Cache-Control'], $matches))
 108                 {
 109                         // Return combined cache-control key/value pairs
 110                         return array_combine($matches['key'], $matches['value']);
 111                 }
 112                 else
 113                 {
 114                         // Return
 115                         return FALSE;
 116                 }
 117         }
 118
 119         // HTTP status codes and messages
 120         public static $messages = array(
 121                 // Informational 1xx
 122                 100 => 'Continue',
 123                 101 => 'Switching Protocols',
 124
 125                 // Success 2xx
 126                 200 => 'OK',
 127                 201 => 'Created',
 128                 202 => 'Accepted',
 129                 203 => 'Non-Authoritative Information',
 130                 204 => 'No Content',
 131                 205 => 'Reset Content',
 132                 206 => 'Partial Content',
 133
 134                 // Redirection 3xx
 135                 300 => 'Multiple Choices',
 136                 301 => 'Moved Permanently',
 137                 302 => 'Found', // 1.1
 138                 303 => 'See Other',
 139                 304 => 'Not Modified',
 140                 305 => 'Use Proxy',
 141                 // 306 is deprecated but reserved
 142                 307 => 'Temporary Redirect',
 143
 144                 // Client Error 4xx
 145                 400 => 'Bad Request',
 146                 401 => 'Unauthorized',
 147                 402 => 'Payment Required',
 148                 403 => 'Forbidden',
 149                 404 => 'Not Found',
 150                 405 => 'Method Not Allowed',
 151                 406 => 'Not Acceptable',
 152                 407 => 'Proxy Authentication Required',
 153                 408 => 'Request Timeout',
 154                 409 => 'Conflict',
 155                 410 => 'Gone',
 156                 411 => 'Length Required',
 157                 412 => 'Precondition Failed',
 158                 413 => 'Request Entity Too Large',
 159                 414 => 'Request-URI Too Long',
 160                 415 => 'Unsupported Media Type',
 161                 416 => 'Requested Range Not Satisfiable',
 162                 417 => 'Expectation Failed',
 163
 164                 // Server Error 5xx
 165                 500 => 'Internal Server Error',
 166                 501 => 'Not Implemented',
 167                 502 => 'Bad Gateway',
 168                 503 => 'Service Unavailable',
 169                 504 => 'Gateway Timeout',
 170                 505 => 'HTTP Version Not Supported',
 171                 509 => 'Bandwidth Limit Exceeded'
 172         );
 173
 174         /**
 175          * @var  integer     the response http status
 176          */
 177         public $status = 200;
 178
 179         /**
 180          * @var  array       headers returned in the response
 181          */
 182         public $headers = array();
 183
 184         /**
 185          * @var  string      the response body
 186          */
 187         public $body = NULL;
 188
 189         /**
 190          * @var  array       cookies to be returned in the response
 191          */
 192         protected $_cookies = array();
 193
 194         /**
 195          * Sets up the response object
 196          *
 197          * @param   array $config
 198          * @return  void
 199          */
 200         public function __construct(array $config = array())
 201         {
 202                 foreach ($config as $key => $value)
 203                 {
 204                         if (property_exists($this, $key))
 205                         {
 206                                 $this->$key = $value;
 207                         }
 208                 }
 209
 210                 // Add the default Content-Type header if required
 211                 $this->headers += array('Content-Type' => 'text/html; charset='.Kohana::$charset);
 212
 213                 // Add the X-Powered-By header
 214                 if (Kohana::$expose)
 215                 {
 216                         $this->headers += array('X-Powered-By' => 'Kohana Framework '.Kohana::VERSION);
 217                 }
 218         }
 219
 220         /**
 221          * Outputs the body when cast to string
 222          *
 223          * @return void
 224          */
 225         public function __toString()
 226         {
 227                 return (string) $this->body;
 228         }
 229
 230         /**
 231          * Returns the body of the response
 232          *
 233          * @return  string
 234          */
 235         public function body()
 236         {
 237                 return (string) $this->body;
 238         }
 239
 240         /**
 241          * Sets or gets the HTTP status from this response.
 242          *
 243          *      // Set the HTTP status to 404 Not Found
 244          *      $response = Response::factory()
 245          *              ->status(404);
 246          *
 247          *      // Get the current status
 248          *      $status = $response->status();
 249          *
 250          * @param   integer  status to set to this response
 251          * @return  integer|self
 252          */
 253         public function status($status = NULL)
 254         {
 255                 if ($status === NULL)
 256                 {
 257                         return $this->status;
 258                 }
 259                 else if (array_key_exists($status, Response::$messages))
 260                 {
 261                         $this->status = (int) $status;
 262                         return $this;
 263                 }
 264                 else
 265                 {
 266                         throw new Kohana_Exception(__METHOD__.' unknown status value : :value', array(':value' => $status));
 267                 }
 268         }
 269
 270         /**
 271          * Gets and sets headers to the [Response], allowing chaining
 272          * of response methods. If chaining isn't required, direct
 273          * access to the property should be used instead.
 274          *
 275          *       // Get a header
 276          *       $accept = $response->headers('Content-Type');
 277          *
 278          *       // Set a header
 279          *       $response->headers('Content-Type', 'text/html');
 280          *
 281          *       // Get all headers
 282          *       $headers = $response->headers();
 283          *
 284          *       // Set multiple headers
 285          *       $response->headers(array('Content-Type' => 'text/html', 'Cache-Control' => 'no-cache'));
 286          *
 287          * @param string $key
 288          * @param string $value
 289          * @return void
 290          */
 291         public function headers($key = NULL, $value = NULL)
 292         {
 293                 if ($key === NULL)
 294                 {
 295                         return $this->headers;
 296                 }
 297                 else if (is_array($key))
 298                 {
 299                         $this->headers = $key;
 300                         return $this;
 301                 }
 302                 else if ($value === NULL)
 303                 {
 304                         return $this->headers[$key];
 305                 }
 306                 else
 307                 {
 308                         $this->headers[$key] = $value;
 309                         return $this;
 310                 }
 311         }
 312
 313         /**
 314          * Sets a cookie to the response
 315          *
 316          * @param   string   name
 317          * @param   string   value
 318          * @param   int      expiration
 319          * @return  self
 320          */
 321         public function set_cookie($name, $value, $expiration = NULL)
 322         {
 323                 if ($expiration === NULL)
 324                 {
 325                         $expiration = Cookie::$expiration;
 326                 }
 327                 else if ($expiration !== 0)
 328                 {
 329                         $expiration += time();
 330                 }
 331
 332                 $this->_cookies[$name] = array(
 333                         'value'      => $value,
 334                         'expiration' => $expiration
 335                 );
 336
 337                 return $this;
 338         }
 339
 340         /**
 341          * Returns a cookie by name
 342          *
 343          * @param   string $name
 344          * @param   string $default
 345          * @return  mixed
 346          */
 347         public function get_cookie($name, $default = NULL)
 348         {
 349                 return isset($this->_cookies[$name]) ? $this->_cookies[$name]['value'] : $default;
 350         }
 351
 352         /**
 353          * Get all the cookies
 354          *
 355          * @return  array
 356          */
 357         public function get_cookies()
 358         {
 359                 return $this->_cookies;
 360         }
 361
 362         /**
 363          * Deletes a cookie set to the response
 364          *
 365          * @param   string   name
 366          * @return  self
 367          */
 368         public function delete_cookie($name)
 369         {
 370                 if (isset($this->_cookies[$name]))
 371                 {
 372                         unset($this->_cookies[$name]);
 373                 }
 374
 375                 return $this;
 376         }
 377
 378         /**
 379          * Deletes all cookies from this response
 380          *
 381          * @return  self
 382          */
 383         public function delete_cookies()
 384         {
 385                 $this->_cookies = array();
 386                 return $this;
 387         }
 388
 389         /**
 390          * Sends the response status and all set headers.
 391          *
 392          * @return  $this
 393          */
 394         public function send_headers()
 395         {
 396                 if ( ! headers_sent())
 397                 {
 398                         if (isset($_SERVER['SERVER_PROTOCOL']))
 399                         {
 400                                 // Use the default server protocol
 401                                 $protocol = $_SERVER['SERVER_PROTOCOL'];
 402                         }
 403                         else
 404                         {
 405                                 // Default to using newer protocol
 406                                 $protocol = 'HTTP/1.1';
 407                         }
 408
 409                         // HTTP status line
 410                         header($protocol.' '.$this->status.' '.Response::$messages[$this->status]);
 411
 412                         foreach ($this->headers as $name => $value)
 413                         {
 414                                 if (is_string($name))
 415                                 {
 416                                         // Combine the name and value to make a raw header
 417                                         $value = "{$name}: {$value}";
 418                                 }
 419
 420                                 // Send the raw header
 421                                 header($value, TRUE);
 422                         }
 423
 424                         // Send cookies
 425                         foreach ($this->_cookies as $name => $value)
 426                         {
 427                                 Cookie::set($name, $value['value'], $value['expiration']);
 428                         }
 429                 }
 430
 431                 return $this;
 432         }
 433
 434         /**
 435          * Send file download as the response. All execution will be halted when
 436          * this method is called! Use TRUE for the filename to send the current
 437          * response as the file content. The third parameter allows the following
 438          * options to be set:
 439          *
 440          * Type      | Option    | Description                        | Default Value
 441          * ----------|-----------|------------------------------------|--------------
 442          * `boolean` | inline    | Display inline instead of download | `FALSE`
 443          * `string`  | mime_type | Manual mime type                   | Automatic
 444          * `boolean` | delete    | Delete the file after sending      | `FALSE`
 445          *
 446          * Download a file that already exists:
 447          *
 448          *     $request->send_file('media/packages/kohana.zip');
 449          *
 450          * Download generated content as a file:
 451          *
 452          *     $request->response = $content;
 453          *     $request->send_file(TRUE, $filename);
 454          *
 455          * [!!] No further processing can be done after this method is called!
 456          *
 457          * @param   string   filename with path, or TRUE for the current response
 458          * @param   string   downloaded file name
 459          * @param   array    additional options
 460          * @return  void
 461          * @throws  Kohana_Exception
 462          * @uses    File::mime_by_ext
 463          * @uses    File::mime
 464          * @uses    Request::send_headers
 465          */
 466         public function send_file($filename, $download = NULL, array $options = NULL)
 467         {
 468                 if ( ! empty($options['mime_type']))
 469                 {
 470                         // The mime-type has been manually set
 471                         $mime = $options['mime_type'];
 472                 }
 473
 474                 if ($filename === TRUE)
 475                 {
 476                         if (empty($download))
 477                         {
 478                                 throw new Kohana_Exception('Download name must be provided for streaming files');
 479                         }
 480
 481                         // Temporary files will automatically be deleted
 482                         $options['delete'] = FALSE;
 483
 484                         if ( ! isset($mime))
 485                         {
 486                                 // Guess the mime using the file extension
 487                                 $mime = File::mime_by_ext(strtolower(pathinfo($download, PATHINFO_EXTENSION)));
 488                         }
 489
 490                         // Force the data to be rendered if
 491                         $file_data = (string) $this->response;
 492
 493                         // Get the content size
 494                         $size = strlen($file_data);
 495
 496                         // Create a temporary file to hold the current response
 497                         $file = tmpfile();
 498
 499                         // Write the current response into the file
 500                         fwrite($file, $file_data);
 501
 502                         // File data is no longer needed
 503                         unset($file_data);
 504                 }
 505                 else
 506                 {
 507                         // Get the complete file path
 508                         $filename = realpath($filename);
 509
 510                         if (empty($download))
 511                         {
 512                                 // Use the file name as the download file name
 513                                 $download = pathinfo($filename, PATHINFO_BASENAME);
 514                         }
 515
 516                         // Get the file size
 517                         $size = filesize($filename);
 518
 519                         if ( ! isset($mime))
 520                         {
 521                                 // Get the mime type
 522                                 $mime = File::mime($filename);
 523                         }
 524
 525                         // Open the file for reading
 526                         $file = fopen($filename, 'rb');
 527                 }
 528
 529                 if ( ! is_resource($file))
 530                 {
 531                         throw new Kohana_Exception('Could not read file to send: :file', array(
 532                                 ':file' => $download,
 533                         ));
 534                 }
 535
 536                 // Inline or download?
 537                 $disposition = empty($options['inline']) ? 'attachment' : 'inline';
 538
 539                 // Calculate byte range to download.
 540                 list($start, $end) = $this->_calculate_byte_range($size);
 541
 542                 if ( ! empty($options['resumable']))
 543                 {
 544                         if($start > 0 OR $end < ($size - 1))
 545                         {
 546                                 // Partial Content
 547                                 $this->status = 206;
 548                         }
 549
 550                         // Range of bytes being sent
 551                         $this->headers['Content-Range'] = 'bytes '.$start.'-'.$end.'/'.$size;
 552                         $this->headers['Accept-Ranges'] = 'bytes';
 553                 }
 554
 555                 // Set the headers for a download
 556                 $this->headers['Content-Disposition'] = $disposition.'; filename="'.$download.'"';
 557                 $this->headers['Content-Type']        = $mime;
 558                 $this->headers['Content-Length']      = ($end - $start) + 1;
 559
 560                 if (Request::user_agent('browser') === 'Internet Explorer')
 561                 {
 562                         // Naturally, IE does not act like a real browser...
 563                         if (Request::$protocol === 'https')
 564                         {
 565                                 // http://support.microsoft.com/kb/316431
 566                                 $this->headers['Pragma'] = $this->headers['Cache-Control'] = 'public';
 567                         }
 568
 569                         if (version_compare(Request::user_agent('version'), '8.0', '>='))
 570                         {
 571                                 // http://ajaxian.com/archives/ie-8-security
 572                                 $this->headers['X-Content-Type-Options'] = 'nosniff';
 573                         }
 574                 }
 575
 576                 // Send all headers now
 577                 $this->send_headers();
 578
 579                 while (ob_get_level())
 580                 {
 581                         // Flush all output buffers
 582                         ob_end_flush();
 583                 }
 584
 585                 // Manually stop execution
 586                 ignore_user_abort(TRUE);
 587
 588                 if ( ! Kohana::$safe_mode)
 589                 {
 590                         // Keep the script running forever
 591                         set_time_limit(0);
 592                 }
 593
 594                 // Send data in 16kb blocks
 595                 $block = 1024 * 16;
 596
 597                 fseek($file, $start);
 598
 599                 while ( ! feof($file) AND ($pos = ftell($file)) <= $end)
 600                 {
 601                         if (connection_aborted())
 602                                 break;
 603
 604                         if ($pos + $block > $end)
 605                         {
 606                                 // Don't read past the buffer.
 607                                 $block = $end - $pos + 1;
 608                         }
 609
 610                         // Output a block of the file
 611                         echo fread($file, $block);
 612
 613                         // Send the data now
 614                         flush();
 615                 }
 616
 617                 // Close the file
 618                 fclose($file);
 619
 620                 if ( ! empty($options['delete']))
 621                 {
 622                         try
 623                         {
 624                                 // Attempt to remove the file
 625                                 unlink($filename);
 626                         }
 627                         catch (Exception $e)
 628                         {
 629                                 // Create a text version of the exception
 630                                 $error = Kohana_Exception::text($e);
 631
 632                                 if (is_object(Kohana::$log))
 633                                 {
 634                                         // Add this exception to the log
 635                                         Kohana::$log->add(Kohana::ERROR, $error);
 636
 637                                         // Make sure the logs are written
 638                                         Kohana::$log->write();
 639                                 }
 640
 641                                 // Do NOT display the exception, it will corrupt the output!
 642                         }
 643                 }
 644
 645                 // Stop execution
 646                 exit;
 647         }
 648
 649         /**
 650          * Parse the byte ranges from the HTTP_RANGE header used for
 651          * resumable downloads.
 652          *
 653          * @see http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html#sec14.35
 654          * @return array|FALSE
 655          */
 656         protected function _parse_byte_range()
 657         {
 658                 if ( ! isset($_SERVER['HTTP_RANGE']))
 659                 {
 660                         return FALSE;
 661                 }
 662
 663                 // TODO, speed this up with the use of string functions.
 664                 preg_match_all('/(-?[0-9]++(?:-(?![0-9]++))?)(?:-?([0-9]++))?/', $_SERVER['HTTP_RANGE'], $matches, PREG_SET_ORDER);
 665
 666                 return $matches[0];
 667         }
 668
 669         /**
 670          * Calculates the byte range to use with send_file. If HTTP_RANGE doesn't
 671          * exist then the complete byte range is returned
 672          *
 673          * @param  integer $size
 674          * @return array
 675          */
 676         protected function _calculate_byte_range($size)
 677         {
 678                 // Defaults to start with when the HTTP_RANGE header doesn't exist.
 679                 $start = 0;
 680                 $end = $size - 1;
 681
 682                 if($range = $this->_parse_byte_range())
 683                 {
 684                         // We have a byte range from HTTP_RANGE
 685                         $start = $range[1];
 686
 687                         if ($start[0] === '-')
 688                         {
 689                                 // A negative value means we start from the end, so -500 would be the
 690                                 // last 500 bytes.
 691                                 $start = $size - abs($start);
 692                         }
 693
 694                         if (isset($range[2]))
 695                         {
 696                                 // Set the end range
 697                                 $end = $range[2];
 698                         }
 699                 }
 700
 701                 // Normalize values.
 702                 $start = abs(intval($start));
 703
 704                 // Keep the the end value in bounds and normalize it.
 705                 $end = min(abs(intval($end)), $size - 1);
 706
 707                 // Keep the start in bounds.
 708                 $start = $end < $start ? 0 : max($start, 0);
 709
 710                 return array($start, $end);
 711         }
 712
 713         /**
 714          * Generate ETag
 715          * Generates an ETag from the response ready to be returned
 716          *
 717          * @throws Kohana_Request_Exception
 718          * @return String Generated ETag
 719          */
 720         public function generate_etag()
 721         {
 722             if ($this->response === NULL)
 723                 {
 724                         throw new Kohana_Request_Exception('No response yet associated with request - cannot auto generate resource ETag');
 725                 }
 726
 727                 // Generate a unique hash for the response
 728                 return '"'.sha1($this->body).'"';
 729         }
 730
 731         /**
 732          * Check Cache
 733          * Checks the browser cache to see the response needs to be returned
 734          *
 735          * @param String Resource ETag
 736          * @throws Kohana_Request_Exception
 737          * @chainable
 738          */
 739         public function check_cache($etag = null)
 740         {
 741                 if (empty($etag))
 742                 {
 743                         $etag = $this->generate_etag();
 744                 }
 745
 746                 // Set the ETag header
 747                 $this->headers['ETag'] = $etag;
 748
 749                 // Add the Cache-Control header if it is not already set
 750                 // This allows etags to be used with Max-Age, etc
 751                 $this->headers += array(
 752                         'Cache-Control' => 'must-revalidate',
 753                 );
 754
 755                 if (isset($_SERVER['HTTP_IF_NONE_MATCH']) AND $_SERVER['HTTP_IF_NONE_MATCH'] === $etag)
 756                 {
 757                         // No need to send data again
 758                         $this->status = 304;
 759                         $this->send_headers();
 760
 761                         // Stop execution
 762                         exit;
 763                 }
 764
 765                 return $this;
 766         }
 767
 768         /**
 769          * Serializes the object to json - handy if you
 770          * need to pass the response data to other
 771          * systems
 772          *
 773          * @param   array    array of data to serialize
 774          * @return  string
 775          * @throws  Kohana_Exception
 776          */
 777         public function serialize(array $toSerialize = array())
 778         {
 779                 // Serialize the class properties
 780                 $toSerialize += array
 781                 (
 782                         'status'  => $this->status,
 783                         'headers' => $this->headers,
 784                         'cookies' => $this->_cookies,
 785                         'body'    => $this->body
 786                 );
 787
 788                 $string = json_encode($toSerialize);
 789
 790                 if (is_string($string))
 791                 {
 792                         return $string;
 793                 }
 794                 else
 795                 {
 796                         throw new Kohana_Exception('Unable to correctly encode object to json');
 797                 }
 798         }
 799
 800         /**
 801          * JSON encoded object
 802          *
 803          * @param   string   json encoded object
 804          * @return  bool
 805          * @throws  Kohana_Exception
 806          */
 807         public function unserialize($string)
 808         {
 809                 // Unserialise object
 810                 $unserialized = json_decode($string);
 811
 812                 // If failed
 813                 if ($unserialized === NULL)
 814                 {
 815                         // Throw exception
 816                         throw new Kohana_Exception('Unable to correctly decode object from json');
 817                 }
 818
 819                 // Foreach key/value pair
 820                 foreach ($unserialized as $key => $value)
 821                 {
 822                         // If it belongs here
 823                         if (property_exists($this, $key))
 824                         {
 825                                 // Apply it
 826                                 $this->$key = $value;
 827                         }
 828                 }
 829
 830                 return TRUE;
 831         }
 832 }