Skip to content

Commit 07a8566

Browse files
authored
Rewrite simpler Symfony framework doc (#94)
1 parent 171649e commit 07a8566

File tree

1 file changed

+62
-84
lines changed

1 file changed

+62
-84
lines changed

docs/getting-started.md

Lines changed: 62 additions & 84 deletions
Original file line numberDiff line numberDiff line change
@@ -10,6 +10,11 @@ return [
1010
];
1111
```
1212

13+
There is few things that can be configured in the bundle at the moment.
14+
But the most important one will be the `JobExecution` storage:
15+
- `filesystem` will create a file for each `JobExecution` in `%kernel.project_dir%/var/batch/{execution.jobName}/{execution.id}.json`
16+
- `dbal` will create a row in a table for each `JobExecution`
17+
1318
```yaml
1419
# config/packages/yokai_batch.yaml
1520
yokai_batch:
@@ -19,115 +24,88 @@ yokai_batch:
1924
# dbal: ~
2025
```
2126

22-
## Job Example
23-
24-
Let say you have a Doctrine ORM entity `App\Entity\User`,
25-
and a [JSON Lines](https://jsonlines.org/) file with information about these entities.
26-
27-
Your goal is to import this file in the database.
27+
> **note**: the default storage is `filesystem`, because it only requires a writeable filesystem.
28+
> But if you already have `doctrine/dbal` in your project, it is highly recommended to use it instead.
29+
> Because querying `JobExecution` in a filesystem might be slow, specially if you are planing to add UIs on top.
2830
29-
### Job in YAML
31+
As Symfony supports registering all classes in `src/` as a service,
32+
we can leverage this behaviour to register all jobs in `src/`.
33+
We will add a tag to every found class in `src/` that implements `Yokai\Batch\Job\JobInterface`:
3034

3135
```yaml
32-
# config/packages/yokai_batch.yaml (or anywhere else)
36+
# config/services.yaml
3337
services:
34-
job.import_users:
35-
class: Yokai\Batch\Job\Item\ItemJob
36-
tags: ['yokai_batch.job']
37-
arguments:
38-
$batchSize: 500
39-
$reader: !service
40-
class: Yokai\Batch\Job\Item\Reader\Filesystem\JsonLinesReader
41-
arguments:
42-
$filePath: !service
43-
class: Yokai\Batch\Job\Parameters\DefaultParameterAccessor
44-
arguments:
45-
$accessor: !service
46-
class: Yokai\Batch\Job\Parameters\JobExecutionParameterAccessor
47-
arguments: ['importFile']
48-
$default: '%kernel.project_dir%/var/import/users.jsonl'
49-
$processor: !service
50-
class: Yokai\Batch\Bridge\Symfony\Serializer\DenormalizeItemProcessor
51-
arguments:
52-
$denormalizer: '@serializer'
53-
$type: App\Entity\User
54-
$writer: '@yokai_batch.item_writer.doctrine_orm_object_writer'
38+
_defaults:
39+
_instanceof:
40+
Yokai\Batch\Job\JobInterface:
41+
tags: ['yokai_batch.job']
5542
```
5643
57-
Then the job will be triggered with its service id:
44+
## Your first job
45+
46+
In a Symfony project, we will prefer using one class per job, because service discovery is so easy to use.
47+
But also because it will be very far easier to configure your job using PHP than any other format.
48+
For instance, there is components that uses `Closure`, has static constructors, ...
49+
But keep in mind you can register your jobs with any other format of your choice.
5850

5951
```php
60-
/** @var \Yokai\Batch\Launcher\JobLauncherInterface $launcher */
61-
$launcher->launch('job.import_users');
62-
```
52+
<?php
6353
64-
### Job in sources
54+
namespace App\NamespaceOfYourChoice;
6555
66-
Although it is 100% possible to register jobs via a YAML file it can become very tedious.
56+
use Yokai\Batch\Bridge\Symfony\Framework\JobWithStaticNameInterface;
57+
use Yokai\Batch\Job\JobInterface;
6758
68-
As Symfony supports registering all classes in `src/` as a service,
69-
we can leverage this behaviour to register all jobs in `src/`.
59+
final class NameOfYourJob implements JobInterface, JobWithStaticNameInterface
60+
{
61+
public static function getJobName(): string
62+
{
63+
return 'job.name';
64+
}
7065
71-
```yaml
72-
# config/services.yaml
73-
services:
74-
_defaults:
75-
_instanceof:
76-
Yokai\Batch\Job\JobInterface:
77-
tags: ['yokai_batch.job']
66+
public function execute(JobExecution $jobExecution): void
67+
{
68+
// your logic here
69+
}
70+
}
7871
```
7972

73+
> **note**: when registering jobs with dedicated class, you can use the
74+
> [JobWithStaticNameInterface](../src/JobWithStaticNameInterface.php) interface
75+
> to be able to specify the job name of your service.
76+
> Otherwise, the service id will be used, and in that case, the service id is the FQCN.
77+
78+
### Triggering the job
79+
Then the job will be triggered with its name (or service id when not specified):
80+
8081
```php
8182
<?php
8283
83-
namespace App\Job;
84-
85-
use App\Entity\User;
86-
use Doctrine\Persistence\ManagerRegistry;
87-
use Symfony\Component\HttpKernel\KernelInterface;
88-
use Symfony\Component\Serializer\Normalizer\DenormalizerInterface;
89-
use Yokai\Batch\Bridge\Doctrine\Persistence\ObjectWriter;
90-
use Yokai\Batch\Bridge\Symfony\Serializer\DenormalizeItemProcessor;
91-
use Yokai\Batch\Job\AbstractDecoratedJob;
92-
use Yokai\Batch\Job\Item\ItemJob;
93-
use Yokai\Batch\Job\Item\Reader\Filesystem\JsonLinesReader;
94-
use Yokai\Batch\Job\Parameters\DefaultParameterAccessor;
95-
use Yokai\Batch\Job\Parameters\JobExecutionParameterAccessor;
84+
namespace App\MyNamespace;
85+
9686
use Yokai\Batch\Storage\JobExecutionStorageInterface;
9787
98-
final class ImportUsersJob extends AbstractDecoratedJob
88+
final class MyClass
9989
{
10090
public function __construct(
101-
JobExecutionStorageInterface $executionStorage,
102-
ManagerRegistry $doctrine,
103-
DenormalizerInterface $denormalizer,
104-
KernelInterface $kernel,
91+
private JobLauncherInterface $executionStorage,
10592
) {
106-
parent::__construct(
107-
new ItemJob(
108-
500,
109-
new JsonLinesReader(
110-
new DefaultParameterAccessor(
111-
new JobExecutionParameterAccessor('importFile'),
112-
$kernel->getProjectDir() . '/var/import/users.jsonl'
113-
)
114-
),
115-
new DenormalizeItemProcessor($denormalizer, User::class),
116-
new ObjectWriter($doctrine),
117-
$executionStorage
118-
)
119-
);
93+
}
94+
95+
public function method(): void
96+
{
97+
$this->launcher->launch('job.import_users');
12098
}
12199
}
122100
```
123101

124-
Then the job will be triggered with its service id:
102+
The job launcher that will be injected depends on the packages you have installed, order matter:
103+
- if `yokai/batch-symfony-messenger` is installed, you will receive a `Yokai\Batch\Bridge\Symfony\Messenger\DispatchMessageJobLauncher`
104+
- if `yokai/batch-symfony-console` is installed, you will receive a `Yokai\Batch\Bridge\Symfony\Console\RunCommandJobLauncher`
105+
- otherwise you will receive a `Yokai\Batch\Launcher\SimpleJobLauncher`
125106

126-
```php
127-
/** @var \Yokai\Batch\Launcher\JobLauncherInterface $launcher */
128-
$launcher->launch(\App\Job\ImportUsersJob::class);
129-
```
107+
## On the same subject
130108

131-
> **note**: when registering jobs with dedicated class, you can use the
132-
> [JobWithStaticNameInterface](../src/JobWithStaticNameInterface.php) interface
133-
> to be able to specify the job name of your service.
109+
- [What is a job execution storage ?](https://github.com/yokai-php/batch/blob/0.x/docs/domain/job-execution-storage.md)
110+
- [What is a job ?](https://github.com/yokai-php/batch/blob/0.x/docs/domain/job.md)
111+
- [What is a job launcher ?](https://github.com/yokai-php/batch/blob/0.x/docs/domain/job-launcher.md)

0 commit comments

Comments
 (0)