Update readme with proper instructions and new layer version

Author: txase

README.md

@@ -1,36 +1,168 @@
 # PHP Layer For AWS Lambda
 
-Ever want to run PHP websites in AWS Lambda? It's your lucky day!
+Ever wanted to run PHP websites in AWS Lambda? It's your lucky day! This Lambda Runtime Layer runs the [PHP 7.1 webserver](http://php.net/manual/en/features.commandline.webserver.php) in response to [AWS API Gateway](https://aws.amazon.com/api-gateway/) requests.
 
-**:warning: This is an experimental AWS Lambda Layer and Runtime. It should not be used for production services. Obligatory legal statement follows:**
+**:warning: This is an experimental AWS Lambda Runtime Layer. It should not be used for production services. Please read the disclaimer at the bottom of this readme before using!**
 
-> STACKERY INC. AND/OR ITS RESPECTIVE SUPPLIERS MAKE NO REPRESENTATIONS ABOUT THE SUITABILITY, RELIABILITY, AVAILABILITY, TIMELINESS, AND ACCURACY OF THE INFORMATION, SOFTWARE, PRODUCTS, SERVICES AND RELATED GRAPHICS CONTAINED ON THE MSN WEB SITES FOR ANY PURPOSE. ALL SUCH INFORMATION, SOFTWARE, PRODUCTS, SERVICES AND RELATED GRAPHICS ARE PROVIDED "AS IS" WITHOUT WARRANTY OF ANY KIND. MICROSOFT AND/OR ITS RESPECTIVE SUPPLIERS HEREBY DISCLAIM ALL WARRANTIES AND CONDITIONS WITH REGARD TO THIS INFORMATION, SOFTWARE, PRODUCTS, SERVICES AND RELATED GRAPHICS, INCLUDING ALL IMPLIED WARRANTIES AND CONDITIONS OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, TITLE AND NON-INFRINGEMENT. IN NO EVENT SHALL MICROSOFT AND/OR ITS SUPPLIERS BE LIABLE FOR ANY DIRECT, INDIRECT, PUNITIVE, INCIDENTAL, SPECIAL, CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER INCLUDING, WITHOUT LIMITATION, DAMAGES FOR LOSS OF USE, DATA OR PROFITS, ARISING OUT OF OR IN ANY WAY CONNECTED WITH THE USE OR PERFORMANCE OF THE MSN WEB SITES, WITH THE DELAY OR INABILITY TO USE THE MSN WEB SITES OR RELATED SERVICES, THE PROVISION OF OR FAILURE TO PROVIDE SERVICES, OR FOR ANY INFORMATION, SOFTWARE, PRODUCTS, SERVICES AND RELATED GRAPHICS OBTAINED THROUGH THE MSN WEB SITES, OR OTHERWISE ARISING OUT OF THE USE OF THE MSN WEB SITES, WHETHER BASED ON CONTRACT, TORT, NEGLIGENCE, STRICT LIABILITY OR OTHERWISE, EVEN IF MICROSOFT OR ANY OF ITS SUPPLIERS HAS BEEN ADVISED OF THE POSSIBILITY OF DAMAGES. BECAUSE SOME STATES/JURISDICTIONS DO NOT ALLOW THE EXCLUSION OR LIMITATION OF LIABILITY FOR CONSEQUENTIAL OR INCIDENTAL DAMAGES, THE ABOVE LIMITATION MAY NOT APPLY TO YOU. IF YOU ARE DISSATISFIED WITH ANY PORTION OF THE MSN WEB SITES, OR WITH ANY OF THESE TERMS OF USE, YOUR SOLE AND EXCLUSIVE REMEDY IS TO DISCONTINUE USING THE MSN WEB SITES.
+## Current Layer Version ARN
+When creating/updating a Lambda function you must specify  a specific version of the layer. This readme will be kept up to date with the latest version available. The latest available Lambda Layer Version ARN is:
+
+**arn:aws:lambda:<region>:887080169480:layer:php71:2**
 
 ### Usage
