index0h / php-conventions Goto Github PK

// @codingStandardsIgnoreStart
use VendorWithVerlyLongName\ProjectrWithVerlyLongName\ServicesWithVerlyLongName\ServiceFolderWithVerlyLongName\ClassWithVerlyLongName;
// @codingStandardsIgnoreStop

// Правильно
$varName      = 'varName';
$variableName = 'variableName';

// Неправильно
$varName = 'varName';
$variableName = 'variableName';

// Правильно
$varName                            = 'varName';
$secondVariableWithVeryLongNameHere =
    '123456790123456790123456790123456790123456790123456790123456790123456790123456790';

// Неправильно
$varName                            = 'varName';
$secondVariableWithVeryLongNameHere
    = '123456790123456790123456790123456790123456790123456790123456790123456790123456790';

// Правильно
$firstVariableWithVeryLongNameHere = 'varName';

$variableName = '123456790123456790123456790123456790123456790123456790123456790123456790123456790';

// Правильно
[
    'elementName'     => 'elementName',
    'longNameElement' => 'longNameElement',
]

// Неправильно
[
    'elementName' => 'elementName',
    'longNameElement' => 'longNameElement',
]

// Правильно
[
    'elementName'                       => 'elementName',
    'secondElementWithVeryLongNameHere' =>
        '123456790123456790123456790123456790123456790123456790123456790123456790123456790',
]

// Неправильно
[
    'elementName'                       => 'elementName',
    'secondElementWithVeryLongNameHere'
        => '123456790123456790123456790123456790123456790123456790123456790123456790123456790',
]

// Правильно
[
    'firstElementWithVeryLongNameHere' => 'elementName',

    'elementName' => '123456790123456790123456790123456790123456790123456790123456790123456790123456790',
]

// Правильно
[
    'firstElement'  => 'firstElement',
    'secondElement' => 'secondElement',
]

// Неправильно
[
    'firstElement'  => 'firstElement',
    'secondElement' => 'secondElement'
]

// Правильно
['firstElement' => 'firstElement', 'secondElement' => 'secondElement']

// Неправильно
['firstElement' => 'firstElement', 'secondElement' => 'secondElement',]

// Правильно
$this->firstMethod();

// Неправильно
$this
    ->firstMethod();

// Правильно
$this
    ->firstMethod()
    ->secondMethod();

// Неправильно
$this->firstMethod()->secondMethod();

// Неправильно
$this
    ->firstMethod()->secondMethod();

// Правильно
$this
    ->firstMethod()
    ->thirdMethod(
        $firstArgument,
        $secondArgument,
        $thirdArgument,
        $fourthArgument,
        $fifthArgument,
        $sixArgument
    );

// Неправильно
$this->firstMethod()->thirdMethod(
    $firstArgument,
    $secondArgument,
    $thirdArgument,
    $fourthArgument,
    $fifthArgument,
    $sixArgument
);

// Правильно
$count = 5;

if ($count === 5) {
// ...
}

// ...

// Неправильно
$count = 5; // Отсутствует перевод строки
if ($count === 5) {
// ...
}
$length = 12; // Отсутствует перевод строки
// ...

// Правильно
{
    if ($count === 5) {
    // ...
    }
}

// Неправильно
{

    // Лишняя пустая строка
    if ($count === 5) {
    // ...
    }
    // Лишняя пустая строка
}

