shetabit/stampable

Add stamp behaviors into laravel models.

v2.0.0 2026-08-16 08:17 UTC

Requires

• php: ^8.4
• illuminate/database: ^12.0|^13.0
• illuminate/support: ^12.0|^13.0

Requires (Dev)

• larastan/larastan: ^3.10
• orchestra/testbench: ^10.0|^11.0
• phpcsstandards/php_codesniffer: ^4.0
• phpstan/phpstan: ^2.2
• phpunit/phpunit: ^11.5|^12.0|^13.0
• rector/rector: ^2.6

MIT

• Mahdi Khanzadi

• stamp
• shetabit
• stampable
• laravel stamp
• laravel stampable
• laravel stamp package
• laravel stampable package
• laravel stamp models
• laravel stampable models
• laravel add stamp to models
• laravel models stamp behaviors

Published on Packagist.org on 2026-08-16 08:22 UTC

README

Laravel Stampable

This is a Laravel Package for adding stamp behaviors into laravel models. This package supports PHP 8.4+ and Laravel 12 and 13.

List of contents

• Install
• How to use
  • Configure migration
  • Configure Model
  • Define stamps
  • Working with stamps
  • Unknown stamps
• Testing
• Change log
• Contributing
• Security
• Credits
• License

Install

Via Composer

$ composer require shetabit/stampable

How to use

Configure Migration

In your migration you must add timestamp field per each stamp.

// In migration, you must add published_at field like the below if you want to use it as a stamp.
$table->timestamp('published_at')->nullable();

Configure Model

In your eloquent model add use HasStamps trait like the below.

<?php

namespace App\Models;

use Illuminate\Database\Eloquent\Model;
use Shetabit\Stampable\Contracts\Stampable;
use Shetabit\Stampable\Traits\HasStamps;

class Category extends Model implements Stampable
{
    use HasStamps;

    //    
}

Define stamps

you can define stamps using protected stamps attribute the model

<?php

namespace App\Models;

use Illuminate\Database\Eloquent\Model;
use Shetabit\Stampable\Contracts\Stampable;
use Shetabit\Stampable\Traits\HasStamps;

class Category extends Model implements Stampable
{
    use HasStamps;

    protected $stamps = [
        'published' => 'published_at',    
    ];

    //    
}

stamps must be in ['stampName' => 'databaseFieldName'] format.

Working with stamps

Model creates methods and local scopes for each stamp dynamically.

According to the latest example, now we have the below methods for each Category instance.

<?php

/**
 * notice that be have all of this methods and scopes for each stamps.
 * the name of methods will be similar to the stamp's name.
**/

// methods:
$category->markAsPublished(); // press published stamp on this category!
$category->markAsUnpublished(); // Remove stamp mark from this category.

$category->isPublished(); // Determines if this category is published.
$category->isnUnpublished(); // Determinces if this category is Unpublished.

// scopes: you can use scopes to filter your data using stamp status.
Category::published()->get(); // retrieve published datas
Category::unpublished()->get(); // retrieve unpublished datas

Unknown stamps

A stamp that the model does not declare throws a Shetabit\Stampable\Exceptions\StampNotFoundException, and the message names the stamps that are available:

$post->isStampedBy('nonexistent');
// The stamp [nonexistent] is not defined. Available stamps: published, verified.

hasStamp() asks the same question without throwing, and getStampField() resolves a stamp to the column behind it.

Testing

Every pull request and every push to master is checked by GitHub Actions: the test suite runs on PHP 8.4 and 8.5 against Laravel 12 and 13 (both the lowest and the highest supported dependencies), the coding style is checked with PHP_CodeSniffer, the sources are analysed with PHPStan and the code coverage is measured.

The tests run against real Eloquent models on an in-memory sqlite database through Orchestra Testbench, so the stamps, the scopes and the dynamic methods are exercised the way an application uses them.

composer install

composer test           # run the test suite
composer test-coverage  # run the test suite and report code coverage
composer check-style    # check the coding style
composer fix-style      # fix the coding style where possible
composer analyse        # run static analysis
composer ci             # run all of the checks above

If you would rather not install PHP on your machine, the shipped Dockerfile and Makefile run everything inside a container:

make test              # run the test suite
make coverage          # run the test suite and report code coverage
make check-style       # check the coding style
make fix-style         # fix the coding style where possible
make analyse           # run static analysis
make ci                # run all of the checks above
make shell             # open a shell inside the container
make help              # list every available target

Another PHP version can be used with make test PHP_VERSION=8.5.

Change log

Please see CHANGELOG for more information on what has changed recently.

Contributing

Please see CONTRIBUTING and CONDUCT for details.

Security

If you discover any security related issues, please email [e-mail] instead of using the issue tracker.

Credits

• Mahdi khanzadi
• All Contributors

License

The MIT License (MIT). Please see License File for more information.