Merge pull request #274 from aSeriousDeveloper/states-contract

Contract / Interface for Models that use `HasStates` trait.

Author: freekmurze

docs/working-with-states/01-configuring-states.md

@@ -5,8 +5,6 @@ weight: 1
 
 This package provides a `HasStates` trait which you can use in whatever model you want state support in. Within your codebase, each state is represented by a class, and will be serialised to the database by this package behind the scenes.
 
-This way you don't have to worry about whether a state is in its textual form or not: you're always working with state objects.
-
 ```php
 use Spatie\ModelStates\HasStates;
 
@@ -158,3 +156,21 @@ abstract class PaymentState extends State
 ```
 
 Next up, we'll take a moment to discuss how state classes are serialized to the database.
+
+## Improved typehinting
+
+Optionally, for improved type-hinting, the package also provides a `HasStatesContract` interface.
+
+This way you don't have to worry about whether a state is in its textual form or not: you're always working with state objects.
+
+```php
+use Spatie\ModelStates\HasStates;
+use Spatie\ModelStates\HasStatesContract;
+
+class Payment extends Model implements HasStatesContract
+{
+    use HasStates;
+
+    // …
+}
+```

src/HasStatesContract.php

@@ -0,0 +1,29 @@
+<?php
+
+namespace Spatie\ModelStates;
+
+use Illuminate\Database\Eloquent\Builder;
+use Illuminate\Support\Collection;
+
+interface HasStatesContract
+{
+    public static function bootHasStates(): void;
+
+    public function initializeHasStates(): void;
+
+    public static function getStates(): Collection;
+
+    public static function getDefaultStates(): Collection;
+
+    public static function getDefaultStateFor(string $fieldName): ?string;
+
+    public static function getStatesFor(string $fieldName): Collection;
+
+    public function scopeWhereState(Builder $builder, string $column, $states): Builder;
+
+    public function scopeWhereNotState(Builder $builder, string $column, $states): Builder;
+
+    public function scopeOrWhereState(Builder $builder, string $column, $states): Builder;
+
+    public function scopeOrWhereNotState(Builder $builder, string $column, $states): Builder;
+}