Merge pull request #17 from bjrnblm/master

Get transitionable states from state on Model

docs/working-with-transitions/04-retrieving-transitionable-states.md

@@ -0,0 +1,52 @@
+---
+title: Retrieving transitionable states
+weight: 4
+---
+
+An array of transitionable states can use the retrieved with the `transitionableStates()` method on your model.
+
+```php
+class Payment extends Model
+{
+    // …
+
+    protected function registerStates(): void
+    {
+        $this->addState('state', PaymentState::class)
+            ->allowTransition(Pending::class, Paid::class)
+            ->allowTransition(Paid::class, Refunded::class)
+    }
+}
+```
+
+```php
+$transitionableStates = $payment->transitionableStates(Pending::class);
+```
+
+This will return an array with all transitionable states for `Pending::class`
+
+```php
+[
+    0 => "paid"
+]
+```
+
+## Transitionable states from state
+
+Its also possible to use `transitionableStates()` method directly on a state:
+
+```php
+$payment->state->transitionableStates();
+```
+
+## Multiple state fields on model
+
+If there are multiple fields, a `\Spatie\ModelStates\Exceptions\InvalidConfig` exception will be thrown. You can pass the state field name explicitly as a parameter:
+
+```php
+// From a model
+$payment->transitionableStates(Pending::class, 'fieldName')
+
+// From a state
+$payment->state->transitionableStates('fieldName');
+```

src/HasStates.php

@@ -141,6 +141,23 @@ public function transitionTo($state, string $field = null)
         $this->{$field}->transitionTo($state);
     }
 
+    public function transitionableStates(string $fromClass, ?string $field = null): array
+    {
+        $stateConfig = self::getStateConfig();
+
+        if ($field === null && count($stateConfig) > 1) {
+            throw InvalidConfig::fieldNotFound($fromClass, $this);
+        }
+
+        $field = $field ?? reset($stateConfig)->field;
+
+        if (! array_key_exists($field, $stateConfig)) {
+            throw InvalidConfig::unknownState($field, $this);
+        }
+
+        return $stateConfig[$field]->transitionableStates($fromClass);
+    }
+
     /**
      * @param string $fromClass
      * @param string $toClass

src/State.php

@@ -255,6 +255,16 @@ public function transitionTo($state, ...$args): Model
         return $this->transition($transition, ...$args);
     }
 
+    /**
+     * Get the transitionable states from this state.
+     *
+     * @return array
+     */
+    public function transitionableStates($field = null): array
+    {
+        return $this->model->transitionableStates(get_class($this), $field);
+    }
+
     /**
      * This method is used to find all available implementations of a given abstract state class.
      * Finding all implementations can be done in two ways:.

src/StateConfig.php

@@ -80,6 +80,23 @@ public function allowTransitions(array $transitions): StateConfig
         return $this;
     }
 
+    public function transitionableStates(string $fromClass): array
+    {
+        $transitionableStates = [];
+
+        foreach ($this->allowedTransitions as $allowedTransition => $value) {
+            [$from, $to] = explode('-', $allowedTransition);
+
+            if ($from !== $fromClass) {
+                continue;
+            }
+
+            $transitionableStates[] = $to::getMorphClass();
+        }
+
+        return $transitionableStates;
+    }
+
     /**
      * @param string $from
      * @param string $to

tests/TransitionableStatesTest.php

@@ -0,0 +1,59 @@
+<?php
+
+namespace Spatie\ModelStates\Tests;
+
+use Spatie\ModelStates\Tests\Dummy\Payment;
+use Spatie\ModelStates\Exceptions\InvalidConfig;
+use Spatie\ModelStates\Tests\Dummy\States\Failed;
+use Spatie\ModelStates\Tests\Dummy\States\Created;
+use Spatie\ModelStates\Tests\Dummy\States\Pending;
+use Spatie\ModelStates\Tests\Dummy\ModelWithMultipleStates;
+
+class TransitionableStatesTest extends TestCase
+{
+    /** @test */
+    public function transitionable_states_with_fieldname()
+    {
+        $payment = new Payment();
+
+        $transitionableStates = $payment->transitionableStates(Created::class, 'state');
+
+        $this->assertEquals(
+            $transitionableStates,
+            [Pending::getMorphClass(), Failed::getMorphClass()]
+        );
+    }
+
+    /** @test */
+    public function transitionable_states_without_fieldname()
+    {
+        $payment = new Payment();
+
+        $transitionableStates = $payment->transitionableStates(Created::class);
+
+        $this->assertEquals(
+            $transitionableStates,
+            [Pending::getMorphClass(), Failed::getMorphClass()]
+        );
+    }
+
+    /** @test */
+    public function transitionable_states_with_invalid_fieldname_fails()
+    {
+        $this->expectException(InvalidConfig::class);
+
+        $payment = new Payment();
+
+        $transitionableStates = $payment->transitionableStates(Created::class, 'wrong');
+    }
+
+    /** @test */
+    public function transitionable_states_with_multiple_states_without_fieldname_fails()
+    {
+        $this->expectException(InvalidConfig::class);
+
+        $payment = new ModelWithMultipleStates();
+
+        $transitionableStates = $payment->transitionableStates(DummyState::class);
+    }
+}