Skip to content

PhpDeal 2.0: PHP 8.4, Go! AOP 4 and native attributes - #70

Merged
lisachenko merged 3 commits into
masterfrom
feature/trusting-sagan-jo6fho
Nov 10, 2026
Merged

lisachenko merged 3 commits into
masterfrom
feature/trusting-sagan-jo6fho

Conversation

@lisachenko

@lisachenko lisachenko commented Nov 10, 2026 •

Copy link
Copy Markdown
Member

Summary

Modernizes PhpDeal for PHP 8.4+ on top of Go! AOP 4. Contracts are now native attributes instead of Doctrine annotations:

#[Invariant('$this->balance >= 0')]
class Account
{
    #[Verify('$amount > 0')]
    #[Ensure('$this->balance === $__old->balance + $amount')]
    public function deposit(float $amount): void { /* ... */ }
}

Core

  • New PhpDeal\Attribute namespace: #[Verify], #[Ensure], #[Invariant] (repeatable) and #[Inherit].
  • The aspects are rebuilt on two shared services:
    • ContractFetcher collects contracts across parents and interfaces, with caching.
    • ContractEvaluator compiles each expression into a closure once.
  • ContractApplication::registerAspects() lets apps that already have a Go! AOP kernel turn contracts on.

Behaviour improvements

  • Inherited preconditions are now checked before the method body. 1.x ran the body first.
  • A parent's contracts run in that parent's class scope, so they can read its private state.
  • Static methods are supported.
  • Invariants are also checked after the constructor.
  • An invariant can call public methods of its own class without endless recursion.
  • $__old is cloned only when a contract actually uses it.
  • Class-level #[Inherit] now also inherits method contracts, which is what the docs always described.
  • Variadic arguments are passed to contracts. Array and object arguments no longer break the error message.

Exceptions

  • PreconditionViolation, PostconditionViolation and InvariantViolation all extend ContractViolation, so existing catch blocks keep working.
  • InvalidContractException is new: it covers syntax errors, non-boolean results, and $this used in a static method.
  • Each violation points to the line of the method that declares the contract.

Tooling and quality

  • Tests run on PHPUnit 13: 109 unit and functional tests. The functional tests run against classes that Go! AOP really weaves.
  • PHPStan level 10 with strict rules and the phpunit extension, over src, tests and demo. It analyses for PHP 8.4–8.5.
  • A PHPStan extension now ships with the package: private properties and methods used only inside contract strings are no longer reported as unused. It is registered automatically through extension-installer.
  • PHP-CS-Fixer (PER-CS 2.0) replaces phpcs.
  • GitHub Actions replaces Travis CI and Scrutinizer:
    • Tests on PHP 8.4 and 8.5, plus a lowest-dependencies job.
    • A PHPStan job.
    • A coding style job, which also runs composer audit.
    • A demo smoke run.
  • Dependabot now also updates GitHub Actions.

Docs

  • The README is rewritten: badges, a feature overview, setup (standalone, inside an existing kernel, Symfony), a reference for every contract, rules for writing expressions, the exception hierarchy, PHPStan integration and production advice.
  • New UPGRADE-2.0.md and CHANGELOG.md.
  • New AGENTS.md for AI coding agents: commands, layout, how contracts work, conventions and testing tips. It is excluded from the distributed package.

Breaking changes

This is a major release; see UPGRADE-2.0.md.

  • The minimum PHP version is 8.4.
  • Annotations are replaced by attributes.
  • AbstractContractAspect, InheritCheckerAspect and the Contract\Fetcher\Parent\* classes are removed.
  • Broken contracts throw InvalidContractException instead of being wrapped into ContractViolation.

Testing

Run locally on PHP 8.5:

  • php-cs-fixer check: clean.
  • PHPStan level 10: no errors. I confirmed the new extension matters: without it, PHPStan reports exactly the 3 fixture properties that are only read by contracts.
  • PHPUnit: 109 tests pass.
  • composer demo runs. Every README example was also run against woven classes and behaves as documented.

PHP 8.4 and the lowest-dependency set were not available locally; the CI matrix covers them.

🤖 Generated with Claude Code

https://claude.ai/code/session_01FxhC1DtML6BuKT7iikmqSb

PhpDeal 2.0 replaces Doctrine annotations with native attributes
(#[Verify], #[Ensure], #[Invariant], #[Inherit]) and runs on Go! AOP 4.

- Rewrite the aspects on top of a shared ContractFetcher (cached,
  inheritance-aware) and ContractEvaluator (expressions compiled once)
- Evaluate parent contracts in their own class scope, check inherited
  preconditions before the body, support static methods, check
  invariants after the constructor and guard against recursion
- Add PreconditionViolation, PostconditionViolation, InvariantViolation
  and InvalidContractException with clearer messages and locations
- Ship a PHPStan extension so members used only by contracts are not
  reported as unused
- Replace the test suite with unit and functional tests on PHPUnit 13,
  analyse everything with PHPStan level 10 and strict rules, and use
  PHP-CS-Fixer (PER-CS 2.0)
- Replace Travis CI and Scrutinizer with GitHub Actions
- Rewrite the README with badges, add UPGRADE-2.0.md and CHANGELOG.md

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01FxhC1DtML6BuKT7iikmqSb
Describes the commands, layout, contract semantics, conventions and
testing tips, and excludes the file from the distributed package.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01FxhC1DtML6BuKT7iikmqSb
On a fresh checkout tests/cache and demo/cache do not exist yet, and
PHPStan rejects missing exclude paths unless they are marked with (?).

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01FxhC1DtML6BuKT7iikmqSb
@lisachenko
lisachenko marked this pull request as ready for review November 10, 2026 16:57
@lisachenko
lisachenko merged commit e24ad58 into master Nov 10, 2026
5 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants