Skip to content
This repository has been archived by the owner on Jun 23, 2021. It is now read-only.

Commit

Permalink
Merge branch '0.8'
Browse files Browse the repository at this point in the history
  • Loading branch information
lode committed Mar 22, 2016
2 parents 4cc8c89 + 48515fd commit 758640f
Show file tree
Hide file tree
Showing 10 changed files with 438 additions and 41 deletions.
187 changes: 150 additions & 37 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -2,57 +2,181 @@

Debby checks your project dependencies and tells you when to update.

1. Install her via composer.
2. Setup a cronjob to let her notify you regulary.
3. Sit back and relax. Take a :coffee: or :tea: or :beer:
1. [Set the package manager path](/README.md#point-at-your-managers).
2. [Configure channels](/README.md#pick-your-channels) where to notify you.
3. [Install via composer and setup a cronjob*](/README.md#get-debby-running) to let her notify you regularly.
4. Sit back and relax. Take a :coffee: or :tea: or :beer:

Debby will tell you when you need to get working.
This lets you stay on top of your dependencies and deploy security releases quickly. :sunglasses:

By the way, Debby will tell when she needs an update herself. You don't need to do anything. :sparkles:

\* You can use Debby [without cronjobs](/README.md#without-cronjob-all-options) as well.

## Installation
---

[Use Composer](http://getcomposer.org/). And use require to get the latest stable version:
- [Point at your managers](/README.md#point-at-your-managers)
- [Composer](/README.md#composer)
- [Pick your channels](/README.md#pick-your-channels)
- [GitHub](/README.md#github)
- [Trello](/README.md#trello)
- [Slack](/README.md#slack)
- [Email](/README.md#email)
- [Get Debby running](/README.md#get-debby-running)
- [Without `options.json`: GitHub channel only](/README.md#without-optionsjson-github-channel-only)
- [Without cronjob: all options](/README.md#without-cronjob-all-options)
- [FAQ](/README.md#faq)
- [Contribute](/README.md#contribute)
- [License](/README.md#license)

``` sh
composer require alsvanzelf/debby
## Point at your managers

Debby can check multiple package manager. Although at the moment, she just knows about one. Composer.
If you know want to add others, you're welcome to [contribute](/README.md#contribute).

#### Composer

To check Composer nothing special is needed.

If you don't run Debby from her vendor directory, you'll need to add an `root_dir` option.
This tells Debby where to find the `composer.json`/`lock` files.

``` json
{
"root_dir": "/path/to/project/"
}
```

## Pick your channels

## Getting started
Debby can communicate via multiple channels. Mostly, you'll only want to setup a single one. But multiple at the same time is not a problem.

#### GitHub

There are three ways to talk to Debby.
Debby creates an issue at your GitHub repository for each updatable package.

#### Out of the box: GitHub issues
Getting started:

Set up a cron to run debby periodically.
You just provide the repository and your personal access token.
1. [Generate a personal access token](https://github.com/settings/tokens) in your GitHub settings.
2. Choose the scope `public_repo` ("Access public repositories") or `repo` ("Full control of private repositories").
3. Add an `notify_github` option:

`0 8 * * * php /var/www/vendor/alsvanzelf/debby/notify.php example/project personal-access-token`
``` json
{
"notify_github": {
"repository": "example/project",
"token": "personal access token"
}
}
```

This will create issues on that repository for packages that need updates.
#### Trello

#### All options
Debby adds a card in your Trello board for each updatable package.

If you want to email the updatable packages, or adjust the default options, provide the path of a options file.
Getting started:

`0 8 * * Mon php /var/www/vendor/alsvanzelf/debby/notify.php /var/www/debby-options.json`
1. [Authenticate at Trello](https://trello.com/1/authorize?name=Debby&expiration=never&scope=read,write&response_type=token&key=9b174ff1ccf5ca94f1c181bc3d802d4b) and copy the token.
2. Decide which list in your board should get the cards.
3. Open a card currently in that list (or create one temporarly), add `.json` to your browser address bar and go.
4. Look for `"idList":` and copy the id behind it.
5. Add an `notify_trello` option:

See [Options](/README.md#Options) for all possible options.
``` json
{
"notify_trello": {
"list": "list id",
"token": "personal token"
}
}
```

#### Custom
#### Slack

You can also call debby from php and do what every you want.
Debby sends a message to a Slack channel for each updatable package.
If multiple packages are found updatable in one run, it adds a single message for all.

``` php
require_once(__DIR__.'/vendor/autoload.php');
Getting started:

1. [Install an incoming webhook](https://slack.com/apps/A0F7XDUAZ-incoming-webhooks) on your team's channel.
2. Copy the "Webhook URL", it looks like `https://hooks.slack.com/services/T00000000/B00000000/XXXXXXXXXXXXXXXXXXXXXXXX`.
3. You don't need to adjust any other setting on the webhook.
4. Add an `notify_slack` option:

``` json
{
"notify_slack": {
"webhook": "https://hooks.slack.com/services/T00000000/B00000000/XXXXXXXXXXXXXXXXXXXXXXXX"
}
}
```

#### Email

Debby sends an email to your inbox with a list of currently updatable packages.

Getting started:

1. Decide on the recipient of the messages.
2. Collect login details for your SMTP server.
3. Add an `notify_email` option:

``` json
{
"notify_email": {
"recipient": "devops@example.com",
"host": "smtp.example.com",
"port": 587,
"security": "ssl",
"user": "devops@example.com",
"pass": "password"
}
}
```

## Get Debby running

0. Go to your project: `cd /var/www/`
1. Install Debby: `composer require alsvanzelf/debby`
2. Define your options: `nano debby.json`

use alsvanzelf\debby;
``` json
{
"root_dir": "/path/to/project/",
"notify_github": {
"repository": "example/project",
"token": "user token"
},
"notify_slack": {
"webhook": "https://hooks.slack.com/services/T00000000/B00000000/XXXXXXXXXXXXXXXXXXXXXXXX"
}
}
```

3. Run regularly: `crontab -e`

``` sh
0 8 * * * php /var/www/vendor/alsvanzelf/debby/notify.php /var/www/debby.json
```

See [example/options.json](/example/options.json) for a complete example.

#### Without `options.json`: GitHub channel only

If you only want to notify via [GitHub issues](/README.md#github), you can setup Debby without `options.json`.
Just provide the repository and your personal access token directly to the crontab:

``` sh
0 8 * * * php /var/www/vendor/alsvanzelf/debby/notify.php example/project personal-access-token
```

#### Without cronjob: all options

You can also call Debby from php and do what every you want.

``` php
$options = [
'root_dir' => '/path/to/project/',
'notify_github' => [
'repository' => 'example/project',
// ...
Expand All @@ -71,17 +195,6 @@ $debby->notify($packages);
See [example/custom.php](/example/custom.php) for a complete example.


## Options

Option | Type | Default | Explanation
------ | ---- | ------- | -----------
`root_dir` | `string` | one directory above `vendor/` | Root directory of the project.
`notify_github` | `array` | `null` | Supply to create issues for each package update. It should contain keys for: <ul><li>`repository`: i.e. `lode/debby`</li><li>`token`: a personal access token, [generate one in your settings](https://github.com/settings/tokens)</li></ul>
`notify_email` | `array` | `null` | Supply to send an email with the updatable packages. It should contain keys for: <ul><li>`recipient`: i.e. `devops@example.com`</li><li>`host`: smtp hostname</li><li>`port`: an int</li><li>`security`: i.e. `ssl`, `tls`</li><li>`user`: username to login to the smtp host, usually the same as the senders email address</li><li>`pass`: plain text password</li></ul>

See [example/options.json](/example/options.json) for a complete example.


## FAQ

#### Why does Debby tell me to update above the composer constraint?
Expand All @@ -95,12 +208,12 @@ You don't trust her? She's open source you know. Anyway, Debby runs just fine in
Just take into account that Debby will run just as fine while bisecting on old commits and notify you for updates since then.


## Contributing
## Contribute

Pull Requests or issues are welcome!


## Licence
## License

[MIT](/LICENSE)

Expand Down
13 changes: 10 additions & 3 deletions example/custom.php
Original file line number Diff line number Diff line change
Expand Up @@ -5,12 +5,19 @@
use alsvanzelf\debby;

$options = [
'root_dir' => '/path/to/project/',
'notify_github' => [
'root_dir' => '/path/to/project/',
'notify_github' => [
'repository' => 'example/project',
'token' => 'user token',
],
'notify_email' => [
'notify_trello' => [
'list' => 'list id',
'token' => 'user token',
],
'notify_slack' => [
'webhook' => 'https://hooks.slack.com/services/T00000000/B00000000/XXXXXXXXXXXXXXXXXXXXXXXX',
],
'notify_email' => [
'recipient' => 'devops@example.com',
'host' => 'smtp.example.com',
'port' => 587,
Expand Down
7 changes: 7 additions & 0 deletions example/options.json
Original file line number Diff line number Diff line change
Expand Up @@ -4,6 +4,13 @@
"repository": "example/project",
"token": "user token"
},
"notify_trello": {
"list": "list id",
"token": "user token"
},
"notify_slack": {
"webhook": "https://hooks.slack.com/services/T00000000/B00000000/XXXXXXXXXXXXXXXXXXXXXXXX"
},
"notify_email": {
"recipient": "devops@example.com",
"host": "smtp.example.com",
Expand Down
117 changes: 117 additions & 0 deletions src/channel/slack.php
Original file line number Diff line number Diff line change
@@ -0,0 +1,117 @@
<?php

namespace alsvanzelf\debby\channel;

use alsvanzelf\debby;
use alsvanzelf\debby\exception;
use alsvanzelf\debby\package;
use alsvanzelf\debby\template;

class slack implements channel {

private $client;

/**
* setup a connection with slack
*
* @param array $options {
* @var $webhook url to post messages to
* }
*/
public function __construct(array $options=[]) {
if (empty($options['webhook'])) {
$e = new exception('slack notifications require a webhook option');
$e->stop();
}

$this->client = curl_init($options['webhook']);

$curl_options = [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_SSL_VERIFYPEER => true,
CURLOPT_SSL_VERIFYHOST => 2,
CURLOPT_HTTPHEADER => [
'Content-type: application/json',
'User-Agent: Debby/'.debby\debby::get_version().' (https://github.com/lode/debby)',
],
];

curl_setopt_array($this->client, $curl_options);
}

/**
* close the curl handle
*/
public function __destruct() {
curl_close($this->client);
}

/**
* send a message for updatable packages
*
* @param array<package> $packages as returned by debby->check()
* @return void
*/
public function send(array $packages) {
if (count($packages) === 1) {
$text = $this->get_package_message($packages[0], $template='slack_single');
}
else {
$package_lines = '';
foreach ($packages as $package) {
$package_lines .= $this->get_package_message($package, $template='slack_multiple_line');
}

$text = template::parse('slack_multiple', ['packages' => $package_lines]);
}

$this->send_message($text);
}

/**
* get a parsed message for a single package
*
* @param package $package
* @param string $template one of 'slack_multiple_line' or 'slack_single'
* @return string
*/
private function get_package_message(package\package $package, $template) {
$template_data = [
'name' => $package->get_name(),
'manager' => $package->get_manager_name(),
'required' => $package->get_required_version(),
'installed' => $package->get_installed_version(),
'latest' => $package->get_latest_version(),
];

return template::parse($template, $template_data);
}

/**
* send a message to a channel
*
* @param string $text
* @return void
*/
private function send_message($text) {
$arguments = json_encode([
'username' => 'Debby',
'icon_emoji' => ':girl::skin-tone-2:',
'text' => $text,
]);

$curl_options = [
CURLOPT_POST => true,
CURLOPT_POSTFIELDS => $arguments,
];
curl_setopt_array($this->client, $curl_options);

curl_exec($this->client);

if (curl_errno($this->client)) {
$e = new exception('slack curl error "'.curl_error($this->client).'"');
$e->stop();
}
}

}
Loading

0 comments on commit 758640f

Please sign in to comment.