maatify / php-return-target

v1.0.0-rc.1 2026-09-30 07:38 UTC

Requires

• php: ^8.4
• ext-hash: *
• ext-json: *
• maatify/crypto: ^1.0
• maatify/exceptions: ^1.0
• maatify/shared-common: ^1.0

Requires (Dev)

• php-cs-fixer/shim: ^3.95
• phpstan/phpstan: ^2.2
• phpunit/phpunit: ^12.5

proprietary

• Maatify

• php
• maatify
• return-target

Published on Packagist.org on 2026-09-30 08:03 UTC

README

PHP Return Target

Stateless signed internal return-target handling for framework-agnostic PHP applications.

Status

Release Candidate — 1.0.0-rc.1

The published SemVer pre-release v1.0.0-rc.1 is available to consumers through Packagist. No Stable release has been published.

Key Features

• Validate internal return targets without rewriting their original representation.
• Issue opaque, expiring rt1 HMAC tokens and verify them through a public service.
• Re-apply current target restrictions and expiry rules during verification.
• Keep HTTP, routing, authentication, redirect execution, and key loading under Host ownership.

Requirements

• PHP ^8.4 (CI covers PHP 8.4 and 8.5)
• ext-hash
• ext-json
• maatify/crypto ^1.0
• maatify/exceptions ^1.0
• maatify/shared-common ^1.0

Installation

The published Release Candidate is available through Packagist:

composer require maatify/php-return-target:1.0.0-rc.1@RC

Quick Usage

$service = new HmacReturnTargetService(
    new ReturnTargetConfig('admin-auth', 60),
    $hostKeyProvider,
    $hostClock,
    $optionalHostRestrictionPolicy,
);

$token = $service->issue('/orders/15');
$verified = $token === null ? null : $service->verify($token);

The Host supplies the KeyProviderInterface, ClockInterface, and optional restrict-only policy. See the Usage Guide and maintained example for a complete runnable construction.

Public Runtime API

The public substitution boundary is ReturnTargetServiceInterface. The canonical implementation is HmacReturnTargetService; its public collaborators are ReturnTargetConfig, ReturnTargetRestrictionPolicyInterface, KeyProviderInterface, and ClockInterface. Successful verification returns VerifiedReturnTargetDTO; normal target, token, policy, or expiry rejection returns false/null according to the operation. The Package Reference is the complete canonical contract and API inventory.

Boundaries

The package does not execute redirects and does not own HTTP, routing, sessions, authentication, authorization, persistence, databases, or token consumption state. The Host owns those concerns and the construction of key material and time policy.

The canonical rt1 token is signed, not encrypted, and must not carry confidential information or secrets.

Normal target, token, policy, or expiry rejection returns false or null. Invalid canonical configuration throws InvalidReturnTargetConfigurationException; classified canonical crypto/key configuration failures throw ReturnTargetCryptoConfigurationException; unknown provider, external, or Host-policy throwables propagate unchanged.

Documentation

• Usage Guide — consumer fit, boundaries, and workflows.
• Examples — maintained Public API examples.
• Package Reference — canonical public/runtime/behavioral contract.
• Changelog — factual project history.
• Security Policy — private vulnerability reporting route and package security ownership.
• Contributing Guide — contribution paths, local verification, and repository workflow.
• Code of Conduct — community collaboration and conduct rules.

Quality Status

The repository defines local and CI gates for Composer validation, Composer 2.10 dependency policy audit, latest/lowest dependency resolution, PHP 8.4/8.5 tests, PHPStan max, formatting, syntax, whitespace, examples, Consumer Verification, and workflow lint. GitHub Final Gate is the stable aggregate CI check; the actual status for a commit is reported by its GitHub Actions run.

Development and Testing

Latest-compatible local sequence:

composer validate --strict
composer update --no-interaction --prefer-dist --no-progress
composer check-platform-reqs
composer audit --no-interaction --abandoned=fail
composer check:syntax
composer check:whitespace
composer format:check
composer analyse
composer test:unit
composer test:system
composer check:examples
composer verify:consumer
composer check:workflows

Lowest-supported dependency sequence begins with:

composer update --prefer-lowest --prefer-stable --no-interaction --prefer-dist --no-progress
composer check-platform-reqs
composer audit --no-interaction --abandoned=fail
composer check:syntax
composer format:check
composer analyse
composer test:unit
composer test:system
composer check:examples

Restore latest-compatible dependencies and rerun the final applicable local sequence after the lowest check. The Consumer Verification Harness performs two independent clean Composer consumer resolutions and removes generated consumer state after each run. CI tests PHP 8.4 and 8.5; its Final Gate aggregates quality, tests, lowest, consumer-verification, and workflow-lint.

License

This package is proprietary software owned by Maatify. See LICENSE for the applicable terms.

Author

Engineered by Mohamed Abdulalim (@megyptm)
Backend Lead & Technical Architect
https://www.maatify.dev

Built with ❤️ by Maatify.dev — Unified Ecosystem for Modern PHP Libraries