joe.szeto / capsule
Requires
- laravel/framework: ^10 || ^11.0
Requires (Dev)
- pestphp/pest: ^2.34
README
composer require joe.szeto/capsule
Basic usage
we can use attribute Setter
to tell the code
the following Closure is a setter, and the value of the setter is the return value of the closure
$me = capsule( #[Setter('name')] fn() => 'szeto', #[Setter('age')] fn() => 30, #[Setter('sex')] fn() => 'man' )->thenReturn(fn(string $name, int $age, string $sex) => [ $name, $age, $sex ]); // to be ['szeto', 30, 'man']
we can also use method set
to set the value of the setter
$me = capsule() ->set('name', fn() => 'szeto') ->set('age', fn() => 30) ->set('sex', fn() => 'man') ->thenReturn(fn(string $name, int $age, string $sex) => [ $name, $age, $sex ]); // to be ['szeto', 30, 'man']
Auto resolve params
if the closure has type hints and the type hint is the same as the value of the setter, the value will be resolved automatically even if the params name is not 100% match, it will still work
$name = capsule() ->set('name', 'szeto') ->thenReturn(fn(string $myName) => $myName);
we can resolve parameters by the application container leverages the underlying container's reflection capabilities. This means that when a closure or callable object is executed, the Capsule library can automatically inject the required dependencies as defined by the type hints of the parameters.
capsule() ->thenReturn(fn(WhenEmpty $empty) => expect($empty)->toBeInstanceOf(WhenEmpty::class));
OnBlank
it will only call when the value of the setter is null
$name = capsule() ->set('name', fn() => null) ->through( #[OnBlank('name'), Setter('name')] fn() => 'szeto' // this closure only call when the value of 'name' is null )->thenReturn('name');
we can also use attribute SetOnBlank
to set and detect the OnBlank at the same time
$name = capsule() ->set('name', fn() => null) ->through( #[SetOnBlank('name')] fn() => 'szeto' ) ->thenReturn('name');
we can also use method setOnBlank
to set the OnBlank
$name = capsule() ->set('name', fn() => null) ->setOnBlank('name', fn() => 'szeto') ->thenReturn('name');
Closure
if the set value is a closure, when the type hint of the param of using is Closure the original closure will be passed to the param
$name = capsule() ->set('name', fn() => 'szeto') ->thenReturn(fn(Closure $name) => $name()); expect($name)->toBe('szeto');
when the type hint of the params is a NOT closure, the value will be return
$name = capsule() ->set('name', fn() => 'szeto') ->thenReturn( fn(string $name) => $name // now name is szeto, not a closure ); expect($name)->toBe('szeto');
Evaluable
if the type is closure, and call it we have to pass the params manually
$name = capsule() ->set('prefix', fn() => 'Joe') ->set('name', fn(string $prefix) => $prefix. ' szeto') ->thenReturn( fn(Closure $name, string $prefix) => $name($prefix) // params is Joe );
but if we pass the param one by one manually it will be very tedious now Evaluable become handy
capsule() ->set('prefix', fn() => 'Joe') ->set('name', fn(string $prefix) => $prefix. ' szeto') ->thenReturn( fn(Evaluable $name) => $name() // params is Joe );
Each
for each value, the closure will be called
$names = capsule() ->set('names', fn() => ['szeto', 'joe']) ->through( #[Each('names' as: 'name')] fn(string $name) => $name // 'szeto', 'joe' )->run();
Only
capsule() ->through( fn() => throw new Exception('should not run'), #[Only] fn() => expect(true)->toBeTrue() ) ->run();
Skip
capsule() ->through( fn() => expect(true)->toBeTrue(), #[Skip] fn() => throw new Exception('should not run'), ) ->run();
Mocking
The Capsule::mock method allows developers to replace parts of their application's behavior with predetermined responses or operations. This is particularly useful in testing, where you want to isolate the part of the application you are testing and control its interactions with external dependencies.
public static function mock(string $key, mixed $value): void
To replace a string value within the capsule, simply pass the key and the new string value to the mock method.
Capsule::mock('name', 'szeto');
If you need to mock the behavior of a function, provide a closure as the second argument. This closure will be executed in place of the original function associated with the given key.
Capsule::mock('name', fn() => 'szeto');
To mock an object, pass an instance of the class as the second argument. This instance will replace any existing instances bound to the specified key within the capsule.
Capsule::mock('name', new OnBlank('szeto'));
Mock with sequence
Capsule::mock(OnBlank::class, new Sequence( new OnBlank('szeto'), new OnBlank('joe') )); capsule() ->through( fn(OnBlank $name) => expect($name->getKey())->toBe('szeto'), fn(OnBlank $name) => expect($name->getKey())->toBe('joe') )->run();
Catch
capsule( fn() => throw new Exception('foo'), #[Cat(Exception::class)] fn($message) => expect($message)->toBe('foo') )->run();
Namespace
it can resolve params from namespace, capsules under same namespace can share the value
capsule() ->namespace('some:namespace') ->set('name', 'szeto')->run(); capsule() ->namespace('some:namespace') ->through( fn(string $name) => expect($name)->toBe('szeto') )->run();
Append
append function will append the callable to the end of the capsule
$capsule = capsule()->through( #[Setter('name')] fn() => 'szeto' ); $name = $capsule->append( #[Setter('name')] fn($name) => 'joe ' . $name )->thenReturn('name'); expect($name)->toBe('joe szeto');
use append combined with namespace
capsule()->namespace('abc:foo')->append( #[Setter('name')] fn(string $name) => 'joe ' . $name ); $name = capsule() ->namespace('abc:foo') ->through( #[Setter('name')] fn() => 'szeto' )->thenReturn('name'); // now name is joe szeto
massage
when we want to change the value of some variable we will always do something like the following
return capsule() ->namespace($namespace) ->set($data) ->thenReturn($return);
so I come up with the idea of massage
return massage($namespace, $data, $return);
or
return massage($namespace, $data);
but if we want to use this approach, we have to follow some conventions
$namespace
= someClassname:someFunction:someVariableName
and the someVariableName
must be the key of the data
for example
massage(Foo::class.':handle:name', ['name' => 'szeto']);
this is equivalent to
capsule() ->namespace(Foo::class.':handle:name') ->set('name', 'szeto') ->thenReturn('name');