Clarity Rules

This document details the rules available in the Clarity category.

Available Rules

Rule	Code
Explicit Octal	explicit-octal
No Empty	no-empty
No Hash Emoji	no-hash-emoji
No Multi Assignments	no-multi-assignments
No Shorthand Ternary	no-shorthand-ternary
Str Contains	str-contains
Str Starts With	str-starts-with
Tagged FIXME	tagged-fixme
Tagged TODO	tagged-todo
Valid Docblock	valid-docblock

---

explicit-octal

Detects implicit octal numeral notation and suggests replacing it with explicit octal numeral notation.

Requirements

• PHP Version: PHP >= 8.1.0

Configuration

Option	Type	Default
enabled	boolean	true
level	string	"warning"

Examples

Correct Code

<?php

$a = 0o123;

Incorrect Code

<?php

$a = 0123;

---

no-empty

Detects the use of the empty() construct.

The empty() language construct can lead to ambiguous and potentially buggy code due to loose and counterintuitive definition of emptiness. It fails to clearly convey developer's intent or expectation, making it preferable to use explicit checks.

Configuration

Option	Type	Default
enabled	boolean	true
level	string	"error"

Examples

Correct Code

<?php

if ($myArray === []) {
    // ...
}

Incorrect Code

<?php

if (!empty($myArray)) {
    // ...
}

---

no-hash-emoji

Discourages usage of the #️⃣ emoji in place of the ASCII #.

While PHP allows the use of emojis in comments, it is generally discouraged to use them in place of the normal ASCII # symbol. This is because it can confuse readers and may break external tools that expect the normal ASCII # symbol.

Configuration

Option	Type	Default
enabled	boolean	true
level	string	"warning"

Examples

Correct Code

<?php

# This is a comment

#[MyAttribute]
class Foo {}

Incorrect Code

<?php

#️⃣ This is a comment

#️⃣[MyAttribute] <- not a valid attribute
class Foo {}

---

no-multi-assignments

Flags any instances of multiple assignments in a single statement. This can lead to confusion and unexpected behavior, and is generally considered poor practice.

Configuration

Option	Type	Default
enabled	boolean	true
level	string	"warning"

Examples

Correct Code

<?php

$b = 0;
$a = $b;

Incorrect Code

<?php

$a = $b = 0;

---

no-shorthand-ternary

Detects the use of the shorthand ternary and elvis operators.

Both shorthand ternary operator ($a ? : $b) and elvis operator ($a ?: $b) relies on loose comparison.

Configuration

Option	Type	Default
enabled	boolean	true
level	string	"warning"

Examples

Correct Code

<?php

$value = $foo ?? $default;
$value = $foo ? $foo : $default;

Incorrect Code

<?php
$value = $foo ?: $default;
$value = $foo ? : $default;

---

str-contains

Detects strpos($a, $b) !== false comparisons and suggests replacing them with str_contains($a, $b) for improved readability and intent clarity.

Requirements

• PHP Version: PHP >= 8.0.0

Configuration

Option	Type	Default
enabled	boolean	true
level	string	"warning"

Examples

Correct Code

<?php

$a = 'hello world';
$b = 'world';

if (str_contains($a, $b)) {
    echo 'Found';
}

Incorrect Code

<?php

$a = 'hello world';
$b = 'world';

if (strpos($a, $b) !== false) {
    echo 'Found';
}

---

str-starts-with

Detects strpos($a, $b) === 0 comparisons and suggests replacing them with str_starts_with($a, $b) for improved readability and intent clarity.

Requirements

• PHP Version: PHP >= 8.0.0

Configuration

Option	Type	Default
enabled	boolean	true
level	string	"warning"

Examples

Correct Code

<?php

$a = 'hello world';
$b = 'hello';
if (str_starts_with($a, $b)) {
    echo 'Found';
}

Incorrect Code

<?php

$a = 'hello world';
$b = 'hello';
if (strpos($a, $b) === 0) {
    echo 'Found';
}

---

tagged-fixme

Detects FIXME comments that are not tagged with a user or issue reference. Untagged FIXME comments are not actionable and can be easily missed by the team. Tagging the FIXME comment with a user or issue reference ensures that the issue is tracked and resolved.

Configuration

Option	Type	Default
enabled	boolean	true
level	string	"warning"

Examples

Correct Code

<?php

// FIXME(@azjezz) This is a valid FIXME comment.
// FIXME(azjezz) This is a valid FIXME comment.
// FIXME(#123) This is a valid FIXME comment.

Incorrect Code

<?php

// FIXME: This is an invalid FIXME comment.

---

tagged-todo

Detects TODO comments that are not tagged with a user or issue reference. Untagged TODOs can be difficult to track and may be forgotten. Tagging TODOs with a user or issue reference makes it easier to track progress and ensures that tasks are not forgotten.

Configuration

Option	Type	Default
enabled	boolean	true
level	string	"warning"

Examples

Correct Code

<?php

// TODO(@azjezz) This is a valid TODO comment.
// TODO(azjezz) This is a valid TODO comment.
// TODO(#123) This is a valid TODO comment.

Incorrect Code

<?php

// TODO: This is an invalid TODO comment.

---

valid-docblock

Checks for syntax errors in docblock comments. This rule is disabled by default because it can be noisy and may not be relevant to all codebases.

Configuration

Option	Type	Default
enabled	boolean	true
level	string	"note"

Examples

Correct Code

<?php

/**
 * @param int $a
 * @return int
 */
function foo($a) {
    return $a;
}

Incorrect Code

<?php

/**
 @param int $a
    */
function foo($a) {
    return $a;
}

---