README.md

NexusPHP CS Config

This library provides a factory for custom rulesets for friendsofphp/php-cs-fixer.

This is the drop-in replacement for Liaison CS Config Factory, but is not fully backwards compatible. See MIGRATION.md for details.

Installation

You can add this library as a local, per-project dependency to your project using Composer:

composer require nexusphp/cs-config

If you only need this library during development, for instance to run your project's test suite, then you should add it as a development-time dependency:

composer require --dev nexusphp/cs-config

Configuration

• Create a .php_cs.dist at the root of your project:

<?php

use Nexus\CsConfig\Factory;
use Nexus\CsConfig\Ruleset\Nexus73;

return Factory::create(new Nexus73())->forProjects();

• Include the cache file in your .gitignore. By default, the cache file will be saved in the project root.

vendor/

+# php-cs-fixer
+.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

<?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

/**
 * This file is part of My Library.
 *
 * (c) 2020 John Doe <[email protected]>
 *
 * 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 provide 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.

<?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

/**
 * 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:

<?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	[]

<?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

namespace MyCompany\CodingStandards\Ruleset;

use Nexus\CsConfig\Ruleset\AbstractRuleset;

final class MyCompany extends AbstractRuleset
{
  public function __construct()
  {
    $this->name = 'My Company';
    $this->rules = [
      '@PSR2' => true,
      ...
    ];
    $this->requiredPHPVersion = 70400;
    $this->autoActivateIsRiskyAllowed = true;
  }
}

Then, in creating your .php_cs.dist, use your own ruleset.

<?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 for more details.

Credits

This project is inspired by and an enhancement of ergebnis/php-cs-fixer-config.

Contributing

Contributions are very much welcome. If you see an improvement or bugfix, open a PR now!