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('french_fries')->view('fries.utility');
    });
}

@extends('statamic::layout')
@section('title', __('French Fries'))
 
@section('content')
    <div class="flex items-center justify-between">
        <h1>{{ __('French Fries') }}</h1>
    </div>
 
    <div class="mt-3 card">
        French Fries
    </div>
@stop

Customizing the navigation and card

You can customize the nav item and the card within the listing by chaining additional methods.

$utility
    ->title('French Fries')
    ->navTitle('Fries')
    ->description('Makes french fries at the click of a button.')
    ->docsUrl('https://yoursite.com/docs/french-fries');

Customizing the controller and view

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

$utility->view('fries');

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

$utility->view('fries', function ($request) {
    return ['foo' => 'bar'];
});

Or you can point to a controller action:

$utility
    ->action(FriesController::class) // call the __invoke method
    ->action([FriesController::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/french-fries

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->routes(function ($router) {
    $router->post('/', [FriesController::class, 'make'])->name('make');
});

{{ cp_route('utilities.french-fries.make') }}
// outputs: /cp/utilities/french-fries/make

Permissions

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

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