Extensive update of README

Author: paulbalandan

README.md

@@ -1,10 +1,16 @@
 # NexusPHP CS Config
 
+[![PHP version](https://img.shields.io/packagist/php-v/nexusphp/cs-config)](https://php.net)
+![build](https://github.com/NexusPHP/cs-config/workflows/build/badge.svg?branch=develop)
+[![Coverage Status](https://coveralls.io/repos/github/NexusPHP/cs-config/badge.svg?branch=develop)](https://coveralls.io/github/NexusPHP/cs-config?branch=develop)
+[![Latest Stable Version](https://poser.pugx.org/nexusphp/cs-config/v)](//packagist.org/packages/nexusphp/cs-config)
+[![license MIT](https://img.shields.io/github/license/nexusphp/cs-config)](LICENSE)
+
 This library provides a factory for custom rulesets for [`friendsofphp/php-cs-fixer`][1].
 
 [1]: https://github.com/FriendsOfPHP/PHP-CS-Fixer
 
-*This is the drop-in replacement for [Liaison CS Config](https://github.com/paulbalandan/liaison-cs-config).*
+*This is the drop-in replacement for [Liaison CS Config](https://github.com/paulbalandan/liaison-cs-config), but is not fully backwards compatible. See [MIGRATION.md](MIGRATION.md) for details.*
 
 ## Installation
 
@@ -28,7 +34,7 @@ then you should add it as a development-time dependency:
 use Nexus\CsConfig\Factory;
 use Nexus\CsConfig\Ruleset\Nexus73;
 
-return Factory::create(new Nexus73());
+return Factory::create(new Nexus73())->forProjects();
 
 ```
 
@@ -42,3 +48,209 @@ vendor/
 +.php_cs
 +.php_cs.cache
 ```
+
+## Advanced Configuration
+
+### Adding Preformatted License Header
+
+You can create a preformatted license header to all PHP files by using the public `forLibrary()` method
+instead of `forProjects()`. This method accepts two required arguments (the library name and author) and
+two optional arguments (the email address and starting year of license).
+
+* Scenario 1: Providing all arguments
+```diff
+<?php
+
+use Nexus\CsConfig\Factory;
+use Nexus\CsConfig\Ruleset\Nexus73;
+
+-return Factory::create(new Nexus73())->forProjects();
++return Factory::create(new Nexus73())->forLibrary('My Library', 'John Doe', '[email protected]', 2020);
+```
+
+This setting will configure a license header similar to below:
+
+```php
+<?php
+
+/**
+ * This file is part of My Library.
+ *
+ * (c) 2020 John Doe <john@doe.com>
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+namespace Nexus\CsConfig;
+```
+
+* Scenario 2: Providing only the required arguments
+
+If you opted not to provided any of the optional arguments (i.e., email address, starting license year),
+these will not be shown on the license header allowing flexibility on the copyright portion.
+
+```diff
+<?php
+
+use Nexus\CsConfig\Factory;
+use Nexus\CsConfig\Ruleset\Nexus73;
+
+-return Factory::create(new Nexus73())->forProjects();
++return Factory::create(new Nexus73())->forLibrary('My Library', 'John Doe');
+```
+
+This will give the following license header:
+
+```php
+<?php
+
+/**
+ * This file is part of My Library.
+ *
+ * (c) John Doe
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+namespace Nexus\CsConfig;
+```
+
+### Overriding Rules in a Ruleset
+
+If you feel that a specific rule in the ruleset is not appropriate for you, you can override it instead of creating a new ruleset:
+
+```diff
+<?php
+
+use Nexus\CsConfig\Factory;
+use Nexus\CsConfig\Ruleset\Nexus73;
+
+-return Factory::create(new Nexus73())->forProjects();
++return Factory::create(new Nexus73(), [
++    'binary_operator_spaces' => false,
++])->forProjects();
+
+```
+
+### Specifying Options to `PhpCsFixer\Config`
+
+The `Factory` class returns an instance of `PhpCsFixer\Config` and fully supports all of
+its properties setup. You can pass an array to the third parameter of `Factory::create()`
+containing your desired options.
+
+**Options**
+
+| Key            | Allowed Types                            | Default                              |
+| -------------- | :--------------------------------------: | :----------------------------------: |
+| cacheFile      | `string`                                 | `.php_cs.cache`                      |
+| customFixers   | `FixerInterface[], iterable, \Traversable` | `[]`                                 |
+| finder         | `iterable, string[], \Traversable`         | default `PhpCsFixer\Finder` instance |
+| format         | `string`                                 | `txt`                                |
+| hideProgress   | `bool`                                   | `false`                              |
+| indent         | `string`                                 | `'    '` // 4 spaces                 |
+| lineEnding     | `string`                                 | `"\n"`                               |
+| phpExecutable  | `null, string`                           | `null`                               |
+| isRiskyAllowed | `bool`                                   | `false`                              |
+| usingCache     | `bool`                                   | `true`                               |
+| customRules    | `array`                                  | `[]`                                 |
+
+```diff
+<?php
+
+use Nexus\CsConfig\Factory;
+use Nexus\CsConfig\Ruleset\Nexus73;
+
+-return Factory::create(new Nexus73())->forProjects();
++return Factory::create(new Nexus73(), [], [
++    'usingCache'  => false,
++    'hideProgress => true,
++])->forProjects();
+```
+
+## Customization of Ruleset
+
+What is the purpose of a configuration factory if not able to create a custom ruleset for
+an organization-wide usage, right? Well, you are not constrained to use the default rulesets
+and putting a long array of overrides. That's pretty nasty.
+
+The way to achieve this is dependent on you but the main idea is creating a new ruleset that
+extends `Nexus\CsConfig\Ruleset\AbstractRuleset`. Yup, it's that easy. Then you just need to
+provide details for its required four (4) protected properties.
+
+```php
+<?php
+
+namespace MyCompany\CodingStandards\Ruleset;
+
+use Nexus\CsConfig\Ruleset\AbstractRuleset;
+
+class MyCompany extends AbstractRuleset
+{
+  /**
+   * Name of this ruleset
+   *
+   * @var string
+   */
+  protected $name = 'My Company';
+
+  /**
+   * Your list of rules
+   *
+   * @var array
+   */
+  protected $rules = [
+    '@PSR2' => true,
+    ...
+  ];
+
+  /**
+   * PHP_VERSION_ID that this ruleset is targeting.
+   *
+   * @var int
+   */
+  protected $requiredPHPVersion = 70400;
+
+  /**
+   * Does this ruleset have risky rules?
+   *
+   * If yes and `PhpCsFixer\Config` has the `$isRiskyAllowed`
+   * flag set to `false`, those risky rules won't be run.
+   *
+   * Set this flag to `true` to automatically setup
+   * the `$isRiskyAllowed` flag.
+   *
+   * @var bool
+   */
+  protected $autoActivateIsRiskyAllowed = false;
+}
+
+```
+
+Then, in creating your `.php_cs.dist`, use your own ruleset.
+
+```php
+<?php
+
+use Nexus\CsConfig\Factory;
+use MyCompany\CodingStandards\Ruleset\MyCompany;
+
+return Factory::create(new MyCompany())->forProjects();
+
+```
+
+## Migrating from Liaison CS Config Factory
+
+If you are coming from the use of Liaison CS Config Factory, be warned that this is not 100% backwards
+compatible. Though some class methods were retained, a lot were refactored for the `Factory` class.
+
+See [MIGRATION.md](MIGRATION.md) for more details.
+
+## Credits
+
+This project is inspired by and an enhancement of [`ergebnis/php-cs-fixer-config`](https://github.com/ergebnis/php-cs-fixer-config).
+
+## Contributing
+
+Contributions are very much welcome. If you see an improvement or bugfix, open a [PR](https://github.com/NexusPHP/cs-config/pulls) now!