Skip to content

Commit

Permalink
Update documentation about selectors
Browse files Browse the repository at this point in the history
  • Loading branch information
antonmedv committed Sep 9, 2022
1 parent f0f8116 commit 9676945
Show file tree
Hide file tree
Showing 2 changed files with 49 additions and 32 deletions.
1 change: 1 addition & 0 deletions docs/UPGRADE.md
Original file line number Diff line number Diff line change
Expand Up @@ -67,6 +67,7 @@
11. Replace `local()` tasks with combination of `once()` and `runLocally()` func.
12. Replace `locateBinaryPath()` with `which()` func.
13. Configuration property `default_stage` is not supported.
14. Replace `onHosts()` and `onStage()` with [labels & selectors](selector.md).

### Step 2: Deploy

Expand Down
80 changes: 48 additions & 32 deletions docs/selector.md
Original file line number Diff line number Diff line change
@@ -1,11 +1,14 @@
# Selector

Deployer uses the selector to choose hosts. Each host can have a set of labels.
Labels are key-value pairs. For example, `stage: production` or `role: web`.
Labels are key-value pairs.

For example, `stage: production` or `role: web`.

You can use labels to select hosts. For example, `dep deploy stage=production`
will deploy to all hosts with `stage: production` label.

For example, lets define two labels **type** and **env** of our hosts:
Let's define two labels **type** and **env** of our hosts:

```php
host('web.example.com')
Expand Down Expand Up @@ -50,9 +53,9 @@ task info
## Selector syntax

Label syntax is represented by [disjunctive normal form](https://en.wikipedia.org/wiki/Disjunctive_normal_form)
(**OR of ANDs).
(**OR of ANDs**).

For example, `type=web,env=prod` is a selector of: `type=web` **or** `env=prod`.
For example, `type=web,env=prod` is a selector of: `type=web` **OR** `env=prod`.

```bash
$ dep info 'type=web,env=prod'
Expand All @@ -64,7 +67,7 @@ task info
As you can see both hosts are selected (as both of them has `env: prod` label).

We can use `&` to define **AND**. For example, `type=web & env=prod` is a selector
for hosts with `type: web` **and** `env: prod` labels.
for hosts with `type: web` **AND** `env: prod` labels.

```bash
$ dep info 'type=web & env=prod'
Expand Down Expand Up @@ -104,10 +107,46 @@ task info
[web.example.com] type:web env:prod
```

And a few hosts `dep info web.example.com db.example.com` is a same as
`dep info alias=web.example.com,alias=db.example.com`.
```bash
$ dep info 'web.example.com' 'db.example.com'
$ # Same as:
$ dep info 'alias=web.example.com,alias=db.example.com'
````

## Using select() function

# Labels in YAML
You can use [select()](api.md#select) function to select hosts by selector from PHP code.

```php
task('info', function () {
$hosts = select('type=web,env=prod');
foreach ($hosts as $host) {
writeln('type:' . $host->get('labels')['type'] . ' env:' . $host->get('labels')['env']);
}
});
```
Or you can use [on()](api.md#on) function to run a task on selected hosts.
```php
task('info', function () {
on(select('all'), function () {
writeln('type:' . get('labels')['type'] . ' env:' . get('labels')['env']);
});
});
```
## Task selectors
To restrict a task to run only on selected hosts, you can use [select()](tasks.md#select) method.
```php
task('info', function () {
// ...
})->select('type=web,env=prod');
```
## Labels in YAML
You can also define labels in YAML recipe. For example:
Expand All @@ -120,7 +159,7 @@ hosts:
env: prod
```
But make sure to distinguish between `env` and `labels.env` keys.
But make sure to distinguish between `env` and `labels.env` keys.
`env` is a configuration key, and `labels.env` is a label.
```php
Expand All @@ -136,26 +175,3 @@ $ dep info env=prod
task info
[web.example.com] env:production labels.env:prod
```

## Using selectors in PHP

You can use [select()](api.md#select) function to select hosts by selector from PHP code.

```php
task('info', function () {
$hosts = select('type=web,env=prod');
foreach ($hosts as $host) {
writeln('type:' . $host->get('labels')['type'] . ' env:' . $host->get('labels')['env']);
}
});
```

Or you can use [on()](api.md#on) function to run a task on selected hosts.

```php
task('info', function () {
on(select('all'), function () {
writeln('type:' . get('labels')['type'] . ' env:' . get('labels')['env']);
});
});
```

0 comments on commit 9676945

Please sign in to comment.