README

Set a watcher to watch for specific keys in your Laravel form requests. If those keys are present, perform any arbitrary functions(s).

Installation
Usage
Complete Example

Installation

This package can be used in Laravel 5.4 or higher.

You can install the package via composer:

composer require hackeresq/laravel-watcher

Watcher is a trait that can be added to your Laravel FormRequests (or you can use the included base FormRequest). To start using the setWatcher() method, you must 'use' the Watcher trait by either adding it to your FormRequest or using the base WatcherRequest in your controllers.

An example of a custom FormRequest implementation:

<?php

namespace App\Http\Requests;

use HackerESQ\Watcher\Watcher;
use Illuminate\Foundation\Http\FormRequest;

class YourCustomFormRequest extends FormRequest
{
    use Watcher;
    
    // ...
}

Alternatively, if you are not using custom FormRequests, you can use the provided WatcherRequest, which already has the trait added. This is how your controller methods should look:

    /**
     * Update the specified resource in storage.
     *
     * @param  HackerESQ\Watcher\Requests\WatcherRequest $request
     * @return \Illuminate\Http\Response
     */
    public function update(WatcherRequest $request)
    {   
        // ...
    }

Success! laravel-watcher is now installed!

Usage

Once you've added the trait to your custom FormRequest or you've added the WatcherRequest to your controller method, you'll have a new setWatcher() method available on your requests. This allows you to set up your watcher.

Basic Usage

The basic usage of the setWatcher() method is to pass an array, with the "trigger" as the key, like so:

        $request->setWatcher([
            'invoice_start_num_changed' => [
                'action' => fn($context) => DB::statement("ALTER TABLE `invoices` AUTO_INCREMENT = ".(int)$context->request->invoice_start_num),
            ],
        ]);

You will notice that the key is the "watched" trigger. If the 'invoice_start_num_changed' is present (and not falsey) the defined 'action,' which is an anonymous function, will be called.

Remove Key

You can optionally choose to remove the trigger from the request (e.g. if you are passing the request elsewhere and want to sanitize it) by passing a 'removeKey' attribute, like this:

        $request->setWatcher([
            'invoice_start_num_changed' => [
                'action' => fn($context) => DB::statement("ALTER TABLE `invoices` AUTO_INCREMENT = ".(int)$context->request->invoice_start_num),
                'removeKey' => true,
            ],
        ]);

Passing Context

You will notice you can pass $context to the anonymous function. This $context object contains the trigger name (in the $context->trigger object) and the original form request (in the $context->request object).

Trigger even when request is empty

Finally, if you want the action to fire even when the trigger is null or empty, you can use the allowEmpty option. Just set allowEmpty to true when you configure your triggers:

        $request->setWatcher([
            'empty_field_contains_nothing' => [
                'action' => fn($context) => Log::info($context),
                'allowEmpty' => true,
            ],
        ]);

Call multiple functions

If you do not want to create and call an intermediary function, and would prefer to call multiple functions from within the watcher, you can opt to use a standard anonymous function (rather than the short arrow function), like this:

        $request->setWatcher([
            'invoice_start_num_changed' => [
                'action' => function($context) { 
                      Log::info($context); 
                      DB::statement("ALTER TABLE `invoices` AUTO_INCREMENT = ".(int)$context->request->invoice_start_num);
                      // do other stuff
                 },
                'removeKey' => true,
            ],
        ]);

Complete Example

SettingsController.php

<?php

namespace App\Http\Controllers;

use Illuminate\Support\Facades\DB;
use Illuminate\Support\Facades\Log;
use HackerESQ\Watcher\Requests\WatcherRequest;

class SettingsController extends Controller
{
    // ... other controller methods
    
    /**
     * Update the specified resource in storage.
     *
     * @param  \HackerESQ\Watcher\Requests\WatcherRequest $request
     * @return \Illuminate\Http\Response
     */
    public function update(WatcherRequest $request)
    {   
        $request->setWatcher([
            'invoice_start_num_changed' => [
                'action' => fn($context) => DB::statement("ALTER TABLE `invoices` AUTO_INCREMENT = ".(int)$context->request->invoice_start_num),
                'removeKey' => true,
            ],
            'should_log_action' => [
                'action' => fn($context) => Log::info($context),
            ],
        ]);

        Settings::set($request->all());

        return $request;
    }
}

Finally

Testing

You can run tests with the composer test command.

Contributing

Feel free to create a fork and submit a pull request if you would like to contribute.

Bug reports

Raise an issue on GitHub if you notice something broken.

hackeresq / laravel-watcher

Maintainers

Details