Custom actions

In addition to the Flatpack standard actions, you can also create your own custom actions or extend existing ones.

Generate an action class

To generate a custom action, you may use the flatpack:action Artisan command:

php artisan flatpack:action custom-action

This command generates a file under the App\Actions\Flatpack namespace:

<?php

namespace App\Actions\Flatpack;

use Flatpack\Actions\FlatpackAction;
use Flatpack\Contracts\FlatpackAction as FlatpackActionContract;

class CustomAction extends FlatpackAction implements FlatpackActionContract
{
    /**
     * Action authorization.
     *
     * @return bool
     */
    public function authorize()
    {
        return true;
    }

    /**
     * Handle action.
     *
     * @return void
     */
    public function handle()
    {
        // Do something...
    }
}

The action class extends Flatpack\Actions\FlatpackAction and must implement the Flatpack\Actions\Action interface.

Registering the action

In order to use the action, you must register it in the flatpack.php configuration file:

<?php

return [

    /*
    |--------------------------------------------------------------------------
    | Actions
    |--------------------------------------------------------------------------
    |
    | Flatpack form or list actions. You can add your own actions here.
    |
    */
    'actions' => [
        'custom-action' => App\Actions\CustomAction::class,

        // ...
    ],

Now the action is ready to be used in the form or list composition.

custom-action:
  type: button
  label: Click me
  action: custom-action # The action name

Handling the action

When an action is triggered, the action class will be initialised and the handle method will be called.

Inside the handle method, you may use the following properties:

Property name	Description	Notes
entity	The entity name (plural)	e.g. "users"
model	The eloquent model class name	e.g. "App\Models\User"
entry	The current eloquent active record	Available on forms only
fields	The form field current values	Available on forms only
files	The temporary files attached to the form	Available on forms only
selected	Array of ids of the selected records	Available on lists only
user	The currently logged in user

Utility methods

The action class instance exposes the following methods you can use:

Method	Description
entityName	Returns the entity name. The `$plural` attribute can be set to `true` to get the plural form.
isBulk	Returns `true` if bulk action is performed (Lists only)

Example

In the example below, we will override the foo attribute of the active record $this->entry and save the changes to the database using Eloquent model's save method.

The method getMessage, if defined, will be called to retrieve the action's success message.

<?php

namespace App\Actions\Flatpack;

use Flatpack\Actions\FlatpackAction;
use Flatpack\Contracts\FlatpackAction as FlatpackActionContract;

class CustomAction extends FlatpackAction implements FlatpackActionContract
{
    /**
     * Model instance.
     *
     * @var \Illuminate\Database\Eloquent\Model
     */
    public $entry;

    /**
     * Get success message.
     *
     * @return string
     */
    public function getMessage()
    {
        return __(':entity has been updated.', [
            'entity' => $this->entityName(),
        ]);
    }

    /**
     * Handle action.
     *
     * @return void
     */
    public function handle()
    {
        $this->entry->foo = 'bar';
        $this->entry->save();
    }
}

Extending actions

You can extend existing actions by generating a new action that extends the original action.

In this example, we will extend the "save" action.

Generate a new custom action, using the flatpack:action Artisan command:

php artisan flatpack:action custom-save

The generated file will be placed under the App\Actions\Flatpack namespace.

The action class will extend the Flatpack\Actions\Save class, overriding the authorize method logic to check if the current user has the required permissions to perform the action.

<?php

namespace App\Actions\Flatpack;

use Flatpack\Actions\Save;
use Flatpack\Contracts\FlatpackAction;

class CustomSave extends Save implements FlatpackAction
{
    /**
     * Action authorization.
     *
     * @return bool
     */
    public function authorize()
    {
        return $this->isOwner() || $this->hasPermissions();
    }

    /**
     * Determine if the user is the owner of the entry.
     *
     * @return bool
     */
    private function isOwner()
    {
        return $this->entry->user_id === $this->user->id;
    }

    /**
     * Determine if the user has the permission to create or update the entry.
     *
     * @return bool
     */
    private function hasPermissions()
    {
        return in_array(true, [
            $this->user->can('create', $this->model),
            $this->user->can('update', $this->model)
        ]);
    }
}

We now have to register the action in the config/flatpack.php configuration file. Since the Save action is already registered, we can simply replace it with the new action:

<?php

return [

    'actions' => [
        'save' => App\Actions\CustomSave::class,

        // ...
    ],

Finally, the extended action is ready to be used:

save:
  type: button
  label: Click me
  action: save # The action name

# Custom actions

# Generate an action class

# Registering the action

# Handling the action

# Utility methods

# Example