-Simply configure your function as follows:
+#### General Usage
+The layer runs the PHP 7.1 [PHP webserver](http://php.net/manual/en/features.commandline.webserver.php) in /var/task, the root directory of function code packages:
+
+```sh
+$ php -S localhost:8000 '<handler>'
+```
 
-1. Set the `Runtime` to `provided`
-1. Determine the latest version of the layer: `aws lambda list-layer-versions --layer-name arn:aws:lambda:<your region>:887080169480:layer:php71`
-1. Add the following Lambda Layer: `arn:aws:lambda:<your region>:887080169480:layer:php71:<latest version>`
+The Lambda Function Handler property specifies the location of the of the webserver router script. This script must be provided.
 
-If you are using AWS SAM it's even easier! Update your function:
+##### Extensions
+Extensions can be built using the lambci/lambda:build-nodejs8.10 Docker image. It is recommended that extensions be built into a Lambda Layer in /lib/php/7.1/modules. Then, in a php.ini file in the Lambda Function root directory put:
+
+```ini
+extension_dir=/opt/lib/php/7.1/modules
+extension=...
+```
+
+The following extensions are built into the layer and available in /opt/lib/php/7.1/modules:
+
+```
+bz2.so
+calendar.so
+ctype.so
+curl.so
+dom.so
+exif.so
+fileinfo.so
+ftp.so
+gettext.so
+iconv.so
+json.so
+phar.so
+posix.so
+shmop.so
+simplexml.so
+sockets.so
+sysvmsg.so
+sysvsem.so
+sysvshm.so
+tokenizer.so
+wddx.so
+xml.so
+xmlreader.so
+xmlwriter.so
+xsl.so
+zip.so
+```
+
+#### Example
+Let's create an AWS SAM PHP application. We suggest using [Stackery](https://stackery.io) to make this super simple. It automates all the scaffolding shown below. But you may also choose to roll your own application from scratch.
+
+First, install [AWS SAM CLI](https://github.com/awslabs/aws-sam-cli). Make sure to create a SAM deployment bucket as shown in [Packaging your application](https://github.com/awslabs/aws-sam-cli/blob/develop/docs/deploying_serverless_applications.rst#packaging-your-application)
+
+Next, create a basic SAM application:
+
+```sh
+$ mkdir my-php-app
+$ cd my-php-app
+```
+
+Create a template.yaml file with the following SAM infrastructure:
 
 ```yaml
+AWSTemplateFormatVersion: 2010-09-09
+Description: My PHP Application
+Transform: AWS::Serverless-2016-10-31
 Resources:
-  MyFunction:
+  phpserver:
     Type: AWS::Serverless::Function
     Properties:
-      ...
+      FunctionName: !Sub ${AWS::StackName}-phpserver
+      Description: PHP Webserver
+      CodeUri: src/server
       Runtime: provided
+      Handler: router.php
+      MemorySize: 3008
+      Timeout: 30
+      Tracing: Active
       Layers:
-        - !Sub arn:aws:lambda:${AWS::Region}:887080169480:layer:php71
+        - !Sub arn:aws:lambda:${AWS::Region}:887080169480:layer:php71:2
+      Events:
+        api:
+          Type: Api
+          Properties:
+            Path: /{proxy+}
+            Method: ANY
 ```
 
-### Development
+Now create the PHP application in `src/server`. We're going to create a webserver router script first. Put the following in `router.php`:
 
-The layer is built by:
+```php
+<?php
+if (is_file($_SERVER['DOCUMENT_ROOT'].'/'.$_SERVER['SCRIPT_NAME'])) {
+  // Serve static files directly
+  return false;
+}
+
+// Run index.php for all requests
+$_SERVER['SCRIPT_NAME'] = '/index.php';
+require 'index.php';
+?>
+```
+
+Lastly, let's write our script. Put this in `index.php`:
+
+```php
+Hello World! You've reached <?php print($_SERVER['REQUEST_URI']); ?>
+```
+
+You should now have a directory structure like:
+
+```
+.
+├── template.yaml
+└── src
+    └── php
+        ├── index.php
+        └── router.php
+```
+
+We're ready to deploy! Run the following commands:
+
+```sh
+$ sam package \
+    --template-file template.yaml \
+    --output-template-file serverless-output.yaml \
+    --s3-bucket <your SAM deployment bucket created above>
+
+$ sam deploy \
+    --template-file serverless-output.yaml \
+    --stack-name my-first-serverless-php-service \
+    --capabilities CAPABILITY_IAM
+```
+
+### Development
+Build the layer by:
 
 1. Installing a Docker environment
-1. Running `make` in the layers directory
+1. Running `make`
+
+This will launch a Docker container that will build php71.zip.
+
+### Disclaimer
 
-This will launch a Docker container that will build php71.zip.
+> THIS SOFTWARE IS PROVIDED BY THE PHP DEVELOPMENT TEAM ``AS IS'' AND
+> ANY EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO,
+> THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A
+> PARTICULAR PURPOSE ARE DISCLAIMED.  IN NO EVENT SHALL THE PHP
+> DEVELOPMENT TEAM OR ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT,
+> INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
+> (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+> SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
+> HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT,
+> STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
+> ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED
+> OF THE POSSIBILITY OF SUCH DAMAGE.