Merge pull request #3 from dreamfactorysoftware/add-examples

Add examples and README

README.md

@@ -1,28 +1,111 @@
+**This guide is not a strict instruction. You don't have to follow every part of it.**
+
 ## DreamFactory Skeleton
 
-> **Note:** This repository contains the code needed to create a new connector of the DreamFactory platform. If you want the full DreamFactory platform, visit the main [DreamFactory repository](https://github.com/dreamfactorysoftware/dreamfactory).
+> **Note:** This repository contains the code needed to create a new connector of the DreamFactory platform. 
+If you want the full DreamFactory platform, visit the 
+main [DreamFactory repository](https://github.com/dreamfactorysoftware/dreamfactory).
+
+You are free to integrate anything [Laravel](https://laravel.com/docs/5.6/) provides, note that DreamFactory uses Laravel 5.6 version.
+
+You can clone content of this repository to your own to get new functional connector of DreamFactory Platform.
+
+To connect it to DF just add the following to the require section of 
+[main composer](https://github.com/dreamfactorysoftware/dreamfactory/blob/ce72cc6739979be286f51617050bc9ec9c657f39/composer.json#L30):
+```
+"require":     {
+    "dreamfactory/df-skeleton":   "~0.1.0"    // instead of skeleton write name of your package
+}
+``` 
 
-## Documentation
+Then run `composer require dreamfactory/df-skeleton update--no-dev --ignore-platform-reqs `
+
+### Documentation
 
 Documentation for the platform can be found on the [DreamFactory wiki](http://wiki.dreamfactory.com).
 
-## Installation
+# Create a new DreamFactory connector
+
+First of all, your package composer need to require df-core 
+and, in case of creating system service, df-system. 
+Just add the following to the composer.json file of your package:
+```json
+"require":     {
+    "dreamfactory/df-core":   "~0.15.1",
+    "dreamfactory/df-system": "~0.2.0"
+}
+```
+
+# This package has: 
+
+### Folders
+
+- `./database` 
+
+Things that concern database. For example [migrations](https://laravel.com/docs/5.6/migrations), if your package needs a table in system database.
+
+- `./routes`
+
+If you need a non DF API [route](https://laravel.com/docs/5.6/routing), you can describe it in routes.php file.
+
+- `./src/Components`
+
+Any support classes, like wrappers or classes that implement the 3rd party packages functionality.
+
+- `./src/Enum`
+
+In some cases you want to define a constant list of values. This is a food place to place them.
+
+- `./src/Events`
+
+Your package can define [events](https://laravel.com/docs/5.6/events) to subscribe to them later.
+
+- `./src/Handlers/Events`
+
+Define event handlers or any other here.
+
+- `./src/Http` 
+Things that handle routes from `./routes` folder.
+
+  - `./src/Http/Middleware`
+
+  Requests middleware should go here.
+
+  - `./src/Http/Conrollers`
+
+  Contollers of `./routes` should go here.
+
+- `./src/Models`
+
+Define Eloquent [Models](https://laravel.com/docs/5.8/eloquent) here.
+
+- `./src/Resources`
+
+API [Resources](https://laravel.com/docs/5.6/eloquent-resources). It may extend `DreamFactory\Core\Resources\BaseRestResource` from df-core.
+
+- `./src/Services`
+
+Define your new Service here. It may also extend `DreamFactory\Core\Services\BaseRestService` or any other base services from df-core.
+
+- `./src/Testing`
+
+PHPUnit tests go here.
 
-For more information, see the [full platform repository](https://github.com/dreamfactorysoftware/dreamfactory).
+### Classes:
 
+1. Service that extends `DreamFactory\Core\Services\BaseRestService` (__see [src/Services](https://github.com/dreamfactorysoftware/df-skeleton/blob/add-examples/src/Services/ExampleService.php)__)
+2. Database table that describes your connector config (__see [database/migrations](https://github.com/dreamfactorysoftware/df-skeleton/blob/add-examples/database/migrations/2019_08_12_125323_create_example_table.php)__)
+3. Model that connects to the table and extends `DreamFactory\Core\Models\BaseServiceConfigModel` (__see [src/Models](https://github.com/dreamfactorysoftware/df-skeleton/blob/master/src/Models/ExampleModel.php)__).
+There is an opportunity to create connector not using database (__see [DreamFactory\Core\Models\BaseServiceConfigNoDbModel](https://github.com/dreamfactorysoftware/df-core/blob/master/src/Models/BaseServiceConfigNoDbModel.php)__)
 
-Edit your project’s composer.json to require the following package.
+4. Resource that extends `DreamFactory\Core\Resources\BaseRestResource` (__see [src/Resources](https://github.com/dreamfactorysoftware/df-skeleton/blob/add-examples/src/Resources/ExampleResource.php)__)
 
-	“require”:{
-		"dreamfactory/df-skeleton": "~0.1.0"
-	}
 
-## Feedback and Contributions
+For parent classes you can override methods to satisfy your needs. 
 
-* Feedback is welcome in the form of pull requests and/or issues.
-* Contributions should generally follow the strategy outlined in ["Contributing to a project"](https://help.github.com/articles/fork-a-repo#contributing-to-a-project)
-* All pull requests must be in a ["git flow"](https://github.com/nvie/gitflow) feature branch and formatted as [PSR-2 compliant](http://www.php-fig.org/psr/psr-2/) to be considered.
+In your resource and service you can override handleGET, handlePOST methods from [df-core](https://github.com/dreamfactorysoftware/df-core/blob/06e01cd46ed106684041fb1fdf8ef35695a1b2cf/src/Components/RestHandler.php#L589) to determine responses (only if 
+[$autoDispatch = true;](https://github.com/dreamfactorysoftware/df-core/blob/06e01cd46ed106684041fb1fdf8ef35695a1b2cf/src/Components/RestHandler.php#L88)).
 
-### License
+[ServiceProvider](https://github.com/dreamfactorysoftware/df-skeleton/blob/master/src/ServiceProvider.php) connects the package to the application.
 
-The DreamFactory core is open-sourced software available for use under the [Apache Version 2.0 license](http://www.apache.org/licenses/LICENSE-2.0).
+*Remember you are not limited and you can implement anything Laravel provide.*

composer.json

@@ -22,6 +22,8 @@
     "issues": "https://github.com/dreamfactorysoftware/df-skeleton/issues",
     "wiki":   "https://wiki.dreamfactory.com"
   },
+  "minimum-stability": "dev",
+  "prefer-stable": true,
   "require":     {
     "dreamfactory/df-core":   "~0.15.1",
     "dreamfactory/df-system": "~0.2.0"

database/migrations/2019_08_12_125323_create_example_table.php

@@ -33,11 +33,6 @@ function (Blueprint $t) use ($onDelete) {
                     $t->string('label')->nullable();
                     $t->text('description')->nullable();
                     $t->timestamp('created_date')->nullable();
-                    $t->timestamp('last_modified_date')->useCurrent();
-                    $t->integer('created_by_id')->unsigned()->nullable();
-                    $t->foreign('created_by_id')->references('id')->on('user')->onDelete($onDelete);
-                    $t->integer('last_modified_by_id')->unsigned()->nullable();
-                    $t->foreign('last_modified_by_id')->references('id')->on('user')->onDelete($onDelete);
                 }
             );
         }

database/migrations/2019_08_12_130653_db_is_example.php

@@ -3,7 +3,7 @@
 use Illuminate\Database\Schema\Blueprint;
 use Illuminate\Database\Migrations\Migration;
 
-class DbVirtualField extends Migration
+class DbIsExample extends Migration
 {
     /**
      * Run the migrations.

routes/routes.php

@@ -0,0 +1,27 @@
+<?php
+
+/*
+|--------------------------------------------------------------------------
+| Skeleton Service Routes
+|--------------------------------------------------------------------------
+|
+| These routes created in example purposes.
+|
+*/
+
+Route::prefix(config('df.example_prefix'))
+    ->middleware('df.cors')
+    ->group(function () {
+        $resourcePattern = '[0-9a-zA-Z-_@&\#\!=,:;\/\^\$\.\|\{\}\[\]\(\)\*\+\? ]+';
+        $servicePattern = '[_0-9a-zA-Z-.]+';
+        $controller = 'DreamFactory\Core\Skeleton\Http\Controllers\ExampleController';
+
+        Route::get('example-route', $controller . '@index');
+
+        /*
+        Route::get('{example}/{path}', $controller . '@streamFile')->where(
+            ['example' => $servicePattern, 'path' => $resourcePattern]
+        );
+        */
+    }
+    );

src/Components/ExampleComponent.php

@@ -0,0 +1,14 @@
+<?php
+
+namespace DreamFactory\Core\Skeleton\Components;
+
+
+class ExampleComponent
+{
+
+    public static function getExample()
+    {
+        return "example";
+    }
+
+}

src/Enums/VerbsMask.php

@@ -0,0 +1,25 @@
+<?php
+namespace DreamFactory\Core\Compliance\Enums;
+
+use DreamFactory\Core\Enums\VerbsMask as CoreVerbsMask;
+
+/**
+ * Various REST verbs as bitmask-able values
+ *
+ * This one is overriding the VerbMask from df-core
+ */
+class VerbsMask extends CoreVerbsMask
+{
+    /**
+     * @return int
+     */
+    public static function getFullAccessMask()
+    {
+        return
+            self::GET_MASK |
+            self::POST_MASK |
+            self::PUT_MASK |
+            self::PATCH_MASK |
+            self::DELETE_MASK;
+    }
+}

src/Events/BaseExampleEvent.php

@@ -0,0 +1,23 @@
+<?php
+namespace DreamFactory\Core\Events;
+
+use DreamFactory\Core\Skeleton\Models\ExampleConfig;
+use Illuminate\Queue\SerializesModels;
+
+abstract class BaseExampleEvent
+{
+    use SerializesModels;
+
+    public $example;
+
+    /**
+     * Create a new event instance.
+     *
+     * @param ExampleConfig $example
+     */
+    public function __construct(ExampleConfig $example)
+    {
+        $this->example = $example;
+    }
+}
+

src/Events/ExampleCreatingEvent.php

@@ -0,0 +1,6 @@
+<?php
+namespace DreamFactory\Core\Events;
+
+class ExampleCreatingEvent extends BaseExampleEvent
+{
+}

src/Handlers/Events/EventHandler.php

@@ -0,0 +1,71 @@
+<?php
+namespace DreamFactory\Core\Compliance\Handlers\Events;
+
+use DreamFactory\Core\Events\ExampleCreatingEvent;
+use DreamFactory\Core\Events\UserCreatingEvent;
+use DreamFactory\Core\Events\BaseExampleEvent;
+use DreamFactory\Core\Events\BaseUserEvent;
+use DreamFactory\Core\Skeleton\Components\ExampleComponent;
+use Illuminate\Contracts\Events\Dispatcher;
+
+class EventHandler
+{
+    /**
+     * Register the listeners for the subscriber.
+     *
+     * @param  Dispatcher $events
+     */
+    public function subscribe($events)
+    {
+        // subscribe to Core event
+        $events->listen(
+            [
+                UserCreatingEvent::class,
+            ],
+            static::class . '@handleUserCreatingEvent'
+        );
+
+        // subscribe to our own event
+        $events->listen(
+            [
+                ExampleCreatingEvent::class,
+            ],
+            static::class . '@handleExampleCreatingEvent'
+        );
+    }
+
+    /**
+     * Handle User creating events.
+     *
+     * @param BaseUserEvent $event
+     *
+     * @return void
+     */
+    public function handleUserCreatingEvent($event)
+    {
+        $isExample = ExampleComponent::getExample() === 'example';
+
+        if ($isExample) {
+            $user = $event->user;
+            // do something internal
+        }
+    }
+
+    /**
+     * Handle Example creating events.
+     * Your own event
+     *
+     * @param BaseExampleEvent $event
+     *
+     * @return void
+     */
+    public function handleExampleCreatingEvent($event)
+    {
+        $isExample = ExampleComponent::getExample() === 'example';
+
+        if ($isExample) {
+            $example = $event->example;
+            // do something internal
+        }
+    }
+}

src/Http/Controllers/ExampleController.php

@@ -0,0 +1,14 @@
+<?php
+
+namespace DreamFactory\Core\Skeleton\Http\Controllers;
+
+use DreamFactory\Core\Http\Controllers\Controller;
+
+class ExampleController extends Controller
+{
+    public function index()
+    {
+        return ['Who am I?' => "I'm Batman"];
+    }
+
+}

src/Http/Middleware/ExampleMiddleware.php

@@ -0,0 +1,35 @@
+<?php
+
+
+namespace DreamFactory\Core\Skeleton\Http\Middleware;
+
+use Closure;
+
+class ExampleMiddleware
+{
+    private $method;
+    private $request;
+
+    /**
+     * @param         $request
+     * @param Closure $next
+     *
+     * @return mixed
+     * @throws \Exception
+     */
+    function handle($request, Closure $next)
+    {
+        $this->request = $request;
+        $this->method = $request->getMethod();
+        $response = $next($request);
+
+        if ($response->isSuccessful())
+        {
+            $content = $response->getOriginalContent();
+            $content['middleware_on'] = true;
+            $response->setContent($content);
+        }
+
+        return $response;
+    }
+}