Merge pull request #6 from oceandba/release/v1.0.0

Release v1.0.0

.github/ISSUE_TEMPLATE/bug_report.md

@@ -0,0 +1,38 @@
+---
+name: Bug report
+about: Create a report to help us improve
+title: ''
+labels: ''
+assignees: ''
+
+---
+
+**Describe the bug**
+A clear and concise description of what the bug is.
+
+**To Reproduce**
+Steps to reproduce the behavior:
+1. Go to '...'
+2. Click on '....'
+3. Scroll down to '....'
+4. See error
+
+**Expected behavior**
+A clear and concise description of what you expected to happen.
+
+**Screenshots**
+If applicable, add screenshots to help explain your problem.
+
+**Desktop (please complete the following information):**
+ - OS: [e.g. iOS]
+ - Browser [e.g. chrome, safari]
+ - Version [e.g. 22]
+
+**Smartphone (please complete the following information):**
+ - Device: [e.g. iPhone6]
+ - OS: [e.g. iOS8.1]
+ - Browser [e.g. stock browser, safari]
+ - Version [e.g. 22]
+
+**Additional context**
+Add any other context about the problem here.

.github/ISSUE_TEMPLATE/custom.md

@@ -0,0 +1,10 @@
+---
+name: Custom issue template
+about: Describe this issue template's purpose here.
+title: ''
+labels: ''
+assignees: ''
+
+---
+
+

.github/ISSUE_TEMPLATE/feature_request.md

@@ -0,0 +1,20 @@
+---
+name: Feature request
+about: Suggest an idea for this project
+title: ''
+labels: ''
+assignees: ''
+
+---
+
+**Is your feature request related to a problem? Please describe.**
+A clear and concise description of what the problem is. Ex. I'm always frustrated when [...]
+
+**Describe the solution you'd like**
+A clear and concise description of what you want to happen.
+
+**Describe alternatives you've considered**
+A clear and concise description of any alternative solutions or features you've considered.
+
+**Additional context**
+Add any other context or screenshots about the feature request here.

.styleci.yml

@@ -0,0 +1,6 @@
+preset: laravel
+
+enabled:
+  - length_ordered_imports
+disabled:
+  - alpha_ordered_imports

.travis.yml

@@ -0,0 +1,34 @@
+dist: xenial
+language: php
+
+env:
+  global:
+    - SETUP=stable
+
+matrix:
+  fast_finish: true
+  include:
+    - php: 7.1
+    - php: 7.1
+      env: SETUP=lowest
+    - php: 7.2
+    - php: 7.2
+      env: SETUP=lowest
+    - php: 7.3
+    - php: 7.3
+      env: SETUP=lowest
+    - php: 7.4snapshot
+
+cache:
+  directories:
+  - $HOME/.composer/cache
+
+before_install:
+  - phpenv config-rm xdebug.ini || true
+  - travis_retry composer self-update
+
+install:
+  - if [[ $SETUP = 'stable' ]]; then travis_retry composer update --prefer-dist --no-interaction --prefer-stable --no-suggest; fi
+  - if [[ $SETUP = 'lowest' ]]; then travis_retry composer update --prefer-dist --no-interaction --prefer-lowest --prefer-stable --no-suggest; fi
+
+script: vendor/bin/phpunit

LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2019 OceanDBA (https://www.oceandba.com/)
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

README.md

@@ -2,9 +2,153 @@
     Graphitti
 </h2>
 
+<p align="center">
+    <a href="https://packagist.org/packages/oceandba/graphitti"><img src="https://poser.pugx.org/oceandba/graphitti/v/stable?format=flat-square" alt="Latest Stable Version"></a>
+    <a href="https://packagist.org/packages/oceandba/graphitti"><img src="https://poser.pugx.org/oceandba/graphitti/v/unstable?format=flat-square" alt="Latest Unstable Version"></a>
+    <a href="https://travis-ci.org/oceandba/graphitti"><img src="https://travis-ci.org/oceandba/graphitti.svg?branch=master" alt="Build Status"></a>
+    <a href="https://github.styleci.io/repos/222423453"><img src="https://github.styleci.io/repos/222423453/shield?branch=master" alt="StyleCI"></a>
+    <a href="https://packagist.org/packages/oceandba/graphitti"><img src="https://poser.pugx.org/oceandba/graphitti/license?format=flat-square" alt="License"></a>
+    <a href="https://packagist.org/packages/oceandba/graphitti"><img src="https://poser.pugx.org/oceandba/graphitti/downloads?format=flat-square" alt="Total Downloads"></a>
+</p>
+
 ## Introduction
+The aim of Graphitti is to ease the use of the [Render URL API](https://graphite.readthedocs.io/en/latest/render_api.html) provided by graphite.
+Graphitti provides a expressive fluid API around the Render URL API.
 
 ## License
 Graphitti is open-sourced software licensed under the [MIT license](http://opensource.org/licenses/MIT)
 
 ### Installation
+This packages works for Laravel versions 5.* and ^6.0 only.
+
+Install Graphitti as you would with any other dependency managed by Composer:
+
+```bash
+composer require oceandba/graphitti
+```
+
+### Configuration
+
+To publish the configuration use the command :
+
+```bash
+php artisan vendor:publish --provider="OceanDBA\Graphitti\GraphittiServiceProvider" --tag="graphitti-config"
+```
+
+This will create the file ```config/graphitti.php```. Use this file to configure your graphite hosts; the file should be self-explanatory and 
+contains the appropriate configurations needed for you to get started.
+
+### Usage
+
+### Using Targets
+
+You can create a new [Target](https://graphite.readthedocs.io/en/latest/render_api.html#target) using the ```OceanDBA\Graphitti\Metrics\Target``` class as
+follows :
+
+```php
+use OceanDBA\Graphitti\Metrics\Target;
+
+$target = Target::make('oceandba.server1.load', 'Server-load-1');
+```
+
+The ```Target``` takes two parameters :
+1) The path
+2) An optional name for the Target
+
+### Applying functions to Target
+
+To apply a function to the ```Target``` use the function name as a method call on the Target instance and pass parameters to it :
+
+```php
+Target::make('oceandba.server1.load', 'Server-load-1')->add(10);
+```
+
+You can also chain the function calls :
+
+```php
+Target::make('oceandba.server1.load', 'Server-load-1')
+      ->add(10)
+      ->aggregate('sum');
+```
+
+Refer to the [Graphite Docs](https://graphite.readthedocs.io/en/latest/functions.html) for list of available functions.
+
+The ```Target``` class uses the ```Macroable``` trait of Laravel. So you are free to add your own methods to the class.
+
+```php
+use OceanDBA\Graphitti\Metrics\Target;
+
+// ...
+
+public function boot()
+{
+    Target::macro('validate', function () {
+        if(strpos($this->value(), 'oceandba') === false) {
+            throw new \InvalidArgumentException('Target is invalid');
+        }
+
+        return $this;
+    });
+}
+```
+
+```php
+Target::make('oceandba.server1.load', 'Server-load-1')->validate();
+```
+
+### Using GraphitePoints
+
+The ```GraphitePoints``` class provides an expressive syntax to retrieve DataPoints from Graphite. You should supply at least one ```Target``` to the 
+```GraphitePoints```.
+
+```php
+use GraphitePoints;
+use OceanDBA\Graphitti\Metrics\Target;
+
+$dataPointsCollection = GraphitePoints::addTarget(Target::make('oceandba.server1.load', 'Server-load-1'))
+                                      ->addTarget(Target::make('oceandba.server2.load', 'Server-load-2'))
+                                      ->render();
+```
+
+This will return a ```OceanDBA\Graphitti\Series\DataPointsCollection```. The object contains a collection of ```OceanDBA\Graphitti\Series\DataPoints```,
+both classes are ```Macroable```.
+
+### Contraint from/until
+
+You can add time period constrains using the ```from``` and ```until``` methods available on the ```GraphitePoints```.
+
+```php
+ GraphitePoints::addTarget(Target::make('oceandba.server1.load', 'Server-load-1'))
+               ->addTarget(Target::make('oceandba.server2.load', 'Server-load-2'))
+               ->from('-1h')
+               ->until('now')
+               ->render()
+```
+
+The methods accept ```Carbon``` instances as well as relative time string. Refer to the [Graphite Docs](https://graphite.readthedocs.io/en/latest/render_api.html#from-until)
+for how to form relative time string. 
+
+### Additional graph parameters
+
+You can add graph parameters using ```addParameter``` method on ```GraphitePoints``` :
+
+```php
+GraphitePoints::addTarget(Target::make('oceandba.server1.load', 'Server-load-1'))
+               ->addTarget(Target::make('oceandba.server2.load', 'Server-load-2'))
+               ->from('-1h')
+               ->until('now')
+               ->addParameter('maxDataPoints', 50)
+               ->render()
+```
+
+Refer to the [Graphite Docs](https://graphite.readthedocs.io/en/latest/render_api.html#graph-parameters) for full list of accepted parameters.
+
+### Credits
+Big Thanks to all developers who worked hard to create something amazing!
+
+### Creator
+[![OceanDBA Ltd](https://img.shields.io/badge/Author-OceanDBA-blue.svg)](https://www.oceandba.com/)
+
+Twitter: [@OceanDBA](https://twitter.com/oceandba)
+<br/>
+GitHub: [OceanDBA Ltd](https://github.com/oceandba)

composer.json

@@ -15,6 +15,7 @@
     "require": {
         "php": "^7.1.3",
         "ext-json": "*",
+        "guzzlehttp/guzzle": "~6.0",
         "illuminate/contracts": "~5.8.0|^6.0|^7.0",
         "nesbot/carbon": "^2.0"
     },
@@ -35,17 +36,26 @@
     },
     "extra": {
         "branch-alias": {
-            "dev-master": "1.x-dev"
+            "dev-master": "2.x-dev"
         },
         "laravel": {
             "providers": [
                 "OceanDBA\\Graphitti\\GraphittiServiceProvider"
-            ]
+            ],
+            "aliases": {
+                "GraphitePoints": "OceanDBA\\Graphitti\\Facades\\GraphitePoints"
+            }
         }
     },
     "config": {
         "sort-packages": true
     },
+    "scripts": {
+        "test:unit": "@php vendor/bin/phpunit",
+        "test": [
+            "@test:unit"
+        ]
+    },
     "minimum-stability": "dev",
     "prefer-stable": true
 }

config/graphitti.php

@@ -0,0 +1,31 @@
+<?php
+
+return [
+
+    /*
+    |--------------------------------------------------------------------------
+    | Default Graphite Host Name
+    |--------------------------------------------------------------------------
+    |
+    | Here you may specify which of the hosts below you wish
+    | to use as your default host for all graphite work.
+    | Of course you may use many hosts at once using
+    | the Graphitti library.
+    |
+    */
+
+    'default' => env('GRAPHITE_HOST', 'graphite'),
+
+    /*
+    |--------------------------------------------------------------------------
+    | Graphite Hosts
+    |--------------------------------------------------------------------------
+    |
+    | Here are each of the hosts setup for your application.
+    |
+    */
+
+    'hosts' => [
+        'graphite' => env('GRAPHITE_URL', 'https://graphite.example.com'),
+    ],
+];

src/Concerns/Makable.php

@@ -0,0 +1,17 @@
+<?php
+
+namespace OceanDBA\Graphitti\Concerns;
+
+trait Makable
+{
+    /**
+     * Creates and return a new instance
+     * with the given parameters.
+     *
+     * @return self
+     */
+    public static function make()
+    {
+        return new static(...func_get_args());
+    }
+}

src/Contracts/Metric.php

@@ -0,0 +1,8 @@
+<?php
+
+namespace OceanDBA\Graphitti\Contracts;
+
+interface Metric
+{
+    //
+}

src/Contracts/TimeSeries.php

@@ -0,0 +1,8 @@
+<?php
+
+namespace OceanDBA\Graphitti\Contracts;
+
+interface TimeSeries
+{
+    //
+}