update README; add Laravel stubs; add form support

README.md

@@ -0,0 +1,27 @@
+# Pilot SDK
+
+## Installation
+
+```bash
+composer config repositories.pilot vcs "https://git.bluesquare.io/bluesquare/pilot-sdk.git"
+composer require bluesquare/pilot-sdk
+```
+
+## Configuration
+
+### Laravel
+
+Ajouter la clé d'API Pilot au `.env` :
+
+```dotenv
+PILOT_KEY=xxxxx
+```
+
+## Utilisation
+
+### Laravel
+
+```php
+php artisan pilot:metric MyMetric
+php artisan pilot:action MyAction
+```

src/Laravel/Commands/MakeAction.php

@@ -0,0 +1,47 @@
+<?php
+
+namespace Bluesquare\Pilot\Laravel\Commands;
+
+use Illuminate\Console\Command;
+use Illuminate\Support\Str;
+
+class MakeAction extends Command
+{
+    /**
+     * The name and signature of the console command.
+     *
+     * @var string
+     */
+    protected $signature = 'pilot:action {name?}';
+
+    /**
+     * The console command description.
+     *
+     * @var string
+     */
+    protected $description = 'Generate files for a Bluesquare Pilot action';
+
+    /**
+     * Execute the console command.
+     */
+    public function handle()
+    {
+        $name = $this->hasArgument('name')
+            ? $this->argument('name')
+            : $this->ask('What is the name of the action?', 'MakeSmoothie');
+
+        $contents = file_get_contents(__DIR__.'/../stubs/action.php');
+        $contents = str_replace('MakeSmoothie', $name, $contents);
+        $contents = str_replace('make-smoothie', Str::slug($name), $contents);
+        $path = app_path('Pilot/Actions/'.$name.'.php');
+
+        if (file_exists($path)) {
+            $this->error('Action already exists!');
+            return;
+        }
+
+        @mkdir(dirname($path), 0755, true);
+        file_put_contents($path, $contents);
+        $this->info('Action created successfully!');
+    }
+}

src/Laravel/Commands/MakeMetric.php

@@ -0,0 +1,47 @@
+<?php
+
+namespace Bluesquare\Pilot\Laravel\Commands;
+
+use Illuminate\Console\Command;
+use Illuminate\Support\Str;
+
+class MakeMetric extends Command
+{
+    /**
+     * The name and signature of the console command.
+     *
+     * @var string
+     */
+    protected $signature = 'pilot:metric {name?}';
+
+    /**
+     * The console command description.
+     *
+     * @var string
+     */
+    protected $description = 'Generate files for a Bluesquare Pilot metric';
+
+    /**
+     * Execute the console command.
+     */
+    public function handle()
+    {
+        $name = $this->hasArgument('name')
+            ? $this->argument('name')
+            : $this->ask('What is the name of the metric?', 'SmoothiesCount');
+
+        $contents = file_get_contents(__DIR__.'/../stubs/metric.php');
+        $contents = str_replace('SmoothiesCount', $name, $contents);
+        $contents = str_replace('smoothies-count', Str::slug($name), $contents);
+        $path = app_path('Pilot/Metrics/'.$name.'.php');
+
+        if (file_exists($path)) {
+            $this->error('Metric already exists!');
+            return;
+        }
+
+        @mkdir(dirname($path), 0755, true);
+        file_put_contents($path, $contents);
+        $this->info('Metric created successfully!');
+    }
+}

src/Laravel/PilotServiceProvider.php

@@ -35,6 +35,11 @@ class PilotServiceProvider extends ServiceProvider
         Route::any('api/pilot', function (Request $request) {
             return $this->handleRequest($request);
         });
+
+        $this->commands([
+            \Bluesquare\Pilot\Laravel\Commands\MakeAction::class,
+            \Bluesquare\Pilot\Laravel\Commands\MakeMetric::class,
+        ]);
     }
 
     protected function registerPilot()
@@ -49,6 +54,10 @@ class PilotServiceProvider extends ServiceProvider
 
                 if (class_exists($class)) {
                     $action = new $class;
+
+                    if (method_exists($action, 'form'))
+                        $this->pilot->form($action->slug(), [$action, 'form']);
+
                     $this->pilot->action($action->slug(), [$action, 'handle']);
                 }
             }

src/Laravel/stubs/action.php

@@ -0,0 +1,44 @@
+<?php
+
+namespace App\Pilot\Actions;
+
+use Bluesquare\Pilot\Entity\Action;
+
+class MakeSmoothie extends Action
+{
+    protected $slug = 'make-smoothie';
+
+    // Optional: you may remove this method if you don't need a form
+    public function form()
+    {
+        return [
+            'flavour' => [
+                'type' => 'text',
+                'label' => 'Flavour',
+                'required' => true,
+            ],
+        ];
+    }
+
+    /**
+     * Available params:
+     * @param $data array The form data
+     * @param $files array The uploaded files
+     * @param $entry mixed|null The Pilot entry ID to execute the action for
+     * @param $entries array<mixed> The Pilot entries ID to execute the action for
+     */
+    public function handle(array $data)
+    {
+        if ($data['flavour'] === 'mayonnaise') {
+            return $this->error('Please choose a better flavour');
+        }
+
+        // ...
+
+        return $this->action(
+            type: 'info',
+            title: 'Smoothie',
+            message: 'Your smoothie is ready!'
+        );
+    }
+}

src/Laravel/stubs/metric.php

@@ -0,0 +1,45 @@
+<?php
+
+namespace App\Pilot\Metrics;
+
+use Bluesquare\Pilot\Entity\Metric;
+
+class SmoothiesCount extends Metric
+{
+    protected $slug = 'smoothies-count';
+
+    /**
+     * Available params:
+     * @param $entry mixed|null The Pilot entry ID to compute the metric for
+     * @param $entries array<mixed> The Pilot entries ID to compute the metric for
+     */
+    public function compute($entry = null)
+    {
+        // Availability
+        // return $this->monitor(true);
+
+        // Progress bar
+        // return $this->progress(10, 100);
+
+        // Doughnut chart
+        // return $this->partition([
+        //    ['label' => 'Banana', 'value' => 90],
+        //    ['label' => 'Pineapple', 'value' => 89],
+        // ]);
+
+        // Trend chart
+        // return $this->trend([
+        //    ['label' => 'Banana', 'value' => 90],
+        //    ['label' => 'Pineapple', 'value' => 89],
+        // ]);
+
+        // Simple value
+        // return $this->value(12);
+
+        // Simple value with filters
+        return $this->filters([
+            $this->filter('Banana', 'banana', fn () => $this->value(90, 10)),
+            $this->filter('Pineapple', 'pineapple', fn () => $this->value(89, 20)),
+        ]);
+    }
+}

src/Pilot.php

@@ -9,6 +9,7 @@ class Pilot
      */
     protected $registry = [
         'action' => [],
+        'form' => [],
         'metric' => [],
     ];
 
@@ -24,6 +25,15 @@ class Pilot
         }
     }
 
+    public function form($slug, callable $function)
+    {
+        $this->register('form', $slug, function () use ($function) {
+            return [
+                'json' => $function(),
+            ];
+        });
+    }
+
     public function action($slug, callable $function)
     {
         $this->register('action', $slug, $function);