// Правильно
public function incrementProductPriceByName(string $productName, float $price): bool
{
// ...

// Неправильно
/**
 * @param string $productName
 * @param float  $price
 * @return bool
 */
public function incrementProductPriceByName(string $productName, float $price): bool
{
// ...

// Правильно
/** 
 * @param array $parsedUrl
 * @phan-param array{scheme:string,host:string,path:string} $parsedUrl
 * @psalm-param array{scheme:string,host:string,path:string} $parsedUrl  
*/
public function showUrl(string $label, array $parsedUrl, string $host): string
{

// Правильно (< php 7.4)
/** @var string */
private $productName;

// Неправильно (< php 7.4)
private $productName;

// Правильно (php 7.4+)
private ?string $productName;

// Правильно (php 7.4+)
/** @var string|null Contains product name */
private ?string $productName;

// Неправильно (php 7.4+)
/** @var string|null */
private ?string $productName;

// Правильно
/**
 * @param string[] $productNames
 */
public function incrementProductPricesByNames(array $productNames, float $price): bool
{
// ...

// Неправильно
/**
 * @param array $productNames
 */
public function incrementProductPricesByNames(array $productNames, float $price): bool
{
// ...

// Правильно
/**
 * @param string|int $stringOrIntArgument
 * @return float|string|object
 */
public function mixedMethod($stringOrIntArgument)
{
// ...

// Неправильно
/**
 * @param mixed $stringOrIntArgument
 * @return mixed
 */
public function mixedMethod($stringOrIntArgument)
{
// ...

$rows = [
    [
        'id'        => 1,
        'createdAt' => new \DateTimeImmutable(),
    ],
    [
        'id'        => 2,
        'createdAt' => new \DateTimeImmutable(),
    ],
    // ...
];

foreach ($rows as $row) {
    /** @var int $id */
    $id = $row['id'];
    /** @var \DateTimeImmutable $createdAt */
    $createdAt = $row['createdAt'];
    // ...
}

/** @var string[]|null */
private $names;

/** @var int|null */
private $count;

/** @var string[]|null */
private ?array $names;

private ?int $count;

// Неправильно
/** @param string[] $userNames */
public function saveUserNames(array $userNames): void

// Правильно
/**
 * @param string[] $userNames
 */
public function saveUserNames(array $userNames): void

// Правильно
/** @var string[] */
private $userNames;

// Неправильно
/** @var string[] */
private $data;

// Правильно
/** @var string[] */
private $userNames;

/** @var int[] */
private $userIds;

// Неправильно
/** @var string[] */
private $userNames;
/** @var int[] */
private $userIds;

// Правильно
{
    /** @var string[] */
    private $userNames;

// Неправильно
{

    /** @var string[] */
    private $userNames;

// Правильно
    /** @var string[] */
    private $userNames;
}

// Неправильно
    /** @var string[] */
    private $userNames;

}

// Правильно
public function findUserById(int $id): ?User

// Неправильно
public function find(int $id): ?User

// Правильно
public function findUserById(int $id): ?User
// ...
}

public function findUserByName(string $name): ?User
// ...
}

// Неправильно
public function findUserById(int $id): ?User
// ...
}
public function findUserByName(string $name): ?User
// ...
}

// Правильно
{
    public function findUserById(int $id): ?User

// Неправильно
{

    public function findUserById(int $id): ?User

// Правильно
    public function findUserById(int $id): ?User
}

// Неправильно
    public function findUserById(int $id): ?User

}

public function firstExample(string $first, ?int $second, bool $third = false, float ...$fourth): string
// ...
public function secondExample(?int $second, bool $third = false, float ...$fourth): string
// ...
public function thirdExample(bool $third = false, float ...$fourth): string

// Правильно
public function concatStrings(string ...$parts): string

// Неправильно
/**
 * @param string $parts
 */
public function concatStrings(array $parts): string

echo 5 + '5abc5';
// 10

if ('abc' == 0) {
    echo 'wat';
}

// wat

switch ('abc') {
    case 0:
        echo 'wat';

        break;
}

// wat

$rows = [0, null, ''];

while ($row = next($rows)) {
    printf("\$row = %s\n", var_dump($row, true));
}

// Ничего не выведет

// Без @ будет ошибка:
// Warning: fopen(path/to/not/exists/file): failed to open stream: No such file or directory
$file = @fopen('path/to/not/exists/file', 'r');

if ($file === false) {
    throw new \RuntimeException('Could not open file: "path/to/not/exists/file"');
}

// Неправильно
$this->{$methodName}($argument);

$externalServiceGenerateExpiredAt = function (\DateTime $createdAt): \DateTime {
    return $createdAt->modify('3 days');
};

$createdAt = new \DateTime('2019-01-01');
$expiredAt = $externalServiceGenerateExpiredAt($createdAt);

printf("createdAt: %s, expiredAt: %s", $createdAt->format('Y-m-d'), $expiredAt->format('Y-m-d'));

// createdAt: 2019-01-04, expiredAt: 2019-01-04

// Для данного метода ДОЛЖНО быть 3 теста.
// 1. Число $number кратно $divider, что бы проверить корректность преобразование типа.
// Например `divide(4, 2);`.
// 2. Число $number не кратно $divider. Например `divide(1, 2);`.
// 3. Число $divider равно 0. Например `divide(3, 0);`.
public function divide(int $number, int $divider): float.
{
    if ($divider === 0) {
        throw new \InvalidArgumentException('Argument "$divider" must be not zero');
    }

    return (float) $number / $divider;
}

// Для данного метода ДОЛЖНО быть 4 теста.
// 1. Название команды соответствует `self::FIRST_COMMAND`.
// 2. Название команды соответствует `self::SECOND_COMMAND`.
// 3. Название команды - пустая строка.
// 4. Команда не найдена.
public function execute(string $commandName): void
{
    if (empty($commandName)) {
        throw new \InvalidArgumentException('Argument "$commandName" must be not empty');
    }

    switch ($commandName) {
        case self::FIRST_COMMAND:
            $this->firstCommand();

            break;
        case self::SECOND_COMMAND:
            $this->secondCommand();

            break;
        default:
            throw new \DomainException(sprintf('Unknown command: "%s"', $commandName));
    }
}

<?php
// Service/UserRegistrator.php 

declare(strict_types = 1);

namespace Vendor\Project\Service;

use Doctrine\ORM\EntityManagerInterface;
use Psr\Log\LoggerInterface;
use Symfony\Component\Security\Core\Encoder\PasswordEncoderInterface;
use Symfony\Component\Security\Core\User\User;
use Symfony\Component\Security\Core\User\UserInterface;

class UserRegistrator
{
    /** @var PasswordEncoderInterface */
    private $passwordEncoder;

    /** @var LoggerInterface */
    private $logger;

    /** @var string */
    private $salt;

    public function __construct(PasswordEncoderInterface $passwordEncoder, LoggerInterface $logger, string $salt)
    {
        if (empty($salt)) {
            throw new \InvalidArgumentException('Variable "$salt" must be not empty');
        }

        $this->passwordEncoder = $passwordEncoder;
        $this->logger          = $logger;
        $this->salt            = $salt;
    }

    public function register(EntityManagerInterface $entityManager, string $userName, string $password): UserInterface
    {
        if (preg_match('/^[a-z][a-z0-9_]{5,254}$/i', $userName)) {
            throw new \InvalidArgumentException(
                sprintf('Variable "$userName" is invalid, actual value: "%s"', $userName)
            );
        } elseif (empty($password)) {
            throw new \InvalidArgumentException('Variable "$password" must be not empty');
        }

        $this->logger->info(sprintf('Register user: "%s"', $userName));

        try {
            $encodedPassword = $this->passwordEncoder->encodePassword($password, $this->salt);
            $user            = new User($userName, $encodedPassword);

            $entityManager->persist($user);
            $entityManager->flush();

            return $user;
        } catch (\Throwable $exception) {
            $this->logger->error($exception->getMessage(), ['exception' => $exception]);

            throw $exception;
        }
    }
}

<?php
// Tests/Service/UserRegistratorTest.php 

declare(strict_types = 1);

namespace Vendor\Project\Tests\Service;

use Doctrine\ORM\EntityManagerInterface;
use PHPUnit\Framework\MockObject\MockObject;
use PHPUnit\Framework\TestCase;
use Psr\Log\LoggerInterface;
use Symfony\Component\Security\Core\Encoder\PasswordEncoderInterface;
use Symfony\Component\Security\Core\User\UserInterface;
use Vendor\Project\Service\UserRegistrator;

class UserRegistratorTest extends TestCase
{
    public function testConstructorWithEmptySalt(): void
    {
        $this->expectException(\InvalidArgumentException::class);
        $this->expectExceptionMessage('Variable "$salt" must be not empty');

        $salt = '';

        /** @var PasswordEncoderInterface|MockObject $passwordEncoder */
        $passwordEncoder = $this->createMock(PasswordEncoderInterface::class);
        /** @var LoggerInterface|MockObject $logger */
        $logger = $this->createMock(LoggerInterface::class);

        new UserRegistrator($passwordEncoder, $logger, $salt);
    }

    public function testRegister(): void
    {
        $salt            = 'salt';
        $userName        = 'userName';
        $password        = 'password';
        $encodedPassword = 'encodedPassword';

        /** @var PasswordEncoderInterface|MockObject $passwordEncoder */
        $passwordEncoder = $this->createMock(PasswordEncoderInterface::class);
        /** @var LoggerInterface|MockObject $logger */
        $logger = $this->createMock(LoggerInterface::class);

        /** @var EntityManagerInterface|MockObject $entityManager */
        $entityManager = $this->createMock(EntityManagerInterface::class);

        $userRegistrator = new UserRegistrator($passwordEncoder, $logger, $salt);

        $entityManagerIncrement = 0;

        $logger
            ->expects($this->once())
            ->method('info')
            ->with(sprintf('Register user: "%s"', $userName));

        $passwordEncoder
            ->expects($this->once())
            ->method('encodePassword')
            ->with($password, $salt)
            ->willReturn($encodedPassword);

        $entityManager
            ->expects($this->at($entityManagerIncrement++))
            ->method('persist')
            ->with(
                $this->callback(
                    function (UserInterface $user) use ($encodedPassword, $userName): bool {
                        $this->assertSame($userName, $user->getUsername());
                        $this->assertSame($encodedPassword, $user->getPassword());

                        return true;
                    }
                )
            );

        /** @noinspection PhpUnusedLocalVariableInspection */
        $entityManager
            ->expects($this->at($entityManagerIncrement++))
            ->method('flush');

        $logger
            ->expects($this->never())
            ->method('error');

        $user = $userRegistrator->register($entityManager, $userName, $password);

        $this->assertSame($userName, $user->getUsername());
        $this->assertSame($encodedPassword, $user->getPassword());
    }

    public function testRegisterWithInvalidUserName(): void
    {
        $this->expectException(\InvalidArgumentException::class);
        $this->expectExceptionMessage('Variable "$userName" is invalid, actual value: "*"');

        $salt     = 'salt';
        $userName = '*';
        $password = 'password';

        /** @var PasswordEncoderInterface|MockObject $passwordEncoder */
        $passwordEncoder = $this->createMock(PasswordEncoderInterface::class);
        /** @var LoggerInterface|MockObject $logger */
        $logger = $this->createMock(LoggerInterface::class);

        /** @var EntityManagerInterface|MockObject $entityManager */
        $entityManager = $this->createMock(EntityManagerInterface::class);

        $userRegistrator = new UserRegistrator($passwordEncoder, $logger, $salt);

        $logger
            ->expects($this->never())
            ->method('info');

        $passwordEncoder
            ->expects($this->never())
            ->method('encodePassword');

        $entityManager
            ->expects($this->never())
            ->method('persist');

        $entityManager
            ->expects($this->never())
            ->method('flush');

        $logger
            ->expects($this->never())
            ->method('error');

        $userRegistrator->register($entityManager, $userName, $password);
    }

    public function testRegisterWithInvalidPassword(): void
    {
        $this->expectException(\InvalidArgumentException::class);
        $this->expectExceptionMessage('Variable "$password" must be not empty');

        $salt     = 'salt';
        $userName = 'userName';
        $password = '';

        /** @var PasswordEncoderInterface|MockObject $passwordEncoder */
        $passwordEncoder = $this->createMock(PasswordEncoderInterface::class);
        /** @var LoggerInterface|MockObject $logger */
        $logger = $this->createMock(LoggerInterface::class);

        /** @var EntityManagerInterface|MockObject $entityManager */
        $entityManager = $this->createMock(EntityManagerInterface::class);

        $userRegistrator = new UserRegistrator($passwordEncoder, $logger, $salt);

        $logger
            ->expects($this->never())
            ->method('info');

        $passwordEncoder
            ->expects($this->never())
            ->method('encodePassword');

        $entityManager
            ->expects($this->never())
            ->method('persist');

        $entityManager
            ->expects($this->never())
            ->method('flush');

        $logger
            ->expects($this->never())
            ->method('error');

        $userRegistrator->register($entityManager, $userName, $password);
    }

    public function testRegisterWithUnexpectedDbException(): void
    {
        $this->expectException(\Exception::class);
        $this->expectExceptionMessage('UnexpectedException');

        $salt            = 'salt';
        $userName        = 'userName';
        $password        = 'password';
        $encodedPassword = 'encodedPassword';
        $exception       = new \Exception('UnexpectedException');
        $logContext      = ['exception' => $exception];

        /** @var PasswordEncoderInterface|MockObject $passwordEncoder */
        $passwordEncoder = $this->createMock(PasswordEncoderInterface::class);
        /** @var LoggerInterface|MockObject $logger */
        $logger = $this->createMock(LoggerInterface::class);

        /** @var EntityManagerInterface|MockObject $entityManager */
        $entityManager = $this->createMock(EntityManagerInterface::class);

        $userRegistrator = new UserRegistrator($passwordEncoder, $logger, $salt);

        $entityManagerIncrement = 0;

        $logger
            ->expects($this->once())
            ->method('info')
            ->with(sprintf('Register user: "%s"', $userName));

        $passwordEncoder
            ->expects($this->once())
            ->method('encodePassword')
            ->with($password, $salt)
            ->willReturn($encodedPassword);

        $entityManager
            ->expects($this->at($entityManagerIncrement++))
            ->method('persist')
            ->with(
                $this->callback(
                    function (UserInterface $user) use ($encodedPassword, $userName): bool {
                        $this->assertSame($userName, $user->getUsername());
                        $this->assertSame($encodedPassword, $user->getPassword());

                        return true;
                    }
                )
            );

        /** @noinspection PhpUnusedLocalVariableInspection */
        $entityManager
            ->expects($this->at($entityManagerIncrement++))
            ->method('flush')
            ->willThrowException($exception);

        $logger
            ->expects($this->once())
            ->method('error')
            ->with($exception->getMessage(), $logContext);

        $userRegistrator->register($entityManager, $userName, $password);
    }
}

public function testLogMessage(): void
// ...
public function testLogMessageWithEmptyMessage(): void
// ...
public function testLogMessageWithEmptyMessageAndEmtyContext(): void
// ...
public function testLogMessageWithInvalidContext(): void

/** @var PasswordEncoderInterface|MockObject $passwordEncoder */
$passwordEncoder = $this->createMock(PasswordEncoderInterface::class);
/** @var LoggerInterface|MockObject $logger */
$logger = $this->createMock(LoggerInterface::class);

$mockObject
    ->expects($this->never())
    ->method('methodName');

$mockObject
    ->expects($this->once())    // Или `->expects($this->at($mockObjectIncrement++))`
    ->method('methodName')
    ->with(...$methodArguments)
    ->willReturn($methodResult) // Или `->willReturnSelf();`

$mockObject
    ->expects($this->once())    // Или `->expects($this->at($mockObjectIncrement++))`
    ->method('methodName')
    ->willReturn($methodResult) // Или `->willReturnSelf();`

$mockObject
    ->expects($this->once())    // Или `->expects($this->at($mockObjectIncrement++))`
    ->method('methodName')
    ->with(...$methodArguments)
    ->willThrowException($exception);

$mockObject
    ->expects($this->once()) // Или `->expects($this->at($mockObjectIncrement++))`
    ->method('methodName')
    ->willThrowException($exception);

// Правильно
/** @var JsonResponse|Response $response */
$response = $action->run(/* ... */);

$this->assertSame($expectedContent, $response->getContent());
$this->assertSame(Response::HTTP_OK, $response->getStatusCode());
$this->assertInstanceOf(JsonResponse::class, $response);

// Неправильно
// В случае возникновения ошибки не будет ясно, что же за ошибка произошла, вместо этого получим только несоответствие
// типа $response, или статус кода.
/** @var JsonResponse|Response $response */
$response = $action->run(/* ... */);

$this->assertInstanceOf(JsonResponse::class, $response);
$this->assertSame(Response::HTTP_OK, $response->getStatusCode());
$this->assertSame($expectedContent, $response->getContent());

// Правильно
$exceptionContext = $object->method(/* ... */);

$this->assertIsArray($exceptionContext);
$this->assertNotEmpty($exceptionContext);
$this->assertArrayHasKey('exception', $exceptionContext);
$this->assertInstanceOf(\Exception::class, $exceptionContext['exception']);
$this->assertSame($expectedExceptionMessage, $exceptionContext['exception']->getMessage());

// Неправильно
$exceptionContext = $object->method(/* ... */);

$this->assertSame($expectedExceptionMessage, $exceptionContext['exception']->getMessage());

// Правильно
$this->assertSame($expectedString, $actualString);

// Неправильно
$this->assertSame(true, $expectedString === $actualString);

// Неправильно
$this->assertTrue($expectedString === $actualString);

// Правильно
$this->assertStringStartsWith($expectedPrefix, $actualString);

// Неправильно
$this->assertSame(0, strpos($actualString, $expectedPrefix));

// Правильно
$this->assertTrue($actualBool);

// Неправильно
$this->assertTrue($actualBool === true);

// Неправильно
$this->assertSame(true, $actualBool);

// Правильно
$userRepository
    ->expects($this->once())
    ->method('findByGroup')
    ->with(
        $this->callback(
            function (Group $group) use ($groupId, $groupName): bool {
                $this->assertSame($groupId, $group->getId());
                $this->assertSame($groupName, $group->getName());
                
                return true;
            }
        )
    )
    ->willReturn($users);

// Неправильно
$userRepository
    ->expects($this->once())
    ->method('findByGroup')
    ->with(
        $this->callback(
            function (Group $group) use ($groupId, $groupName): bool {
                // Если следующая проверка не выполнится, в лог будет добавлено сообщение о том, что аргумент не
                // прошел проверку. Информация о том, какая из частей этой проверки дала ложный результат, и какие
                // в принципе значения сравнивались, будет потеряна.
                return $group->getId() === $groupId && $group->getName() === $groupName;
            }
        )
    )
    ->willReturn($users);

// Правильно
$expected = 5;
$actual   = 5;

$this->assertSame($expected, $actual);

// Неправильно
$expected = 5;
$actual   = 5;

$this->assertEqual($expected, $actual);

// Правильно
$expected = 5;
$actual   = 4.5;

$this->assertEqual($expected, $actual, '', 1);

$expected = new \DateTimeImmutable('2019-01-01 10:20:30');
$actual   = new \DateTimeImmutable('2019-01-01 10:20:30');

$this->assertSame($expected->getTimestamp(), $actual->getTimestamp());

$expected = new \DateTimeImmutable();
$actual   = new \DateTimeImmutable();

$this->assertEqual($expected->getTimestamp(), $actual->getTimestamp(), '', 2);