README

Laravel package untuk mendefinisikan error aplikasi satu kali, di PHP enum, lalu memakai definisi yang sama untuk response API, validation, logging, dan frontend.

enum SuratMasukError: string implements ErrorCode
{
    #[ErrorDefinition(
        message: 'Surat sudah disetujui dan tidak dapat diubah.',
        category: ErrorCategory::WORKFLOW,
        httpStatus: 409,
    )]
    case DRAFT_LOCKED = 'SM-WF-001';
}

throw ApplicationException::of(SuratMasukError::DRAFT_LOCKED, context: ['document_id' => $surat->id]);

HTTP/1.1 409 Conflict

{ "message": "Surat sudah disetujui dan tidak dapat diubah.", "code": "SM-WF-001", "retryable": false }

Fitur

Satu sumber kebenaran: kode, message, category, HTTP status, severity, dan retryable didefinisikan di enum case melalui attribute.
Response JSON konsisten untuk ApplicationException, otomatis lewat exception handler Laravel.
Validation dengan kode error per field: FormRequest memetakan setiap rule ke error code, dan response 422 membawa kode tersebut.
Structured logging: level log mengikuti severity, dan data sensitif di context otomatis disensor.
Linter (error-definition:lint) untuk menangkap kode duplikat, format salah, atau rule validation yang belum dipetakan.
Generator (error-definition:generate) untuk error-codes.ts di frontend dan error-catalog.json.
Publish catalog (error-definition:publish) ke filesystem disk Laravel (local, S3, SFTP) atau endpoint HTTP.
Agent skill untuk Claude dan AI coding agent lain, supaya agent menulis error mengikuti framework ini.

Kebutuhan

PHP 8.3 atau lebih baru
Laravel 13

Instalasi

composer require abu-abbas/error-definition-framework

Service provider terdaftar otomatis melalui Laravel package discovery. Publish config jika perlu mengubah output path generator atau menambah sensitive key:

php artisan vendor:publish --tag=error-definition-config

Penggunaan

1. Definisikan error

Buat enum per modul yang mengimplementasikan ErrorCode, di folder mana pun yang termasuk Composer autoload aplikasi.

use Edf\Core\Attributes\ErrorDefinition;
use Edf\Core\ErrorCategory;
use Edf\Core\ErrorCode;
use Edf\Core\ErrorSeverity;

enum SuratMasukError: string implements ErrorCode
{
    #[ErrorDefinition(
        message: 'Nomor surat wajib diisi.',
        category: ErrorCategory::VALIDATION,
        httpStatus: 422,
        severity: ErrorSeverity::LOW,
    )]
    case NOMOR_SURAT_REQUIRED = 'SM-VAL-001';

    #[ErrorDefinition(
        message: 'Surat sudah disetujui dan tidak dapat diubah.',
        category: ErrorCategory::WORKFLOW,
        httpStatus: 409,
    )]
    case DRAFT_LOCKED = 'SM-WF-001';
}

2. Lempar error

use Edf\Core\Exceptions\ApplicationException;

throw ApplicationException::of(
    SuratMasukError::DRAFT_LOCKED,
    context: ['user_id' => $user->id, 'document_id' => $surat->id],
);

Request JSON menerima response berisi message, code, dan retryable dengan HTTP status dari definisi. Context hanya masuk ke log.

3. Petakan validation

use Edf\Laravel\Validation\HasErrorDefinitions;

final class StoreSuratMasukRequest extends FormRequest
{
    use HasErrorDefinitions;

    public function rules(): array
    {
        return ['nomor_surat' => ['required']];
    }

    public function errorCodes(): array
    {
        return ['nomor_surat.required' => SuratMasukError::NOMOR_SURAT_REQUIRED];
    }
}

{
  "message": "Nomor surat wajib diisi.",
  "errors": {
    "nomor_surat": [
      { "code": "SM-VAL-001", "message": "Nomor surat wajib diisi.", "retryable": false }
    ]
  }
}

4. Periksa dan generate

php artisan error-definition:lint
php artisan error-definition:generate

Frontend memakai kode dari file hasil generate, bukan string yang ditulis ulang:

import { ERROR_CODES, type ErrorCode } from './generated/error-codes';

if (code === ERROR_CODES.SM_WF_001) {
  // ...
}

5. Publish catalog

Kirim daftar error lengkap aplikasi dari CI ke storage bersama atau endpoint HTTP:

EDF_PUBLISH_APPLICATION=surat-masuk php artisan error-definition:publish --revision="$(git rev-parse HEAD)"

Default-nya menulis ke disk local. Cara memakai SFTP, S3, atau HTTP ada di panduan Publish Catalog.

Agent Skill

Package menyertakan Agent Skill error-definition-development agar AI coding agent seperti Claude menulis error mengikuti framework ini, bukan abort() atau message bebas.

Claude Code: salin skill ke project.

mkdir -p .claude/skills
cp -r vendor/abu-abbas/error-definition-framework/resources/boost/skills/error-definition-development .claude/skills/

Laravel Boost: jalankan php artisan boost:install, lalu pilih abu-abbas/error-definition-framework di daftar third-party guidelines/skills.

Cara pasang di Claude.ai, Claude Desktop, dan agent lain ada di panduan Agent Skill.

Dokumentasi

Mulai dari documentation index untuk filosofi framework dan peta seluruh dokumentasi.

Guides: cara memakai setiap fitur
API reference: class, method, dan kontrak
Concepts: istilah dan konsep dasar
Design decisions: alasan di balik desainnya
Roadmap

Kontribusi

Lihat CONTRIBUTING.md.

License

MIT. Lihat LICENSE.

abu-abbas / error-definition-framework

Package info

Security

Statistics