Magical Call¶
This magical function allows you to call()
any Action
or Task
run()
function, from anywhere. Using the
Hive::call()
Facade.
The function call()
is mainly used for calling HiveApi Actions
from Controllers
, and calling HiveApi Tasks
from
Actions
.
Each Action
knows which UI called it, using $this->getUI()
. This may be useful for handling the same Action
differently based on the UI
type (WEB
or API
). This will work when calling the Action
from Controllers
and
Commands
using the magical call()
function.
Usage¶
In the first argument you can pass the class full name, as follow App\Containers\User\Tasks\CreateUserTask::class
,
or you can pass the container name and class name, as follow User@CreateUserTask
.
Using the “string based” style (i.e., containerName@className
) helps removing direct dependencies between containers.
The call()
function, in turn, will verify the Container exist before calling the function and inform the user to
install Container if not exist.
A huge downside of the “string-based” approach, however, is that you will lose auto-completion features from your IDE!
When a class is directly called using its full name, a warning will be logged informing you to use the “string based
caller style”. This message, however, can be disabled by changing the flag hive.logging.log-wrong-hive-caller-style
in the Ship/Configs/hive.php
file accordingly.
<?php
// Call "AssignUserToRoleTask" Task from the "Authorization" Container using the hiveapi caller style
Hive::call('Authorization@AssignUserToRoleTask');
// Call "AssignUserToRoleTask" Task from the "Authorization" Container using class full name.
// This will cause to add an INFO entry to the log file!
Hive::call(\App\Containers\Authorization\Tasks\AssignUserToRoleTask::class);
Example Basic Usage¶
$foo = \HiveApi\Core\Foundation\Facades\Hive::call('Container@ActionOrTask');
- From
Controllers
andActions
you can use the$this->call('Container@ActionOrTask')
instead of the Facade but it is not recommended. - The magical
call()
function accepts the class full namespace (\App\Containers\User\Tasks\GetAllUsersTask::class
) and the HiveApi caller style (Containers@GetAllUsersTask
). - There is also a
transactionalCall()
method available, that wraps everything in aDB::Transaction
(see below).
Passing arguments to the run()
function¶
$foo = Hive::call('Container@ActionOrTask', [$runArgument1, $runArgument2, $runArgument3]);
Calling other functions before calling the run()
¶
$foo = Hive::call('Container@ActionOrTask', [$runArgument], ['otherFunction1', 'otherFunction2']);
Calling other functions and pass them arguments before calling the run()
¶
<?php
$foo = Hive::call('Container@ActionOrTask', [$runArgument], [
[
'function1' => ['function1-argument1', 'function1-argument2']
],
[
'function2' => ['function2-argument1']
],
]);
$foo = Hive::call('Container@ActionOrTask', [$runArgument], [
'function-without-argument',
[
'function1' => ['function1-argument1', 'function1-argument2']
],
]);
$foo = Hive::call('Container@ActionOrTask', [], [
'function-without-argument',
[
'function1' => ['function1-argument1', 'function1-argument2']
],
'another-function-without-argument',
[
'function2' => ['function2-argument1', 'function2-argument2', 'function2-argument3']
],
]);
Transactional Magical Call¶
Sometimes, you want to wrap a call into one Database Transaction
(see theofficial Laravel Documentation).
Consider the following example: You want to create a new Team
and automatically assign yourself (i.e., your own
User
) to this newly created Team
. Your CreateTeamAction
may call a dedicated CreateTeamTask
and a
AssignMemberToTeamTask
afterwards. However, if the AssignMemberToTeamTask
fails, for unknown reasons, you may want
to “rollback” (i.e., remove) the newly created Team
from the database in order to keep the database in a valid state.
That’s where DB::transactions
comes into play!
HiveApi provides a transactionalCall($class, $params, $extraMethods)
method with the similar parameters as already
known from the call()
method. Internally, this method calls this call()
method anyways, but wraps it into a
DB::transaction
.
If any Exception
occurs during the execution of the $class
to be called, everything done in this context is
automatically rolled-back from the database. However, respective operations on the file system (e.g., you may also
have uploaded a profile picture for this Team
already that needs to be removed in this case) need to be performed
manually!
Typically, you may want to use the transactionalCall()
on the Controller
level!
Use Case Example¶
<?php
return Hive::call('User@ListUsersTask', [], ['ordered']);
// can be called this way as well Hive::call(ListUsersTask::class, [], ['ordered']);
return Hive::call('User@ListUsersTask', [], ['ordered', 'clients']);
return Hive::call('User@ListUsersTask', [], ['admins']);
return Hive::call('User@ListUsersTask', [], ['admins', ['roles' => ['manager', 'employee']]]);
The ListUsersTask class¶
<?php
namespace App\Containers\User\Tasks;
use App\Containers\User\Data\Criterias\AdminsCriteria;
use App\Containers\User\Data\Criterias\ClientsCriteria;
use App\Containers\User\Data\Criterias\RoleCriteria;
use App\Containers\User\Data\Repositories\UserRepository;
use App\Ship\Criterias\Eloquent\OrderByCreationDateDescendingCriteria;
use App\Ship\Parents\Tasks\Task;
class ListUsersTask extends Task
{
private $userRepository;
public function __construct(UserRepository $userRepository)
{
$this->userRepository = $userRepository;
}
public function run()
{
return $this->userRepository->paginate();
}
public function clients()
{
$this->userRepository->pushCriteria(new ClientsCriteria());
}
public function admins()
{
$this->userRepository->pushCriteria(new AdminsCriteria());
}
public function ordered()
{
$this->userRepository->pushCriteria(new OrderByCreationDateDescendingCriteria());
}
public function withRole($roles)
{
$this->userRepository->pushCriteria(new RoleCriteria($roles));
}
}