👃 💩 Custom PHP Code Sniffer sniffs to help find Code Smells (Odor).
Inspired by: https://github.com/object-calisthenics/phpcs-calisthenics-rules
- What Is it?
- Compatibility
- How to Install?
- How to Use?
- Omitting Sniffs
- Running Specific Sniffs
- Sniffs Included
- Customizing Sniffs
- Customizations Available
- Similar Packages
- Contributing
- License
This package is a set of custom Sniffs for the PHP Code Sniffer that you can use in your CI build to ensure the ingegrity of your code base.
- PHP 7.1+ please use v1.0.0 and above.
- PHP 5.6 and below please use any version below v1.0.0.
Install via Composer:
composer require bmitch/codor --dev
Create a PHPCS ruleset XML (codor.xml or whatever filename you want) file in the root of your project.
<?xml version="1.0" encoding="UTF-8"?>
<ruleset name="Project">
<description>Project Coding Standard</description>
<rule ref="vendor/bmitch/codor/src/Codor/ruleset.xml"/>
</ruleset>Then run it with the command:
vendor/bin/phpcs --standard=codor.xml src
Where src is the location of the source code you want to check.
You may not want to run all the sniffs provided so you can specify which sniffs you want to exclude with the --exclude flag like:
vendor/bin/phpcs --standard=codor.xml --exclude=Codor.ControlStructures.NoElse src
(if you want to exclude multiple just separate them with a comma)
Or you can also specify which sniffs to specifically run:
vendor/bin/phpcs --standard=codor.xml --sniffs=Codor.ControlStructures.NoElse src
Please see the PHPCS documentation:
https://github.com/squizlabs/PHP_CodeSniffer/wiki/Advanced-Usage#ignoring-files-and-folders
Does not allow for any else or elseif statements.
❌
if ($foo) {
return 'bar';
} else {
return 'baz';
}✅
if ($foo) {
return 'bar';
}
return 'baz';Functions/methods must be no more than 20 lines.
❌
public function foo()
{
// more than 20 lines
}✅
public function foo()
{
// no more than 20 lines
}Functions/methods must have no more than 3 parameters.
❌
public function foo($bar, $baz, $bop, $portugal)
{
//
}✅
public function foo($bar, $baz, $bop)
{
//
}Functions/methods must not return null.
❌
public function getAdapter($bar)
{
if ($bar === 'baz') {
return new BazAdapter;
}
return null;
}✅
public function getAdapter($bar)
{
if ($bar === 'baz') {
return new BazAdapter;
}
return NullAdapter;
}Functions/methods cannot have parameters that default to a boolean.
❌
public function getCustomers($active = true)
{
if ($active) {
// Code to get customers from who are active
}
// Code to get all customers
}✅
public function getAllCustomers()
{
// Code to get all customers
}
public function getAllActiveCustomers()
{
// Code to get customers from who are active
}Classes must be no more than 200 lines.
❌
class ClassTooLong
{
// More than 200 lines
}✅
class ClassNotTooLong
{
// No more than 200 lines
}Class constructors must not contain any loops.
❌
public function __construct()
{
for($index = 1; $index < 100; $index++) {
// foo
}
}✅
public function __construct()
{
$this->someMethod();
}
private function someMethod()
{
for($index = 1; $index < 100; $index++) {
// foo
}
}Warns if a class extends another class. Goal is to promote composition over inheritance (https://en.wikipedia.org/wiki/Composition_over_inheritance).
❌
class GasolineCar extends Vehicle
{
//
}
class GasolineVehicle extends Vehicle
{
//
}✅
class Vehicle
{
private $fuel;
public function __construct(FuelInterface $fuel)
{
$this->fuel;
}
}
class Gasoline implements FuelInterface
{
}
$gasolineCar = new Vehicle($gasoline);Final classes should not contain protected methods or variables. Should use private instead.
❌
final class Foo
{
protected $baz;
protected function bar()
{
//
}
}✅
final class Foo
{
private $baz;
private function bar()
{
//
}
}Classes should not instantiate objects. Should use dependency injection.
❌
class NewInConstructor
{
private MyClass $myClass;
public function __construct()
{
$this->myClass = new MyClass();
}
}✅
class NewInConstructor
{
private MyClass $myClass;
public function __construct(MyClass $myClass)
{
$this->myClass = $myClass;
}
}Produces an error if your class uses undeclared member variables. Only warns if class extends another class.
❌
class Foo
{
private function bar()
{
$this->baz = 13;
}
}✅
class Foo
{
private $baz;
private function bar()
{
$this->baz = 13;
}
}Functions/methods cannot contain "And" or "Or". This could be a sign of a function that does more than one thing.
❌
public function validateStringAndUpdateDatabase()
{
// code to validate string
// code to update database
}✅
public function validateString()
{
// code to validate string
}
public function updateDatabase()
{
// code to update database
}Functions/methods cannot have more than 2 level of indentation.
❌
public function foo($collection)
{
foreach ($collection as $bar) {
foreach ($bar as $baz) {
//
}
}
}✅
public function foo($collection)
{
foreach ($collection as $bar) {
$this->process($bar);
}
}
private function process($bar)
{
foreach ($bar as $baz) {
//
}
}Nested if statements are not allowed.
❌
public function allowedToDrink($person)
{
if ($person->age === 19) {
if ($person->hasValidId()) {
return true;
}
}
return false;
}✅
public function allowedToDrink($person)
{
if ($person->age !== 19) {
return false;
}
if (! $person->hasValidId()) {
return false;
}
return true;
}Produces an error if a line contains a ternary operator that could be converted to a Null Coalescing operator.
❌
$username = isset($customer['name']) ? $customer['name'] : 'nobody';✅
$username = $customer['name'] ?? 'nobody';Only allows for 1 line between functions/methods. Any more than 1 will produce an error.
❌
public function foo()
{
//
}
public function bar()
{
//
}✅
public function foo()
{
//
}
public function bar()
{
//
}Prevents you from having a mixed type returned in a doc block.
❌
/**
* @return mixed
*/
public function foo()
{
//
}✅
/**
* @return string
*/
public function foo()
{
//
}Some of the sniff rules can be customized to your liking. For example, if you'd want the Codor.Files.FunctionLength to make sure your functions are no more than 30 lines instead of 20, you can do that. Here's an example of a codor.xml file with that customization:
<?xml version="1.0" encoding="UTF-8"?>
<ruleset name="Project">
<description>Project Coding Standard</description>
<rule ref="vendor/bmitch/codor/src/Codor/ruleset.xml"/>
<rule ref="Codor.Files.FunctionLength">
<properties>
<property name="maxLength" value="30"/>
</properties>
</rule>
</ruleset>Codor.Files.FunctionLengthmaxLength: The maximum number of lines a function/method can have (default = 20).Codor.Files.FunctionParametermaxParameters: The maximum number of parameters a function/method can have (default = 3).Codor.Classes.ClassLengthmaxLength: The maximum number of lines a Class can have (default = 200).Codor.Files.IndentationLevelindentationLimit: Cannot have more than or equal to this number of indentations (default = 2).
- https://github.com/object-calisthenics/phpcs-calisthenics-rules
- https://github.com/slevomat/coding-standard
Please see CONTRIBUTING.md
The MIT License (MIT). Please see License File for more information.