Utilities

What’s a utility?

A utility is really just a route or two with a view, injected into the Utilities area of the control panel, and wrapped up with a permission. You could make the same thing by wiring up the individual parts, but creating a utility is a shortcut.

To get an idea for what a utility is, take a look at the utilities Statamic ships with:

• A page for viewing cache information and a button to clear it.
• A page to list PHP settings from phpinfo().
• A page letting you clear search indexes.
• A page to view email configuration and send a test.

Creating a utility

Registering a utility will give you a route, nav item, and a permission for free.

In a service provider’s boot method, you can register a utility with the Utility facade.

Start with Utility::register() with the handle of the utility, then chain as many methods as you want.

Make sure to surround any utility registrations in a Utility::extend closure.

use Statamic\Facades\Utility;
 
public function boot()
{
    Utility::extend(function () {
        Utility::register('data_wangjangler')->view('wangjangler.utility');
    });
}

@extends('statamic::layout')
@section('title', __('Data Wangjangler'))
 
@section('content')
    <div class="flex items-center justify-between">
        <h1>{{ __('Data Wangjangler') }}</h1>
    </div>
 
    <button @click="commenceWangjangling">
        Wangjangle that data.
    </button>
@stop

Customizing the navigation and card

You can customize the nav item, description, icon, and other details on the index listing by chaining the corresponding methods.

For icons you can pass an SVG as a string. Be sure to use fill="currentColor" to allow the UI to fit into the control panel.

use Statamic\Facades\Utility;
 
public function boot()
{
    Utility::extend(function () {
        Utility::register('data_wangjangler')
            ->title('Data Wangjangler')
            ->navTitle('Wangjangler')
            ->icon('<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 512 512"><path d="M246.0422 221.6193c-14.2079 -17.2455 -21.3609 -38.4104 -21.3609 -59.5753 0 -78.4865 94.0663 -156.875 188.1325 -156.875 51.9324 0 94.0662 42.1338 94.0662 94.0662 0 94.0662 -78.3885 188.1325 -156.973 188.1325 -21.1649 0 -42.3298 -7.153 -59.5753 -21.3609L58.6936 497.6449c-12.2482 12.2482 -32.1392 12.2482 -44.3875 0s-12.2482 -32.1393 0 -44.3875l231.7361 -231.6381Z" fill="currentColor" stroke-width="1"></path></svg>')
            ->description('Wanjangles your data at the click of a button.')
            ->docsUrl('https://yoursite.com/docs/wangjangler');
    });
}

Customizing the controller and view

At a minimum you need to tell it which view to load.

Utility::register('data_wangjangler')->view('wangjangler');

If you’d like to pass data to it, you could use a closure similar to if it were in a routes file:

Utility::register('data_wangjangler')->view('wangjangler', function ($request) {
    return ['foo' => 'bar'];
});

Or you can point to a controller action:

Utility::register('data_wangjangler')
    ->action(WangjanglerController::class) // call the __invoke method
    ->action([WangjanglerController::class, 'index']); // call the index method

Routing

A route will be created for you automatically, using the slugified version of the handle you initially provided. eg. /cp/utilities/data-wangjangler

If your utility needs to do something (like how you click a button in the cache manager utility to actually clear the cache) you may register additional routes.

Utility::register('data_wangjangler')->routes(function ($router) {
    $router->post('/', [WangjanglerController::class, 'make'])->name('make');
});

{{ cp_route('utilities.data-wangjangler.make') }}
// outputs: /cp/utilities/data-wangjangler/make

Permissions

A single permission will be registered automatically using the handle. eg. access data_wangjangler utility

Users without this permission will not see the utility in the navigation or utility listing.