Полезные практики написания поддерживаемого кода на PHP
Привет, меня зовут Алексей и я должен признаться, я PHP разработчик. Последние несколько лет плотно занимаюсь проектами на symfony и решил поделиться с сообществом практиками, которые стараюсь соблюдать при работе.
Многие из них довольно спорные, для дискуссии добро пожаловать в комментарии.
1. Зависимости в di указываем явно
Явное лучше неявного. При описании классов не полагаемся на магию symfony di. Вообще мне кажется, что autowiring довольно вредная практика. При явном описании гораздо проще и быстрее при чтении кода понимать какие зависимости использует класс.
Плохо:
App\Services\MyService: ~
Хорошо:
app.services.my_service:
class: App\Services\MyService
arguments:
- '@doctrine.orm.entity_manager'
- '@app.services.my_service.dependency'
2. В DI подставляем реализации, а не интерфейсы
Так повышается читабельность и поощряется множественные имплементации интерфейсов.
Плохо:
app.services.my_service:
class: App\Services\MyService
arguments:
- '@App\OtherService\Producer\ProducerInterface'
App\OtherService\Producer\ProducerInterface:
alias: App\OtherService\Producer\Amqp
Хорошо:
app.services.my_service:
class: App\Services\MyService
arguments:
- '@app.other_service.producer'
app.other_service.producer:
class: App\OtherService\Producer\Amqp
3. Не надо пробрасывать в классы весь контейнер целиком
Плохо:
final class MyService implements MyServiceInterface
{
public function __construct(private readonly ContainerInterface $container) {}
public function doSomething()
{
$producer = $this->container->get('app.other_service.producer');
$producer->publish();
}
}
Хорошо:
final class MyService implements MyServiceInterface
{
public function __construct(private readonly ProducerInterface $producer) {}
public function doSomething()
{
$producer->publish();
}
}
4. Каждый класс закрывается интерфейсом
Позволяет разрабатывать отталкиваясь от интерфейса. Если в месте использования
класса по какой-то причине не подходит его реализация, его легко заменить другой.
final class MyService implements MyServiceInterface
{
// ...
}
5. Чем меньше методов в интерфейсе, тем лучше.
Большие интерфейсы сложнее поддерживать и реализовать. Нарушается принцип единственной ответственности.
Плохо:
interface SomeEntityInterface
{
public function getId(): int;
public function getName(): int;
public function getAge(): int;
}
Хорошо:
interface IdAwareInterface
{
public function getId(): int;
}
interface NameAwareInterface
{
public function getName(): int;
}
interface AgeAwareInterface
{
public function getAge(): int;
}
6. В интерфейсах указываем какие exception могут быть выброшены
Кроме этих exceptions никакие другие выбрасываться не должны. Если у интерфейса нет блока @throws — значит в реализации все exception должны быть обработаны.
7. Максимально строгая типизация
Используем strict_types=1. Типы указываем максимально жестко.
Плохо:
public function doSomething(mixed $id)
{
return $id;
}
Хорошо:
public function doSomething(int $id)
{
return $id;
}
8. Флаги в аргументах функций
Нарушается принцип единственной ответственности. Отдельные классы проще тестировать, можно использовать в разных сценариях с помощью композиции.
Плохо:
final class SomeService {
public function doSomething($force = false)
{
if ($force) {
return $this->doForce()
}
return $this->do()
}
}
Хорошо:
final class ForceService {
public function doSomething()
{
return $this->doForce();
}
}
9. Количество аргументов в функции максимум 3
Если аргументов много — значит метод выполняет слишком много действий, нарушается принцип единственной ответственности. Это сложно тестировать и поддерживать.
Плохо:
final class SomeService {
public function doSomething($own, $two, $three, $four)
{
}
}
10. Не мутировать объекты переданные в метод/функцию
Это неочевидное поведение для клиентского кода и легко приводит к ошибкам в процессе развития и изменения кода.
Плохо:
$item = new Item();
$this->calculateCount($item);
public function calculateCount(Item $item): void
{
$count = 0;
// some logic
$item->setCount($count);
}
Хорошо:
$item = new Item();
$item->setCount($this->calculateCount());
public function calculateCount(): int
{
$count = 0;
// some logic
return $count;
}
11. Заполнение DTO через конструктор с именованными аргументами, readonly свойствами, без get/set методов
Такая запись читабельна за счёт именованных аргументов, нет лишнего кода get/set, такая dto иммутабельна за счёт readonly.
Хорошо:
final class Item
{
public function __construct(
public readonly int $id,
public readonly int $count,
public readonly string $originId,
) {
}
}
$item = new Item(
id: 1,
count: 2,
originId: 'aaa-bbb-ccc',
);
12. Разбиваем большие классы и методы
Класс меньше ~150 строк, метод меньше ~30 строк. Это значительно упрощает чтение кода.
13. Unit тесты всегда
На любой код обязательно пишем unit тест (кроме dto). Если есть skiptests — то обязательно добавляем ссылку на то место, где это протестировано.
/**
* @skiptests tested in {@see \App\SomeOthreService}
*/
final class SomeServiceTest extends TestCase {
}
14. Тестируем поведение, а не детали реализации
Тест должен проверять все варианты поведения модуля, но не должен тестировать внутреннюю реализацию этого поведения.
Не надо в тесте проверять вызов логгера, аргументы исходящих вызовов, вызовы приватных методов, если только в этом не заключается основная логика работы класса. Stubs и dummy заглушки намного предпочтительнее mocks и fakes.
Плохо:
final class SomeServiceTest extends TestCase {
public function testDoSomething()
{
$logger = $this->createMock(LoggerInterface::class);
$logger->expects($this->once())
->method('info')
->with('some message');
$service = new SomeService($logger);
$service->doSomething();
}
}
Хорошо:
final class SomeServiceTest extends TestCase {
public function testDoSomething()
{
$service = new SomeService(
$this->createMock(LoggerInterface::class),
);
$service->doSomething();
}
}
15. Композиция, а не наследование
Наследование это максимально сильная связь между классами.
Композиция в подавляющем большинстве случаев предпочтительнее.
Плохо:
final class SomeService extends BaseLogic {
}
Хорошо:
final class SomeService {
public function __construct(private readonly BaseLogic $logic) {}
public function execute()
{
$this->logic->doSomething();
}
}
16. По умолчанию указываем final для классов
Такое правило позволяет избежать проблем с наследованием и поощряет использование композиции.
final class SomeService {
}
17. Не работаем с ассоциативными массивами, только с объектами
Приходится писать много проверок, сложно расширять. Используем JMS\Serializer\SerializerInterface и
JMS\Serializer\ArrayTransformerInterface.
Плохо:
$id = $data['id'];
Хорошо:
$id = $data->getId();
18. Соблюдаем закон Деметры
Класс должен взаимодействовать только с известными ему модулями, не взаимодействовать с незнакомцами.
Плохо:
$client = $this->clientFactory->create();
$client->send();
Хорошо:
$this->clientDecorator->send();
19. Минимальная цикломатическая сложность
Код должен быть максимально плоским. Чем меньше сложность, тем проще читать код и понимать, что он делает.
Иногда можно жертвовать микрооптимизациями ради читаемости.
Плохо:
foreach ($items as $item) {
if ($item->isAvailable()) {
$availableItems[] = $item;
}
if ($item->isAcvite()) {
$activeItems[] = $item;
}
}
Хорошо:
$availableItems = $this->filterAvailableItems($items);
$activeItems = $this->filterActiveItems($items);
