README

A modern PHP library providing a reporting API for web applications. Designed as PSR-7/PSR-15 middleware that collects and reports application status information including installed packages, repositories, and application metadata.

Features

🚀 Modern PHP 8.1+ with native enums, constructor property promotion, and strict types
📊 Application Status Reporting with package information and metadata
🔌 PSR-7/PSR-15 Compatible middleware for easy integration
🎯 Null Object Pattern for robust error handling
📋 OpenAPI 3.0 Specification with complete API documentation
🧪 100% Test Coverage with PHPUnit 11
🔐 JWT Authentication support

Requirements

PHP 8.1+ (required for native enum support)
Composer for dependency management
PHPUnit 10.5+ or 11.0+ for testing (dev dependency)

Installation

Install via Composer:

composer require dwenzel/reporter-api

Quick Start

Basic Usage as PSR-15 Middleware

<?php

use DWenzel\ReporterApi\Api;
use Psr\Http\Message\ServerRequestInterface;

// Create the API middleware
$reporterApi = new Api();

// Check if the API can handle the request
if ($reporterApi->canHandle($request)) {
    // Process the request and get response
    $response = $reporterApi->process($request, $handler);
}

Using the Report Endpoint Directly

<?php

use DWenzel\ReporterApi\Api;

$api = new Api();
$reportEndpoint = $api->getReportEndpoint();

// Handle a server request
$response = $reportEndpoint->handle($serverRequest);

Working with Application Status

<?php

use DWenzel\ReporterApi\Schema\ApplicationStatus;
use DWenzel\ReporterApi\Schema\Report;

// Create a new report
$report = new Report();

// Set application status using modern PHP enum
$report->setStatus(ApplicationStatus::OK);
$report->setName('My Application');
$report->setApplicationId(12345);

// Get status information
$status = $report->getStatus(); // Returns ApplicationStatus enum
$statusValue = $status->getValue(); // Returns 'ok'

API Endpoints

GET /api/reporter/v1/application/report

Returns a comprehensive JSON report containing:

Application metadata (name, ID, status)
Installed package information with versions
Repository details
Status indicators

Example Response:

{
  "applicationId": 12345,
  "name": "my-application",
  "status": "ok",
  "packages": [
    {
      "name": "vendor/package",
      "version": "1.0.0",
      "sourceReference": "abc123"
    }
  ],
  "repositories": [
    {
      "type": "git",
      "url": "https://github.com/vendor/package.git"
    }
  ]
}

Architecture

Core Components

Api: Main PSR-15 middleware class with endpoint routing
Endpoint\Report: Primary reporting endpoint implementation
Schema\*: Data models representing API response structure
Http\*: PSR-7 HTTP message implementations

Design Patterns

Endpoint Routing: Path-based routing with lazy loading
Schema Serialization: JSON serialization via traits
Null Object Pattern: Robust error handling
Dependency Integration: Leverages cpsit/auditor for package discovery

Testing

Run the test suite:

# Using composer script
composer test

# Using PHPUnit directly
./vendor/bin/phpunit -c tests/Build/UnitTests.xml

# With DDEV (if using Docker development environment)
ddev exec "cd /var/www/html/app/vendor/dwenzel/reporter-api && .build/bin/phpunit -c tests/Build/UnitTests.xml"

Test Coverage

The library maintains 100% test coverage with comprehensive unit tests for all components.

Configuration

Custom Endpoint Registration

<?php

use DWenzel\ReporterApi\Api;

$api = new Api();

// The default endpoint map can be extended
// Default: ['/api/reporter/v1/application/report' => Report::class]

JWT Authentication

The API supports JWT token authentication as defined in the OpenAPI specification. Include the api_key header in your requests:

GET /api/reporter/v1/application/report
Authorization: Bearer your-jwt-token

Development

Project Structure

src/
├── Api.php                 # Main middleware class
├── Endpoint/              # HTTP endpoint handlers
│   ├── EndpointInterface.php
│   ├── Report.php         # Main reporting endpoint
│   └── NullEndpoint.php   # Null object for unhandled routes
├── Schema/                # Data models
│   ├── ApplicationStatus.php  # PHP 8.1 enum
│   ├── Report.php
│   ├── Package.php
│   └── ...
├── Http/                  # PSR-7 implementations
│   ├── JsonResponse.php
│   ├── AbstractMessage.php
│   └── ...
└── Traits/                # Reusable functionality
    ├── JsonSerialize.php
    └── ToArray.php

Modern PHP Features

This library showcases modern PHP development practices:

Native Enums (PHP 8.1): ApplicationStatus enum with string backing
Constructor Property Promotion (PHP 8.0): Clean, concise constructors
Typed Properties (PHP 7.4): All properties are strictly typed
Strict Types: Enabled across the entire codebase
Union Types: Used where appropriate for flexibility

Contributing

Fork the repository
Create a feature branch (git checkout -b feature/amazing-feature)
Make your changes with proper tests
Ensure all tests pass (composer test)
Commit your changes (git commit -m 'Add amazing feature')
Push to the branch (git push origin feature/amazing-feature)
Open a Pull Request

Code Standards

PHP 8.1+ with strict types
PSR-4 autoloading
PSR-7/PSR-15 compliance
100% test coverage
Modern PHP conventions

API Documentation

Complete API documentation is available in the OpenAPI 3.0 specification:

OpenAPI Spec: reporterApi.yaml
Interactive Documentation: Use tools like Swagger UI to explore the API

License

This project is licensed under the GPL-2.0+ License - see the LICENSE file for details.

Authors

Dirk Wenzel - Initial work and maintenance

Dependencies

Runtime Dependencies

PHP 8.1+: Core language requirement
cpsit/auditor: Package information gathering
web-token/jwt-framework: JWT token handling

Development Dependencies

PHPUnit 10.5+/11.0+: Testing framework
roave/security-advisories: Security vulnerability monitoring

Changelog

See ChangeLog for a detailed history of changes and improvements.

Need help? Open an issue on GitHub or check the OpenAPI specification for detailed API documentation.

dwenzel / reporter-api

Maintainers

Details