declaration-blank-lines

Mezi metodami jsou dva prázdné řádky, mezi vlastnostmi a konstantami nejvýš jeden, za otevírací závorkou třídy a před zavírací žádný a dokumentační komentář se drží své deklarace.

Opravuje · v presetech dresscode/per, dresscode/psr12, dresscode/nette · pokrývá no_blank_lines_after_class_opening, no_blank_lines_after_phpdoc, NetteCodingStandard.WhiteSpace.FunctionSpacing, SlevomatCodingStandard.Attributes.AttributeAndTargetSpacing, SlevomatCodingStandard.Classes.ConstantSpacing, SlevomatCodingStandard.Classes.EmptyLinesAroundClassBraces, SlevomatCodingStandard.Classes.PropertySpacing, SlevomatCodingStandard.Classes.TraitUseSpacing, Squiz.WhiteSpace.FunctionSpacing

Co pravidlo hlídá

Prázdné řádky mezi deklaracemi jsou to, co dělá třídu čitelnou na první pohled: metody od sebe oddělené výrazně, vlastnosti a konstanty pohromadě, komentář přilepený k tomu, co popisuje. Pravidlo má pro každé takové místo volbu: mezi funkcemi a metodami, v rozhraní zvlášť, před první a za poslední metodou třídy, za otevírací a před zavírací závorkou, kolem use traitů, mezi vlastnostmi, konstantami a případy výčtu, před dokumentovaným členem a mezi dokumentačním komentářem či atributem a deklarací.

Každá volba je počet prázdných řádků, rozsah [min, max] s otevřeným koncem jako null, nebo null, které místo nechá na pokoji. Rozsah se hodí tam, kde chcete připustit dvojí zápis: betweenMembers: [0, 1] dovolí vlastnosti psát těsně pod sebe i oddělené jedním řádkem, ale dva už ne. Počet mimo rozsah pravidlo posune k nejbližší mezi.

Výchozí hodnoty jsou styl dvou prázdných řádků mezi metodami. Preset dresscode/psr12 nastavuje betweenFunctions, betweenFunctionsInInterface, betweenMembers, beforeDocumentedMember a afterPhpdoc na null, protože PSR-12 o počtu řádků mezi metodami nic neříká.

Příklad

class Cart
{

	private array $items = [];  // Expected 0 blank lines before the property, 1 found
	public function add(Item $item): void  // Expected 2 blank lines before the method, 0 found
	{
		$this->items[] = $item;
	}

	public function total(): int  // Expected 2 blank lines before the method, 1 found
	{
		return array_sum($this->items);
	}
}

class Cart
{
	private array $items = [];


	public function add(Item $item): void
	{
		$this->items[] = $item;
	}


	public function total(): int
	{
		return array_sum($this->items);
	}
}

Volby

betweenFunctions

Počet, rozsah nebo null, výchozí 2. Před funkcí nebo metodou a za ní; první a poslední metoda třídy se řídí volbami beforeFirst a afterLast. Platí i pro funkce deklarované mimo třídu.

rules:
	dresscode/declaration-blank-lines:
		betweenFunctions: 1

class Cart
{
	public function add(Item $item): void
	{
	}


	public function total(): int  // Expected 1 blank line before the method, 2 found
	{
	}
}

class Cart
{
	public function add(Item $item): void
	{
	}

	public function total(): int
	{
	}
}

betweenFunctionsInInterface

Počet, rozsah nebo null, výchozí 1. Mezi metodami rozhraní, které nemají tělo, a stačí jim proto menší odstup.

rules:
	dresscode/declaration-blank-lines:
		betweenFunctionsInInterface: 0

interface Storage
{
	public function read(string $key): mixed;

	public function write(string $key, mixed $value): void;  // Expected 0 blank lines before the method, 1 found
}

interface Storage
{
	public function read(string $key): mixed;
	public function write(string $key, mixed $value): void;
}

beforeFirst

Počet, rozsah nebo null, výchozí 0. Před metodou, která je prvním členem třídy.

rules:
	dresscode/declaration-blank-lines:
		beforeFirst: 1

