README

The JOOservices Exceptions Library is a PHP 8.5+ foundational library providing shared exception contracts, base exception classes, and structured context utilities across the JOOservices package ecosystem.

Package name: jooservices/exceptions

Latest stable release: v1.0.0 (see CHANGELOG)

Install

composer require jooservices/exceptions

Core Features

• Ecosystem-Wide Catching: Root marker JOOExceptionInterface for catch-all ecosystem handling.
• SPL Semantics: Separate AbstractJOORuntimeException and AbstractJOOLogicException bases.
• Structured Context: AbstractContextAwareException, AbstractContextAwareLogicException, and HasExceptionContext.
• Stable Error Metadata: errorCode(), logLevel() (LogLevel vocabulary), toLogArray().
• Sensitive Data Redaction: DefaultContextRedactor + CompositeContextRedactor::withExtraKeys().
• Framework Decoupled: Zero runtime dependencies.

Basic Usage

Catching Ecosystem Exceptions

use JOOservices\Exceptions\Contracts\JOOExceptionInterface;

try {
    $dto = UserDto::from($input);
} catch (JOOExceptionInterface $e) {
    $logger->error($e->getMessage());
}

Declaring base exceptions

use JOOservices\Exceptions\Base\AbstractJOORuntimeException;

abstract class ClientException extends AbstractJOORuntimeException {}

Context-Aware Exceptions

use JOOservices\Exceptions\Base\AbstractContextAwareException;
use JOOservices\Exceptions\Support\ExceptionContext;
use JOOservices\Exceptions\Support\LogLevel;

final class HydrationException extends AbstractContextAwareException
{
    public static function forField(string $path, string $expectedType): self
    {
        return (new self("Hydration failed for field '{$path}'"))
            ->withContext([
                'path' => $path,
                'expectedType' => $expectedType,
            ]);
    }

    public function errorCode(): string
    {
        return 'dto.hydration.failed';
    }

    public function logLevel(): string
    {
        return LogLevel::ERROR;
    }

    protected function copyWithContext(ExceptionContext $context): static
    {
        return new self($this->getMessage(), $this->getCode(), $this->getPrevious(), $context);
    }
}

$logger->log($exception->logLevel(), $exception->getMessage(), $exception->toLogArray());

For logic / invariant failures with context, extend AbstractContextAwareLogicException the same way.

Security & Context Redaction

use JOOservices\Exceptions\Base\AbstractContextAwareException;
use JOOservices\Exceptions\Support\CompositeContextRedactor;

AbstractContextAwareException::setRedactor(
    CompositeContextRedactor::withExtraKeys(['national_id', 'ssn']),
);

Never put secrets in exception messages. Put diagnostics in context and rely on redaction.

Trait Integration

When inheritance is blocked by a third-party base, use HasExceptionContext, implement copyWithContext(), and call initContext() in the constructor (fail-fast if omitted).

Documentation

• Documentation Hub
• Changelog
• Installation
• Quick Start
• Laravel Integration
• Risks and Gaps
• AI Skills Usage

AI Support

• AGENTS.md
• CLAUDE.md
• AI Skills Map
• Canonical skills: .github/skills/
• Adapters: antigravity/prompts/, jetbrains/prompts/, .github/prompts/

Development

composer lint
composer lint:all
composer docs:verify
composer test
composer test:coverage
composer check
composer ci

• Setup
• Testing
• CI/CD
• Release Process
• Contributing

Approved Git flow: feature/fix → develop; release/hotfix → master; tags from master.

Community

• Contributing
• Security Policy
• Code of Conduct

GitHub Actions and Services

• CI: security (composer audit --locked), optional dependency-review, lint + docs snippet guard, PHPStan, PHPMD, 100% coverage tests, Codecov upload, optional SonarCloud (SONAR_TOKEN)
• Codacy: free Analysis CLI → GitHub Code Scanning (optional CODACY_PROJECT_TOKEN)
• Fortify: free-trial capable; skips cleanly when credentials are absent
• Release: validate, GitHub release, Packagist update on v*.*.* tags
• PR Labeler / Semantic PR Title
• OpenSSF Scorecard / Secret Scanning (Gitleaks)

License

MIT — see LICENSE.