MAGETWO-49470: [Git][PR] Process public PRs #3302 #3219 #2718 #2292 #2180

- Readme update

Author: mazhalai

phpserver/README.md

@@ -1,9 +1,11 @@
 PHP Built-in webserver
 ======================
 
-php has a Built-in webserver since version 5.4 https://secure.php.net/manual/en/features.commandline.webserver.php
+PHP has had a <a href="https://secure.php.net/manual/en/features.commandline.webserver.php" target="_blank">built-in web sever</a> since version 5.4.
 
-As many applications and frameworks rely on rewrites on webserver side, the same as Magento does, it offers an argument for a router script. Either the script returns false which means, it should try to deliver the file as usual via file system lookup, or it executes the specific php scripts via include.
+PHP's web server provides a router script for use with server rewrites. Magento, like many other applications and frameworks, requires server rewrites.The router script either:
+- The web server executes the requested PHP script using a server-side include
+- Returns `false`, which means the web server returns the file using file system lookup
 
 Example:
 requests to `/static/frontend/Magento/blank/en_US/mage/calendar.css` should deliver the file if it exists, or execute `/static.php` if not.
@@ -12,7 +14,7 @@ Without a router script, that is not possible via the php built-in server.
 
 ### How to install Magento
 
-Because the router can not route the `setup` folder, it's necessary to install Magento manually without the web wizard. You can process the installation for your application using the following command line: 
+Magento's web-based Setup Wizard runs from the `setup` subdirectory, which PHP's built-in web server cannot route. Therefore, you must install Magento using the <a href="http://devdocs.magento.com/guides/v2.0/install-gde/install/cli/install-cli.html" target="_blank">command line</a>. An example follows:
 
 ```
 php bin/magento setup:install --base-url=http://127.0.0.1:8082 
@@ -24,7 +26,9 @@ php bin/magento setup:install --base-url=http://127.0.0.1:8082
 
 It's important to note that the router is not able to work with rewrite urls, that's why the flag `use-rewrites` is set to `0`.
 
-At the end of the installation process, don't forget to note the admin uri. That will let you access to the admin panel. For example : ```http://127.0.0.1:8082/index.php/admin_1vpn01```.
+Notes:
+- You must use `--use-rewrites=0` because the web server cannot rewrite URLs
+- By default, Magento creates a random Admin URI for you. Make sure to write this value down because it's how you access the Magento Admin later. For example : ```http://127.0.0.1:8082/index.php/admin_1vpn01```.
 
 For more informations about the installation process using the CLI, you can consult the dedicated documentation that can found in [the developer documentation](https://github.com/magento/devdocs/blob/develop/guides/v2.0/install-gde/install/cli/install-cli-install.md).
 
@@ -34,9 +38,13 @@ Example usage: ```php -S 127.0.0.1:8082 -t ./pub/ ./phpserver/router.php```
 
 ### What exactly the script does
 
-first we have an low level `$debug` closure, for the case you need to debug execution.
+The `$debug` option provides low-level logging for debugging purposes.
 
-If the request path starts with index.php, get.php, static.php, we return to normal request flow. If we notice a favicon.ico request, the same.
+Forwarding rules:
+- Any request for `favicon.ico` or for any path that starts with `index.php`, `get.php`, `static.php` are processed normally.
+- Requests for the path `pub/errors/default` are rewritten as `errors/default`. This is provided for compatibility with older versions.
+- Files under request paths `media`, `opt`, or `static` are tested; if the file exists, the file is served. If the file does not exist, `static` files are forwarded to `static.php` and `media` files are forwarded to `get.php` ((How about `opt`?))
+- If no rules are matched, return a 404 (Not Found).
 
 Then rewrite paths for `pub/errors/default/` by removing the `pub/` part. (was at least needed for older versions)
 
@@ -46,4 +54,7 @@ If none of the rules matched, return 404. You may instead include the index.php,
 
 ### How to access to the admin dashboard
 
-At the end of the installation process, it's necessary to get the admin uri.
+When the installation is finished, you can access Magento as follows:
+- Storefront: `<your Magento base URL>`
+- Magento Admin: `<your Magento base URL>/<admin URI>`
+