class Cart
{
	public function add(Item $item): void  // Expected 1 blank line before the method, 0 found
	{
	}
}

class Cart
{

	public function add(Item $item): void
	{
	}
}

afterLast

Počet, rozsah nebo null, výchozí 0. Za metodou, která je posledním členem třídy.

rules:
	dresscode/declaration-blank-lines:
		afterLast: 1

class Cart
{
	public function add(Item $item): void
	{
	}
}  // Expected 1 blank line after the method, 0 found

class Cart
{
	public function add(Item $item): void
	{
	}

}

afterOpeningBrace

Počet, rozsah nebo null, výchozí 0. Před prvním členem třídy, pokud to není metoda; pak platí beforeFirst.

rules:
	dresscode/declaration-blank-lines:
		afterOpeningBrace: 1

class Cart
{
	private array $items = [];  // Expected 1 blank line before the property, 0 found
}

class Cart
{

	private array $items = [];
}

beforeClosingBrace

Počet, rozsah nebo null, výchozí 0. Za posledním členem třídy, pokud to není metoda; pak platí afterLast.

rules:
	dresscode/declaration-blank-lines:
		beforeClosingBrace: 1

class Cart
{
	private array $items = [];
}  // Expected 1 blank line before the closing brace, 0 found

class Cart
{
	private array $items = [];

}

betweenTraitUses

Počet, rozsah nebo null, výchozí 0. Mezi use traitů na začátku třídy.

class Cart
{
	use Countable;

	use Serializable;  // Expected 0 blank lines before the trait use, 1 found
}

class Cart
{
	use Countable;
	use Serializable;
}

afterTraitUses

Počet, rozsah nebo null, výchozí 1. Před členem, který následuje za use traitů, pokud to není metoda; pak platí betweenFunctions.

class Cart
{
	use Countable;
	private array $items = [];  // Expected 1 blank line before the property, 0 found
}

class Cart
{
	use Countable;

	private array $items = [];
}

betweenMembers

Počet, rozsah nebo null, výchozí [0, 1]. Mezi vlastnostmi, konstantami a případy výčtu bez dokumentačního komentáře a atributu. Výchozí rozsah dovolí členy psát těsně pod sebe i oddělené jedním řádkem.

class Cart
{
	private array $items = [];
	private int $count = 0;


	private ?Customer $customer = null;  // Expected at most 1 blank line before the property, 2 found
}

class Cart
{
	private array $items = [];
	private int $count = 0;

	private ?Customer $customer = null;
}

S pevným počtem musí být odstup všude stejný:

rules:
	dresscode/declaration-blank-lines:
		betweenMembers: 1

class Cart
{
	private array $items = [];
	private int $count = 0;  // Expected 1 blank line before the property, 0 found
}

class Cart
{
	private array $items = [];

	private int $count = 0;
}

beforeDocumentedMember

Počet, rozsah nebo null, výchozí 1. Před vlastností, konstantou nebo případem výčtu, který má dokumentační komentář nebo atribut; komentář potřebuje odstup od předchozího člena, aby bylo vidět, ke kterému patří.

class Cart
{
	private array $items = [];
	/** @var int<0, max> */
	private int $count = 0;  // Expected 1 blank line before the property, 0 found
}

class Cart
{
	private array $items = [];

	/** @var int<0, max> */
	private int $count = 0;
}

afterPhpdoc

Počet, rozsah nebo null, výchozí 0. Mezi dokumentačním komentářem nebo atributem a deklarací, ke které patří.

class Cart
{
	/**
	 * Adds an item.
	 */

	public function add(Item $item): void  // Expected 0 blank lines after the doc comment, 1 found
	{
	}
}

class Cart
{
	/**
	 * Adds an item.
	 */
	public function add(Item $item): void
	{
	}
}

Související pravidla

• header-blank-lines prázdné řádky v hlavičce souboru kolem declare, namespace a importů
• body-blank-lines prázdný řádek za otevírací závorkou těla funkce nebo řídicí struktury
• statement-blank-lines prázdné řádky kolem příkazů jako return

Zdroj

Třída DeclarationBlankLinesRule, fixtury declaration-blank-lines.