Feat: PHP 8.4, Laravel 12/13, a test suite and CI

[khanzadimahdi]

Part of the modernization series across the shetabit packages.

The dynamic scopes were half broken

__call() recognised Post::unpublished() and then forwarded the method name to the scope instead of the stamp name:

return $this->forwardCallTo($this->newQuery(), $methodName, [$method]);
//                                                           ^^^^^^^ 'unpublished'

scopeUnstamped($query, 'unpublished') then looked unpublished up in the stamp list, found nothing, and ran whereNull(null). The positive form only ever worked because there the method name happens to equal the stamp name.

Two more in the same helper:

• getStampScope() compared a lower-cased method name against the stamp names as declared, so a stamp named isVerified had no working scope at all.
• It looped over every stamp without stopping at the one it matched, so a later stamp could overwrite an earlier match and a scope's meaning depended on declaration order.

A stamp that does not exist used to fail quietly

isStampedBy('typo') answered false — which reads as "this record is not published" for what is really a typo. markAsStamped(), markAsUnstamped() and both scopes raised an undefined array key and then wrote to, or queried, a column named null.

They throw StampNotFoundException now, and the message names the stamps that do exist. hasStamp() asks the same question without throwing, and getStampField() resolves a stamp to its column.

Also

• The private getFreshTimestamp() is gone; the model's own freshTimestamp() is used, so a stamp is written in the same format as created_at instead of a date() string when outside Laravel.
• __call() no longer carries an unreachable branch for increment/decrement that would have called itself until the stack ran out. A test covers that both still work, along with relations, through-calls, dynamic wheres and plain forwarding.
• 44 tests — real Eloquent models on an in-memory sqlite database through Testbench — at 100% line coverage. PHPStan level 7 with larastan, no baseline.
• Three workflows (tests matrix, code style, static analysis), a Dockerfile with pcov and a Makefile.

Breaking

PHP 8.4 minimum (was 7.1) and Laravel 12/13 only (was 5.1+). Every method of Contracts\Stampable and of the trait declares its types, so an implementation of the contract has to declare compatible ones. An unknown stamp throws instead of failing quietly. illuminate/database is now required explicitly — the trait has always used Eloquent's query builder.

Verified

composer ci green on PHP 8.4 and 8.5 × lowest and highest (4 runs), rector clean, composer validate --strict passes.

🤖 Generated with Claude Code