From a1a051d518200f6e22ee993a79cd17fc535f3dab Mon Sep 17 00:00:00 2001
From: Michael Bianco <iloveitaly@gmail.com>
Date: Fri, 23 Apr 2021 11:37:09 -0600
Subject: [PATCH] Lots of documentation updates

---
 README.md | 51 +++++++++++++++++++++++++++++++++++++++++++++------
 1 file changed, 45 insertions(+), 6 deletions(-)

diff --git a/README.md b/README.md
index ef93a35..593f69b 100644
--- a/README.md
+++ b/README.md
@@ -21,13 +21,54 @@ for us to support them.
 ## Installation
 
 ```bash
-asdf plugin-add php https://github.com/asdf-community/asdf-php.git
+asdf plugin-add php
 ```
 
+Since this plugin compiles PHP from source, you'll want to ensure all other required packages are installed.
+After you've installed additional system packages, install a specific PHP version:
+
+```bash
+asdf install php 7.4.16
+```
+
+You can test to ensure the installation was successful:
+
+```bash
+asdf reshim
+php --version
+```
+
+Composer is installed globally alongside PHP by default. If your application requires additional php extensions, you may need to install them via `pecl`. For example:
+
+```bash
+pecl install redis
+pecl install imagick
+
+echo "extension=redis.so
+extension=imagick.so" > $(asdf where php)/conf.d/php.ini
+```
+
+#### MacOS
+
+To install PHP on MacOS, you'll need a set of packages installed via homebrew:
+
+```bash
+brew install bison bzip2 freetype gettext libiconv icu4c jpeg libedit libpng libxml2 libzip openssl readline webp zlib
+```
+
+You may want to run the above command with `upgrade` instead of `install` to ensure the latest version of all required packages is installed.
+
+There's also a set of optional packages which enable additional extensions to be enabled:
+
+```
+brew install gmp libsodium imagemagick
+```
+
+Note that the supported extension are not exhaustive, so you may need edit the `bin/install` script to support additional extension. Feel free to submit a PR for any missing extensions.
+
 #### Note: PHP-PEAR
 
-PHP PEAR is down without ETA for when the server will be back. To install PHP
-without PEAR you can specify a `PHP_WITHOUT_PEAR` variable with any value
+If PHP PEAR is down you can install PHP without PEAR. Specify `PHP_WITHOUT_PEAR` variable with any value
 (except no), eg:
 
 ```bash
@@ -41,9 +82,7 @@ install & manage versions.
 
 ## Global Composer Dependencies
 
-After installing a global composer package you will need to run `asdf reshim`.
-
-### Example
+Composer is installed globally by default. To use it, you'll need to reshim:
 
 ```shell
 composer global require friendsofphp/php-cs-fixer