Code Odor Sniffer

👃 💩 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

What is it?

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.

Compatibility

• PHP 7.1+ please use v1.0.0 and above.
• PHP 5.6 and below please use any version below v1.0.0.

How to Install?

Install via Composer:

composer require bmitch/codor --dev

How to Use?

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.

Omitting Sniffs

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)

Running Specific Sniffs

Or you can also specify which sniffs to specifically run:

vendor/bin/phpcs --standard=codor.xml --sniffs=Codor.ControlStructures.NoElse src

Suppressing the sniffs on specific pieces of code

Please see the PHPCS documentation:
https://github.com/squizlabs/PHP_CodeSniffer/wiki/Advanced-Usage#ignoring-files-and-folders

Sniffs Included

Codor.ControlStructures.NoElse

Does not allow for any else or elseif statements.

❌

if ($foo) {
    return 'bar';
} else {
    return 'baz';
}

✅

if ($foo) {
    return 'bar';
}
return 'baz';

Codor.Files.FunctionLength

Functions/methods must be no more than 20 lines.

❌

public function foo()
{
    // more than 20 lines
}

✅

public function foo()
{
    // no more than 20 lines
}

Codor.Files.FunctionParameter

Functions/methods must have no more than 3 parameters.

❌

public function foo($bar, $baz, $bop, $portugal)
{
    // 
}

✅

public function foo($bar, $baz, $bop)
{
    // 
}

Codor.Files.ReturnNull

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;
}

Codor.Files.MethodFlagParameter

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
}

Codor.Classes.ClassLength

Classes must be no more than 200 lines.

❌

class ClassTooLong
{
    // More than 200 lines
}

✅

class ClassNotTooLong
{
    // No more than 200 lines
}

Codor.Classes.ConstructorLoop

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

Codor.Classes.Extends

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);

Codor.Classes.FinalPrivate

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()
    {
        //
    }
}

Codor.Classes.NewInstance

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;
    }
}

Codor.Classes.PropertyDeclaration

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;
    }
}

Codor.Files.FunctionNameContainsAndOr

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
}

Codor.Files.IndentationLevel

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) {
        //
    }
}

Codor.ControlStructures.NestedIf

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;
}

Codor.Syntax.NullCoalescing

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';

Codor.Syntax.LinesAfterMethod

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()
{
    //
}

Codor.TypeHints.MixedReturnType

Prevents you from having a mixed type returned in a doc block.

❌

/**
 * @return mixed
 */
public function foo()
{
    //
}

✅

/**
 * @return string
 */
public function foo()
{
    //
}

Customizing Sniffs

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>

Customizations Available

• Codor.Files.FunctionLength
• maxLength: The maximum number of lines a function/method can have (default = 20).
• Codor.Files.FunctionParameter
• maxParameters: The maximum number of parameters a function/method can have (default = 3).
• Codor.Classes.ClassLength
• maxLength: The maximum number of lines a Class can have (default = 200).
• Codor.Files.IndentationLevel
• indentationLimit: Cannot have more than or equal to this number of indentations (default = 2).

Similar Packages

• https://github.com/object-calisthenics/phpcs-calisthenics-rules
• https://github.com/slevomat/coding-standard

Contributing

Please see CONTRIBUTING.md

License

The MIT License (MIT). Please see License File for more information.