AIS PHP/Laravel Conventions

Name: ais-php-laravel
Rating: 92
Author: victorhramos-dev

Sistema AIS Real-Time Processing - Laravel 11.x + PHP 8.2+

Padrões de Código Obrigatórios

PHPDoc (Obrigatório em TODOS os arquivos)

php

<?php

namespace App\Services\AIS;

/**
 * Descrição clara do propósito da classe.
 * 
 * @package App\Services\AIS
 */
class ExemploService implements ExemploServiceInterface
{
    /**
     * Descrição do método.
     *
     * @param string $parametro Descrição do parâmetro
     * @return array<string, mixed> Descrição do retorno
     * @throws \InvalidArgumentException Se parâmetro inválido
     */
    public function metodo(string $parametro): array
    {
        // Implementação
    }
}

Comentários em pt-BR (Obrigatório para CC > 2)

Blocos com complexidade ciclomática > 2 DEVEM ter comentários explicativos em português:

php

// Verifica se a mensagem já existe nas 3 camadas de deduplicação
// Camada 1: Redis SET NX (rápido, volátil)
// Camada 2: Bloom Filter (probabilístico, memória eficiente)
// Camada 3: PostgreSQL (definitivo, persistente)
if ($this->verificarDuplicacao($mensagem)) {
    return false;
}

Estrutura de Services

php

<?php

namespace App\Services\AIS;

use Illuminate\Support\Facades\Redis;
use Psr\Log\LoggerInterface;

class NomeService implements NomeServiceInterface
{
    // Constantes para valores mágicos (NUNCA hardcode)
    private const PREFIXO_CACHE = 'ais:nome:';
    private const TTL_PADRAO = 300;

    // Injeção de dependências via construtor
    public function __construct(
        protected Redis $redis,
        protected LoggerInterface $logger
    ) {}

    // Métodos públicos primeiro
    public function metodoPrincipal(): mixed {}

    // Métodos privados depois
    private function metodoAuxiliar(): mixed {}
}

Estrutura de Models

php

<?php

namespace App\Models;

use App\Models\Concerns\UsesAisConnection;
use Illuminate\Database\Eloquent\Model;

class AISMessage extends Model
{
    use UsesAisConnection;

    protected $connection = 'ais';
    protected $table = 'ais_messages';

    protected $fillable = [
        'mmsi',
        'message_type',
        'raw_nmea',
        'parsed_data',
        'received_at',
    ];

    protected $casts = [
        'parsed_data' => 'array',
        'received_at' => 'datetime',
    ];
}

Estrutura de Controllers API

php

<?php

namespace App\Http\Controllers\API\AIS;

use App\Http\Controllers\Controller;
use App\Http\Resources\AIS\MessageResource;
use Illuminate\Http\Request;

class MessageController extends Controller
{
    public function index(Request $request): AnonymousResourceCollection
    {
        $validated = $request->validate([
            'mmsi' => 'sometimes|string|size:9',
            'type' => 'sometimes|integer|between:1,27',
            'from' => 'sometimes|date',
            'to' => 'sometimes|date|after:from',
        ]);

        $query = AISMessage::query();

        // Aplicar filtros...

        return MessageResource::collection(
            $query->orderBy('received_at', 'desc')->paginate(50)
        );
    }
}

Proibições Absolutas

•NUNCA usar as any, @ts-ignore (se TypeScript)
•NUNCA usar @ts-expect-error
•NUNCA suprimir erros com catch vazio catch(e) {}
•NUNCA hardcode de valores mágicos (usar constantes)
•NUNCA commitar arquivos .env
•NUNCA modificar migrations existentes (criar novas)

Estrutura TDD (Arrange-Act-Assert)

php

public function test_deduplicacao_rejeita_mensagem_duplicada(): void
{
    // Arrange - Preparar dados de teste
    $mensagem = $this->criarMensagemAIS(['mmsi' => '123456789']);
    $this->service->processar($mensagem);

    // Act - Executar ação sendo testada
    $resultado = $this->service->processar($mensagem);

    // Assert - Verificar resultados
    $this->assertFalse($resultado);
    $this->assertDatabaseCount('ais_messages', 1);
}

Imports Padrão

php

use Illuminate\Support\Facades\Redis;
use Illuminate\Support\Facades\Log;
use Illuminate\Support\Facades\DB;
use Illuminate\Support\Facades\Cache;
use Carbon\Carbon;

Referências

•@.docs/CODE-STYLE.md para padrões detalhados
•@.docs/SPEC-00: AIS Real-Time Processing System.md para arquitetura