One of our main goals when building Zenaton is to make sure our product is simple to use. We believe what is important to you is your business logic and that you should be able to start working on complex business workflows without having to dive into deep technical documentation first.
If you’re currently building software using PHP and the Laravel framework, we’re going to walk you through getting started with Zenaton.
Before we get started, you need to have a Laravel project already set up. If you don’t and still want to follow, I suggest you read installation instructions from Laravel documentation. I’m using version 5.7.28 of Laravel at the time of writing. Make sure you are able to see the default Laravel welcome page before continuing.
Before jumping into the terminal or writing code, you need to grab your Zenaton credentials from our website. You can register for a free account and, then retrieve your credentials on the API page.
To be able to start workflows and execute tasks asynchronously, you will need to install the Zenaton Agent. The Agent will connect to our infrastructure, execute jobs when it is instructed and send results back so they can be reported on your dashboard. To install the Agent, run the following command in your terminal:
curl https://install.zenaton.com | shIf you don’t feel like piping something from the internet into a shell, it’s okay. You can retrieve the install script, read it, and then execute it with the following commands:
curl https://install.zenaton.com/ -o install-zenaton.sh
cat install-zenaton.sh
sh install-zenaton.shAfter running the install script, the Agent should already be running. If you want to stop the Agent, use zenaton stop. If you need to start the Agent again after stopping it, or because you restarted your computer, you can use the command zenaton start.
Now we have everything we need. It’s time to work on our project.
We need to add our Zenaton PHP library using Composer.
composer require zenaton/zenaton-laravelThis will install our package and the necessary dependencies. We also need to publish the package default configuration file.
php artisan vendor:publish --tag=zenaton-configNow, lets put the credentials in the .env file of the project using the following content:
ZENATON_APP_ID=CHANGEME
ZENATON_API_TOKEN=PleaseReplaceThisWithYourApiToken
ZENATON_APP_ENV=devMake sure to replace the first two values with the credentials you got on the Zenaton dashboard.
The last step is to make the Agent “listen”: The Agent will authenticate itself using the credentials from the configuration and will get ready to execute jobs:
zenaton listen --laravelWe’re done. You can now run asynchronous tasks as code and orchestrate multiple task executions through the Zenaton workflow engine.
Now, where do we write tasks and workflows? Well, in Zenaton, tasks and workflows are just PHP classes. Let’s write our first task together and see how to run it asynchronously using the Zenaton workflow engine.
Laravel does not impose anything related to code organization so the same principle applies for tasks and workflows. You need to write a PHP class that is able to be autoloaded by Composer. In the default Laravel configuration, it means it has to be in the app/ directory, but you’re free to put it in any sub-directory of your choice.
If you are using the default Laravel directory structure, I suggest you put your tasks in app/Zenaton/Tasks and your workflows in app/Zenaton/Workflows. We will be using artisan commands to generate tasks and workflows, and those are the directories that they use.
Let’s write the task. It will be very simple, but it’s for demonstration purposes. Our task will only receive a string parameter, which will be a message, and it will write this message inside the Laravel log file.
Let’s generate the tasks using our artisan command.
php artisan zenaton:make:task LogTaskOpen the file that was generated in app/Tasks/LogTask.php and update it with the following content:
<?php
namespace App\Zenaton\Tasks;
use Zenaton\Interfaces\TaskInterface;
use Zenaton\Traits\Zenatonable;
class LogTask implements TaskInterface
{
use Zenatonable;
/** @var string */
private $message;
/**
* @param string $message
*/
public function __construct($message)
{
$this->message = $message;
}
public function handle()
{
\Log::info($this->message);
}
}Now, if you try to execute this task using Laravel Tinker — A REPL for Laravel projects — while observing the Laravel log file at the same time,you can see some logs being written.
(new App\Zenaton\Tasks\LogTask("Hello from zenaton"))->dispatch();
You should also notice that your task is executed in the background: You can continue to write other instructions in Tinker while your task is executing.
Remember that you are free to do whatever you want in your tasks: query databases, send emails, resize images, export some data to files, etc. All the intensive work of your application that can be asynchronous can be done in tasks.
Here, we were using Tinker to dispatch the task, but you can put the dispatch instruction of a task wherever you want: in actions, in commands, in services, in observers. Really it’s up to you.
You can do a lot with tasks only, but workflows will get you all the power of Zenaton.
We will implement a small workflow doing the following:
- Run the LogTask to log a message.
- Wait for 10 seconds.
- Run the LogTask a second time to log another message.
The workflow is simple but it’s just a first step for you to see how to write a workflow and where to put the code.
Start by generating the workflow using the artisan command.
php artisan zenaton:make:workflow ExampleWorkflowOpen the generated file app/Zenaton/Workflows/ExampleWorkflow.php and update it with the following content:
<?php
namespace App\Zenaton\Workflows;
use App\Zenaton\Tasks\LogTask;
use Zenaton\Interfaces\WorkflowInterface;
use Zenaton\Tasks\Wait;
use Zenaton\Traits\Zenatonable;
class ExampleWorkflow implements WorkflowInterface
{
use Zenatonable;
public function handle()
{
(new LogTask("Hello from"))->execute();
(new Wait())->seconds(10)->execute();
(new LogTask("a Zenaton workflow"))->execute();
}
}We can dispatch the workflow in Laravel Tinker to see that everything work as expected:
(new App\Zenaton\Workflows\ExampleWorkflow())->dispatch();
And that’s it. You are now able to write tasks and orchestrate them using workflows. You can read more about the advanced features of workflows in the documentation.
If there are other features you would like to see in the Laravel package, feel free to write some feedback in the comments. If you need some inspiration about what kind of workflows you could implement, you can take a look at some use-cases we wrote.
If you have any question, feel free to reach out.
