yaffs.net Git - yaffs-website/blob - vendor/asm89/stack-cors/README.md

   1 # Stack/Cors
   2
   3 Library and middleware enabling cross-origin resource sharing for your
   4 http-{foundation,kernel} using application. It attempts to implement the
   5 [W3C Recommendation] for cross-origin resource sharing.
   6
   7 [W3C Recommendation]: http://www.w3.org/TR/cors/
   8
   9 Master [![Build Status](https://secure.travis-ci.org/asm89/stack-cors.png?branch=master)](http://travis-ci.org/asm89/stack-cors)
  10
  11 ## Installation
  12
  13 Require `asm89/stack-cors` using composer.
  14
  15 ## Usage
  16
  17 This package can be used as a library or as [stack middleware].
  18
  19 [stack middleware]: http://stackphp.com/
  20
  21 ### Options
  22
  23 | Option                 | Description                                                | Default value |
  24 |------------------------|------------------------------------------------------------|---------------|
  25 | allowedMethods         | Matches the request method.                                | `array()`     |
  26 | allowedOrigins         | Matches the request origin.                                | `array()`     |
  27 | allowedOriginsPatterns | Matches the request origin with `preg_match`.              | `array()`  |
  28 | allowedHeaders         | Sets the Access-Control-Allow-Headers response header.     | `array()`     |
  29 | exposedHeaders         | Sets the Access-Control-Expose-Headers response header.    | `false`       |
  30 | maxAge                 | Sets the Access-Control-Max-Age response header.           | `false`       |
  31 | supportsCredentials    | Sets the Access-Control-Allow-Credentials header.          | `false`       |
  32
  33 The _allowedMethods_ and _allowedHeaders_ options are case-insensitive.
  34
  35 You don't need to provide both _allowedOrigins_ and _allowedOriginsPatterns_. If one of the strings passed matches, it is considered a valid origin.
  36
  37 If `array('*')` is provided to _allowedMethods_, _allowedOrigins_ or _allowedHeaders_ all methods / origins / headers are allowed.
  38
  39 ### Example: using the library
  40
  41 ```php
  42 <?php
  43
  44 use Asm89\Stack\CorsService;
  45
  46 $cors = new CorsService(array(
  47     'allowedHeaders'         => array('x-allowed-header', 'x-other-allowed-header'),
  48     'allowedMethods'         => array('DELETE', 'GET', 'POST', 'PUT'),
  49     'allowedOrigins'         => array('localhost'),
  50     'allowedOriginsPatterns' => array('/localhost:\d/'),
  51     'exposedHeaders'         => false,
  52     'maxAge'                 => false,
  53     'supportsCredentials'    => false,
  54 ));
  55
  56 $cors->addActualRequestHeaders(Response $response, $origin);
  57 $cors->handlePreflightRequest(Request $request);
  58 $cors->isActualRequestAllowed(Request $request);
  59 $cors->isCorsRequest(Request $request);
  60 $cors->isPreflightRequest(Request $request);
  61 ```
  62
  63 ## Example: using the stack middleware
  64
  65 ```php
  66 <?php
  67
  68 use Asm89\Stack\Cors;
  69
  70 $app = new Cors($app, array(
  71     // you can use array('*') to allow any headers
  72     'allowedHeaders'      => array('x-allowed-header', 'x-other-allowed-header'),
  73     // you can use array('*') to allow any methods
  74     'allowedMethods'      => array('DELETE', 'GET', 'POST', 'PUT'),
  75     // you can use array('*') to allow requests from any origin
  76     'allowedOrigins'      => array('localhost'),
  77     // you can enter regexes that are matched to the origin request header
  78     'allowedOriginsPatterns' => array('/localhost:\d/'),
  79     'exposedHeaders'      => false,
  80     'maxAge'              => false,
  81     'supportsCredentials' => false,
  82 ));
  83 ```