interview-demo-code/.cursor/rules/php.md

PHP Code Style Rules

PHP Version

Проект поддерживает PHP 7.4+

PSR Standards

• PSR-1: Basic Coding Standard
• PSR-4: Autoloading Standard
• PSR-12: Extended Coding Style

Code Style

Type Declarations

// ✅ Правильно - строгая типизация
public function getCustomers(Request $request): JsonResponse
{
    $id = (int) $request->get('id');
    return new JsonResponse(['data' => $customers]);
}

// ❌ Неправильно - без типов
public function getCustomers($request)
{
    return ['data' => $customers];
}

Nullable Types

// ✅ Правильно
public function findById(?int $id): ?array
{
    if ($id === null) {
        return null;
    }
    return $this->query->where('id', '=', $id)->firstOrNull();
}

Strict Types

Всегда используй declare(strict_types=1);:

<?php

declare(strict_types=1);

namespace App\Services;

Array Syntax

// ✅ Предпочтительно - короткий синтаксис
$array = ['key' => 'value'];

// ❌ Не использовать
$array = array('key' => 'value');

String Interpolation

// ✅ Предпочтительно
$message = "User {$userId} not found";

// ✅ Альтернатива
$message = sprintf('User %d not found', $userId);

Arrow Functions (PHP 7.4+)

// ✅ Для простых операций
$filtered = array_filter($items, fn($item) => $item->isActive());

// ❌ Для сложной логики - используй обычные функции

Nullsafe Operator (PHP 8.0+)

// ✅ Для PHP 7.4
$name = $user && $user->profile ? $user->profile->name : null;

Naming Conventions

Classes

// ✅ PascalCase
class TelegramCustomerService {}
class UserRepository {}

Methods

// ✅ camelCase
public function getCustomers(): array {}
public function saveOrUpdate(array $data): array {}

Variables

// ✅ camelCase
$customerData = [];
$totalRecords = 0;

Constants

// ✅ UPPER_SNAKE_CASE
private const MAX_RETRIES = 3;
public const DEFAULT_PAGE_SIZE = 20;

Private Properties

// ✅ camelCase с модификатором доступа
private string $tableName;
private Builder $builder;

Documentation

PHPDoc

/**
 * @throws ValidationException Если параметры невалидны
 */
public function getCustomers(Request $request): JsonResponse
{
    // ...
}

Inline Comments

// ✅ Полезные комментарии
// Применяем фильтры для подсчета общего количества записей
$countQuery = $this->buildCountQuery($filters);

// ❌ Очевидные комментарии
// Получаем данные
$data = $this->getData();

Error Handling

Exceptions

// ✅ Специфичные исключения
if (!$userId) {
    throw new InvalidArgumentException('User ID is required');
}

// ✅ Логирование
try {
    $result = $this->service->process();
} catch (Exception $e) {
    $this->logger->error('Processing failed', [
        'exception' => $e,
        'context' => $context,
    ]);
    throw new ProcessingException('Failed to process', 0, $e);
}

Query Builder Usage

Always Use Query Builder

// ✅ Правильно
$customers = $this->builder->newQuery()
    ->select(['id', 'name', 'email'])
    ->from('megapay_customers')
    ->where('status', '=', 'active')
    ->orderBy('created_at', 'DESC')
    ->get();

// В крайних случаях можно использовать прямые SQL
$result = $this->database->query("SELECT * FROM megapay_customers");

Parameter Binding

// ✅ Query Builder автоматически биндит параметры
$query->where('name', 'LIKE', "%{$search}%");

// ❌ Никогда не конкатенируй значения в SQL, избегай SQL Injection.

Array Access

Safe Array Access

// ✅ Используй Arr::get()
use Openguru\OpenCartFramework\Support\Arr;

$value = Arr::get($data, 'key', 'default');

// ❌ Небезопасно
$value = $data['key']; // может вызвать ошибку

Return Types

// ✅ Всегда указывай return type
public function getData(): array {}
public function findById(int $id): ?array {}
public function process(): void {}

// ❌ Без типа
public function getData() {}

Visibility Modifiers

// ✅ Всегда указывай модификатор доступа
private string $tableName;
protected Builder $builder;
public function getData(): array {}