5/27/24, 2:21 PM 1.

1.6

https://voyager-docs.devdojo.com/~gitbook/pdf 1/96
5/27/24, 2:21 PM 1.6

Introduction
Welcome to the Voyager documentation for version 1.6. This documentation will teach
you how to install, configure, and use Voyager so that way you can create some kick ass
stuff!

Hm Hm (cough)… I mean… Arrgg! Ye young scallywag! What say we learn how to steer
this ship!

Voyager Screenshot

Before installing Voyager you may want to take a quick moment to learn what it is and
what it isn't, we'll do that in the next section.

https://voyager-docs.devdojo.com/~gitbook/pdf 2/96
5/27/24, 2:21 PM 1.6

Getting started

https://voyager-docs.devdojo.com/~gitbook/pdf 3/96
5/27/24, 2:21 PM 1.6

What is Voyager
Before installing Voyager it is very important to take a quick moment to learn what it is &
what it isn't.

What it is
An admin interface for your Laravel app

An easy way to add/edit/delete data for your app

A menu builder (build menus in Voyager for your app)

A media manager for your files

CRUD/BREAD generator (learn more about BREAD here)

Voyager is simply an admin for your Laravel app. Whatever you want your app to do on
the front-end is completely up to you. You are in control of your application and you can
use Voyager to make your life easier by adding data, editing users, creating menus, and
many other administrative tasks.

What it isn't
A content management system (CMS)

A blogging platform

Wordpress (Bleh! 😜 )

Voyager is not a CMS or a blogging platform. But it can be used to create a CMS or a
blogging platform, but out of the box it is neither of those. As stated in the previous
section you have full control on what your application will do and how it will function.

With Laravel & Voyager you can create any kind of application your heart desires. Laravel
& Voyager are simply tools to make it easier to build.

https://voyager-docs.devdojo.com/~gitbook/pdf 4/96
5/27/24, 2:21 PM 1.6

Prerequisites
Before installing Voyager make sure you have installed one of the following versions of
Laravel:

Laravel 8

Laravel 9

Additionally Voyager requires you to use PHP 7.3 or newer. Laravel requires you to use
PHP 8 or newer when using Laravel 9.

https://voyager-docs.devdojo.com/~gitbook/pdf 5/96
5/27/24, 2:21 PM 1.6

Installation
Voyager is super easy to install. After creating your new Laravel application you can
include the Voyager package with the following command:

composer require tcg/voyager

Next make sure to create a new database and add your database credentials to your .env
file, you will also want to add your application URL in the APP_URL variable:

APP_URL=http://localhost
DB_HOST=localhost
DB_DATABASE=homestead
DB_USERNAME=homestead
DB_PASSWORD=secret

Finally, we can install Voyager. You can choose to install Voyager with dummy data or
without the dummy data. The dummy data will include 1 admin account (if no users
already exist), 1 demo page, 4 demo posts, 2 categories and 7 settings.

To install Voyager without dummy data simply run

php artisan voyager:install

If you prefer installing it with the dummy data run the following command:

php artisan voyager:install --with-dummy

Specified key was too long error

If you see this error message you have an outdated version of MySQL, use the following
solution: https://laravel-news.com/laravel-5-4-key-too-long-error

And we're all good to go!

https://voyager-docs.devdojo.com/~gitbook/pdf 6/96
5/27/24, 2:21 PM 1.6

Start up a local development server with php artisan serve And, visit the URL
http://localhost:8000/admin in your browser.

If you installed with the dummy data, a user has been created for you with the following
login credentials:

email: [email protected]
password: password

Quick note
A dummy user is only created if there are no current users in your database.

If you did not go with the dummy user, you may wish to assign admin privileges to an
existing user. This can easily be done by running this command:

php artisan voyager:admin [email protected]

If you wish to create a new admin user you can pass the --create flag, like so:

php artisan voyager:admin [email protected] --create

And you will be prompted for the users name and password.

Advanced
This section is meant for users who are installing Voyager on an already existing Laravel
installation or for users who want to perform a manual install. If this is not the case, you
should go back to the installation documentation or skip this section.

The first thing you should do is publish the assets that come with Voyager. You can do
that by running the following commands:

https://voyager-docs.devdojo.com/~gitbook/pdf 7/96
5/27/24, 2:21 PM 1.6

php artisan vendor:publish --provider="TCG\Voyager\VoyagerServiceProvider

php artisan vendor:publish --provider="Intervention\Image\ImageServicePro

Next, call php artisan migrate to migrate all Voyager table.

If you want to change migrations, for example to use a different table for users, don't
migrate. Instead copy Voyagers migrations to database/migrations , make your changes,
turn off the config option database.autoload_migrations and then migrate.

Now, open your User-Model (usually app/User.php ) and make the class extend
\TCG\Voyager\Models\User instead of Authenticatable .

<?php

class User extends \TCG\Voyager\Models\User

{
// ...
}

The next step is to add Voyagers routes to your routes/web.php file:

<?php

Route::group(['prefix' => 'admin'], function () {

Voyager::routes();
});

Now run
php artisan db:seed --class=VoyagerDatabaseSeeder
to seed some necessary data to your database, and
php artisan storage:link
to create the storage symlink to your public folder.

After that, run composer dump-autoload to finish your installation!

https://voyager-docs.devdojo.com/~gitbook/pdf 8/96
5/27/24, 2:21 PM 1.6

Upgrading

Upgrading 1.5 to 1.6

Update your Composer.json

To update to the latest version inside of your composer.json file make sure to update the
version of Voyager inside the require declaration of your composer.json to:

tcg/voyager": "1.6.*

And then run composer update

Check your TinyMCE configuration

TinyMCE was updated to version 6 and with that, a lot of configurations have changed.
If there are any errors in the console and you changed the TinyMCE configuration, make
sure you are using the latest options and values from their docs.

Troubleshooting

Be sure to ask us on our slack channel if you are experiencing any issues and we will try
and assist. Thanks.

https://voyager-docs.devdojo.com/~gitbook/pdf 9/96
5/27/24, 2:21 PM 1.6

Configurations
With the installation of Voyager you will find a new configuration file located at
config/voyager.php .
In this file you can find various options to change the configuration of your Voyager
installation.

If you cache your configuration files please make sure to run php artisan config:clear
after you changed something.

Below we will take a deep dive into the configuration file and give a detailed description of
each configuration set.

Users
<?php

'user' => [
'add_default_role_on_register' => true,
'default_role' => 'user',
'admin_permission' => 'browse_admin',
'namespace' => App\User::class,
'redirect' => '/admin'
],

add_default_role_on_register: Specify whether you would like to add the default role to
any new user that is created.
default_role: You can also specify what the default_role is of the user.
admin_permission: The permission needed to view the admin dashboard.
namespace: The namespace of your apps User Class.
redirect: Redirect path after the user logged in.

Controller

https://voyager-docs.devdojo.com/~gitbook/pdf 10/96
5/27/24, 2:21 PM 1.6

<?php

'controllers' => [
'namespace' => 'TCG\\Voyager\\Http\\Controllers',
],

You can specify the default controller namespace of Voyager. If you ever wish to
override any of the core functionality of Voyager you can do so by duplicating the Voyager
controllers and specifying the location of your custom controllers.

Overwrite a single controller

If you only want to overwrite a single controller, you might consider adding the following
piece of code to your AppServiceProvider class in the register method.
$this->app->bind(VoyagerBreadController::class, MyBreadController::class);

Model
<?php

'models' => [
//'namespace' => 'App\\',
],

You can specify the namespace or location of your models. This is used when creating
the Models from the database section of Voyager. If not defined the default application
namespace will be used.

Assets
<?php

'assets_path' => '/vendor/tcg/voyager/assets',

https://voyager-docs.devdojo.com/~gitbook/pdf 11/96
5/27/24, 2:21 PM 1.6

You may wish to specify a different asset path. If your site lives in a subfolder you may
need to include that directory to the beginning of the path. This may also be used in case
you wish to duplicate the published assets and customize your own.

When upgrading to new version of voyager the assets located in the

/vendor/tcg/voyager/assets directory may need to be overwritten, so if you wish to
customize any styles you will want to duplicate that directory and specify the new location of
your asset_path.

Storage
<?php

'storage' => [
'disk' => 'public',
],

By default Voyager is going to use the public local storage. You can additionally use
any driver inside of your config/filesystems.php . This means you can use S3, Google
Cloud Storage, or any other file storage system you would like.

Database
<?php

'database' => [
'tables' => [
'hidden' => ['migrations', 'data_rows', 'data_types', 'menu_items
],
'autoload_migrations' => true,
],

You may wish to hide some database tables in the Voyager database section. In the
database config you can choose which tables would like to hide.

https://voyager-docs.devdojo.com/~gitbook/pdf 12/96
5/27/24, 2:21 PM 1.6

autoload_migrations allows you to exclude Voyagers migration-files from loading

when running php artisan migrate .

Multilingual
<?php

'multilingual' => [
'enabled' => false,
'default' => 'en',
'locales' => [
'en',
//'pt',
],
],

You can specify whether or not you want to enable mutliple languages. You can then
specify your default language and all the support languages (locales)

Read more about multilanguage here.

Dashboard

https://voyager-docs.devdojo.com/~gitbook/pdf 13/96
5/27/24, 2:21 PM 1.6

<?php

'dashboard' => [
'navbar_items' => [
'Profile' => [
'route' => 'voyager.profile',
'classes' => 'class-full-of-rum',
'icon_class' => 'voyager-person',
],
'Home' => [
'route' => '/',
'icon_class' => 'voyager-home',
'target_blank' => true,
],
'Logout' => [
'route' => 'voyager.logout',
'icon_class' => 'voyager-power',
],
],
'widgets' => [
'TCG\\Voyager\\Widgets\\UserDimmer',
'TCG\\Voyager\\Widgets\\PostDimmer',
'TCG\\Voyager\\Widgets\\PageDimmer',
],
],

In the dashboard config you can add navbar_items, make the data_tables responsive, and
manage your dashboard widgets.

navbar_items Include a new route in the main user navbar dropdown by including a
'route', 'icon_class', and 'target_blank'.

data_tables If you set 'responsive' to true the datatables will be responsive.

widgets Here you can manage the widgets that live on your dashboard. You can take a
look at an example widget class by viewing the current widgets inside of
tcg/voyager/src/Widgets .

Primary color

https://voyager-docs.devdojo.com/~gitbook/pdf 14/96
5/27/24, 2:21 PM 1.6

<?php

'primary_color' => '#22A7F0',

The default primary color for the Voyager admin dashboard is a light blue color. You can
change that primary color by changing the value of this config.

Show developer tips

<?php

'show_dev_tips' => true,

In the Voyager admin there are developer tips or notifications that will show you how to
reference certain values from Voyager. You can choose to hide these notifications by
setting this configuration value to false.

Additional stylesheets
<?php

'additional_css' => [
//'css/custom.css',
],

You can add your own custom stylesheets that will be included in the Voyager admin
dashboard. This means you could technically create a whole new theme for Voyager by
adding your own custom stylesheet.

Read more here.

The path will be passed to Laravels asset function.

https://voyager-docs.devdojo.com/~gitbook/pdf 15/96
5/27/24, 2:21 PM 1.6

Additional Javascript
<?php

'additional_js' => [
//'js/custom.js',
],

The same goes for this configuration. You can add your own javascript that will be
executed in the Voyager admin dashboard. Add as many javascript files as needed.

Read more here.

Google Maps
<?php

'googlemaps' => [
'key' => env('GOOGLE_MAPS_KEY', ''),
'center' => [
'lat' => env('GOOGLE_MAPS_DEFAULT_CENTER_LAT', '32.715738'),
'lng' => env('GOOGLE_MAPS_DEFAULT_CENTER_LNG', '-117.161084'),
],
'zoom' => env('GOOGLE_MAPS_DEFAULT_ZOOM', 11),
],

There is a new data type called coordinates that allow you to add a google map as a
datatype. The user can then drag and drop a pin in the Google Maps to save a longitude
and latitude value in the database.

In this config you can set the default Google Maps Keys and center location. This can
also be added to your .env file.

Allowed Mimetypes

https://voyager-docs.devdojo.com/~gitbook/pdf 16/96
5/27/24, 2:21 PM 1.6

To allow/disallow mimetypes to be uploaded through the media-manager you can define

an array allowed_mimetypes :

<?php

'allowed_mimetypes' => [
'image/jpeg',
'image/png',
'image/gif',
'image/bmp',
'video/mp4',
],

The user can only upload files with the given mimetypes. If you want to allow all types to
be uploaded you can use the following:

<?php

'allowed_mimetypes' => '*',

https://voyager-docs.devdojo.com/~gitbook/pdf 17/96
5/27/24, 2:21 PM 1.6

BREAD

https://voyager-docs.devdojo.com/~gitbook/pdf 18/96
5/27/24, 2:21 PM 1.6

Introduction
When adding or editing the current BREAD for a database table you will first see the
BREAD info which allows you to set the Display Names, slug, icon, Model and Controller
Namespace, Policy Name. You can also choose if you would like to Generate permissions
for that BREAD type.

When you scroll down you will see each of the rows that are associated with that table
where you can select where in your views you want to see each of those fields:

BROWSE (field will show up when you browse the current data)

READ (field will show when you click to view the current data)
EDIT (field will be visible and allow you to edit the data)
ADD (field will be visible when you choose to create a new data type)
DELETE (doesn't pertain to delete so this can be checked or unchecked)

https://voyager-docs.devdojo.com/~gitbook/pdf 19/96
5/27/24, 2:21 PM 1.6

You may also choose to specify what form type you want to use for each field. This can
be a TextBox, TextArea, Checkbox, Image, and many other types of form elements.

Each field also has additional details or options that can be included. These types are
checkbox, dropdown, radio button, and image.

Validation
Inside of the Optional Details section for each row in your BREAD you can also specify
validation rules with some simple JSON. Here is an example of how to add a validation
rule for required and max length of 12

{
"validation": {
"rule": "required|max:12"
}
}

Additionally, you may wish to add some custom error messages which can be
accomplished like so:

https://voyager-docs.devdojo.com/~gitbook/pdf 20/96
5/27/24, 2:21 PM 1.6

{
"validation": {
"rule": "required|max:12",
"messages": {
"required": "This :attribute field is a must.",
"max": "This :attribute field maximum :max."
}
}
}

You can also define multiple rules the following way:

{
"validation": {
"rule": [
"required",
"max:12"
]
}
}

Action specific rules

You can define separate validation rules for edit and add:

{
"validation": {
"rule": "min:3",
"edit": {
"rule": "nullable"
},
"add": {
"rule": "required"
}
}
}

You can find a list of all available validation rules in the Laravel docs.

https://voyager-docs.devdojo.com/~gitbook/pdf 21/96
5/27/24, 2:21 PM 1.6

Tagging
Tagging gives you the possibility to add new items to a Belongs-To-Many relationship
directly when editing or adding a BREAD.

To activate this function, you simply have to enable Tagging in the relationship details

After that you can enter a free-text into the select and hit enter to save a new relationship.

Be aware:

This only stores the display-column so you have to make sure that all other fields are
either nullable or have a default value.

Ordering Bread Items

You can define the default order for browsing BREADs and order your BREAD items with
drag-and-drop.
For this you need to change the settings for your BREAD first:

https://voyager-docs.devdojo.com/~gitbook/pdf 22/96
5/27/24, 2:21 PM 1.6

Order column is the field in your table where the order is stored as an integer.
Order display column is the field which is shown in the drag-drop list.
Order direction the direction in which the field is ordered.

After this you can go to your BREAD-browse page and you will see a button Order.
Clicking this button will bring you to the page where you can re-arrange your items:

Scope browse-results
If you want to filter the browse results for a BREAD you can do so by creating a Scope in
your model. For example if you want to only show posts that were created by the current

https://voyager-docs.devdojo.com/~gitbook/pdf 23/96
5/27/24, 2:21 PM 1.6

user, define a Scope like the following:

<?php
public function scopeCurrentUser($query)
{
return $query->where('author_id', Auth::user()->id);
}

Next, go to the BREAD-settings for posts and look for the Scope input and select
currentUser :

After hitting Submit you will only see your own posts.

https://voyager-docs.devdojo.com/~gitbook/pdf 24/96
5/27/24, 2:21 PM 1.6

Relationships

Adding a relationship
Using the BREAD builder you can easily create Relationships between tables. At the
bottom of the page you will see a new button that says 'Create Relationship'

Notice
If you have not yet created the BREAD for the table yet, it will need to be created first and
then you can come back after creating the BREAD to add the relationship. Otherwise you'll
end up with a notification which looks like the following.

https://voyager-docs.devdojo.com/~gitbook/pdf 25/96
5/27/24, 2:21 PM 1.6

So, after the BREAD has already been created you will then be able to create a new
relationship. After you click on the 'Create a Relationship' button. You will see a new
Modal window that looks like the following:

You will first specify which type of relationship this is going to be, then you will select the
table you are referencing and which Namespace that belongs to that table. You will then
select which row combines those tables.

You can also specify which columns you would like to see in the dropdown or the multi-
select.

Now, you can easily create belongsTo , belongsToMany , hasOne , and hasMany
relationships directly in Voyager.

https://voyager-docs.devdojo.com/~gitbook/pdf 26/96
5/27/24, 2:21 PM 1.6

Advanced options
If you need to set advanced options for belongsToMany relationship you can set, after
saving relationship, these parameters in details field:

{
"foreign_pivot_key": "user_id",
"related_pivot_key": "role_id",
"parent_key": "id"
}

Sorting relationships
You can sort the results of a relationship by setting the sort object in the relationship
options:

{
"sort": {
"field": "my_field",
"direction": "asc"
}
}

Or

{
"sort": {
"field": "my_field",
"direction": "desc"
}
}

To sort by my_field descending.

Scoping relationships

https://voyager-docs.devdojo.com/~gitbook/pdf 27/96
5/27/24, 2:21 PM 1.6

You can easily filter the shown relationship options by defining a local scope in the
foreign model.
For example, if you want to only show active entries, create a scope like:

public function scopeActive($query)

{
return $query->where('active', 1);
}

And add the following to the relationship options:

{
"scope": "active",
}

The value is the name of your scope-method without the word scope .
The value for scopeActive() is active . For scopeSomeUsers() it is someUsers .

In a BelongsTo relationship the foreign key field decides if value can be saved on add or edit
and applies validation rules for everything else, like visibility in browse and edit, the
relationship field is used.

https://voyager-docs.devdojo.com/~gitbook/pdf 28/96
5/27/24, 2:21 PM 1.6

Formfields
Formfields are the hearth of Voyagers BREAD-system.
Each formfield represents a field in your database-table and one input (or output) in
BREAD.
To tweak your formfields you can insert JSON options which are described in the
following pages.

All formfields share a handful options:

Description
All types can include a description in order to help your future self or other users using
your Voyager admin panel to understand exactly what a specific BREAD input field is for,
this can be defined in the Optional Details JSON input field:

{
"description": "A helpful description text here for your future self.
}

Display options
There are also a few options that you can include to change the way your BREAD is
displayed. You can add a display key to your json object and change the width of the
particular field and even specify a custom ID.

{
"display": {
"width": "3",
"id": "custom_id"
}
}

https://voyager-docs.devdojo.com/~gitbook/pdf 29/96
5/27/24, 2:21 PM 1.6

The width is displayed on a 12-grid system. Setting it with a width of 3 will span 25% of
the width.

The id will let you specify a custom id wrapper around your element. example:

<div id="custom_id">
<!-- Your field element -->
</div>

Default value
Most formfields allow you to define a default value when adding an entry:

{
"default" : "Default text"
}

Null Values
You might want to save an input field into the database as a null value instead of an
empty string.

Simply enough, inside the BREAD you can include the following Optional Details for the
field:

{
"null": ""
}

This will turn an empty string into a null value. However you might want to be able to
add both an empty string and a null value to the database for that field. However you
have to choose a replacement for the null value, but it can be anything you wish. For
example, if you want a field to change a string (ex. Nothing ) into a null value you
could include the following Optional Details for that field:

https://voyager-docs.devdojo.com/~gitbook/pdf 30/96
5/27/24, 2:21 PM 1.6

{
"null": "Nothing"
}

Now entering Nothing into the field will end up as a null value in the database.

Generating Slugs
Using the bread builder you may wish to automatically generate slugs of a certain input.
Lets say you have some posts, which have a title and a slug. If you want to automatically
generate the slug from the title attribute, you may include the following Optional Details:

{
"slugify": {
"origin": "title",
"forceUpdate": true
}
}

This will automatically generate the slug from the input of the title field. If a slug does
already exists, it will only be updated if forceUpdate is set enabled, by default this is
disabled.

Custom view
You can specify a custom view to be used for a formfield.
To do so, you have to specify the view attribute for your desired field:

{
"view": "my_view"
}

This will then load my_view from resources/views instead of the formfield.

You get plenty of data passed to your view for you to use:

https://voyager-docs.devdojo.com/~gitbook/pdf 31/96
5/27/24, 2:21 PM 1.6

$view can be browse , read , edit , add or order

$content the content for this field

$dataType the DataType

$dataTypeContent the whole model-instance

$row the DataRow

$options the DataRow details

You can also use a custom field view for a specific action (browse, edit, etc) or for similar
actions (browse and read).
The custom views are:

{
"view_browse": "my_browse_view",
"view_read": "my_read_view",
"view_add": "my_add_view",
"view_edit": "my_edit_view",
"view_order": "my_order_view"
}

The same variables as above will be passed to your custom action view.

Developing a custom formfield?

If you are developing a custom formfield and want to customize any of the views, you can do
so by merging view into $options in your formfields createContent() method.

https://voyager-docs.devdojo.com/~gitbook/pdf 32/96
5/27/24, 2:21 PM 1.6

Checkbox/Multiple Checkbox/Radio

Checkbox
{
"on" : "On Text",
"off" : "Off Text",
"checked" : true
}

In Voyager a Checkbox is converted into a toggle switch, and as you can see above the
on key will contain the value when the toggle switch is on, and the off will contain the
value that is set when the switch is off. If checked is set to true the checkbox will be
toggle on; otherwise by default it will be off.

Multiple Checkbox
{
"checked" : true,
"options": {
"checkbox1": "Checkbox 1 Text",
"checkbox2": "Checkbox 2 Text"
}
}

You can create as many checkboxes as you want.

Radio Button

https://voyager-docs.devdojo.com/~gitbook/pdf 33/96
5/27/24, 2:21 PM 1.6

{
"default" : "radio1",
"options" : {
"radio1": "Radio Button 1 Text",
"radio2": "Radio Button 2 Text"
}
}

The Radio button is exactly the same as the dropdown. You can specify a default if
one has not been set and in the options object you will specify the value of the option
on the left and the text to be displayed on the right.

https://voyager-docs.devdojo.com/~gitbook/pdf 34/96
5/27/24, 2:21 PM 1.6

Coordinates

Optional Details
Set these in the Edit BREAD interface

showLatLngInput / showAutocompleteInput

Set either of these to false to not include that input. Both default to true .

{
"showAutocompleteInput": false,
"showLatLngInput": false
}

onChange

{
"onChange": "myFunction"
}

Defines an onChange callback so that you can perform subsequent actions (such as
using the Autocomplete Place address to populate another field) after the user changes
any of the inputs in this formfield.

onChange callback is debounced at 300ms.

First parameter is eventType ("mapDragged", "latLngChanged", or "placeChanged").

Second parameter is data object containing lat , lng , and place properties.

https://voyager-docs.devdojo.com/~gitbook/pdf 35/96
5/27/24, 2:21 PM 1.6

function myFunction(eventType, data) {

console.log('eventType', eventType);
console.log('data.lat', data.lat);
console.log('data.lng', data.lng);
console.log('data.place', data.place);
}

https://voyager-docs.devdojo.com/~gitbook/pdf 36/96
5/27/24, 2:21 PM 1.6

Date & Time

{
"format" : "%Y-%m-%d"
}

The date & timestamp input field is where you can input a date. In the JSON above you
can specify the format value of the output of the date. It allows you to display a
formatted date in browse and read views, using Carbon's formatLocalized() method

https://voyager-docs.devdojo.com/~gitbook/pdf 37/96
5/27/24, 2:21 PM 1.6

Dropdown
{
"default" : "option1",
"options" : {
"option1": "Option 1 Text",
"option2": "Option 2 Text"
}
}

When specifying that an input type should be a dropdown you will need to specify the
values of that dropdown. In the JSON above you can specify the default value of the
dropdown if it does not have a value. Additionally, in the options object you will specify
the value of the option on the left and the text to be displayed on the right.

https://voyager-docs.devdojo.com/~gitbook/pdf 38/96
5/27/24, 2:21 PM 1.6

Images
{
"resize": {
"width": "1000",
"height": null
},
"quality" : "70%",
"upsize" : true,
"thumbnails": [
{
"name": "medium",
"scale": "50%"
},
{
"name": "small",
"scale": "25%"
},
{
"name": "cropped",
"crop": {
"width": "300",
"height": "250"
}
}
]
}

The image input has many options. By default if you do not specify any options no
problem... Your image will still be uploaded. But, if you want to resize an image, set the
quality of the image, or specify thumbnails for the uploaded image you will need to
specify those details.

resize If you want to specify a size you will need to include that in the resize object. If
you set either height or width to null it will keep the aspect ratio based on the width or
height that is set. So, for the example above the width is set to 1000 pixels and since
the height is set to null it will resize the image width to 1000 pixels and resize the
height based on the current aspect ratio.

quality If you wish to compress the image with a percentage quality you can specify that
percentage in the quality key. Typically between 70 and 100% there is little notice of

https://voyager-docs.devdojo.com/~gitbook/pdf 39/96
5/27/24, 2:21 PM 1.6

image quality, but the image size may be dramatically lower.

upsize This is only valid if you have set your image to be resized. If you specify your
image to resized to 1000 pixels and the image is smaller than 1000 pixels by default it will
not upsize that image to the 1000 pixels; however, if you set upsize to true. It will upsize
all images to your specified resize values.

thumbnails Thumbnails takes an array of objects. Each object is a new thumbnail that is
created. Each object contains 2 values, the name and scale percentage. The name
will be attached to your thumbnail image (as an example say the image you uploaded
was ABC.jpg a thumbnail with the name of medium would now be created at ABC-
medium.jpg). The scale is the percentage amount you want that thumbnail to scale.
This value will be a percentage of the resize width and height if specified.

https://voyager-docs.devdojo.com/~gitbook/pdf 40/96
5/27/24, 2:21 PM 1.6

Media Picker
The media picker formfield allows you to upload/delete/select files directly from the
media-manager.
You can customize the behaviour with the following options:

{
"max": 10,
"min": 0,
"expanded": true,
"show_folders": true,
"show_toolbar": true,
"allow_upload": true,
"allow_move": true,
"allow_delete": true,
"allow_create_folder": true,
"allow_rename": true,
"allow_crop": true,
"allowed": [],
"hide_thumbnails": false,
"quality": 90,
"watermark": {
"source": "...",
"position": "top-left",
"x": 0,
"y": 0
}
}

Name Description Type Default

The start path relative

base_path String /bread-slug/
to the filesystem

Rename uploaded files to

rename String Original name
a given string/expression

Delete files if the

delete_files BREAD entry is deleted. bool false
Use with caution!

show_as_images Shows stored data as bool false

https://voyager-docs.devdojo.com/~gitbook/pdf 41/96
5/27/24, 2:21 PM 1.6

Name Description Type Default

images when browsing

The minimum amount of

min int 0
files that can be selected

The maximum amount of

max files that can be selected. int 0
0 means infinite

If the media-picker should

expanded bool true
be expanded by default

show_folders Show subfolders bool true

show_toolbar Shows/hides the whole toolbar bool false

allow_upload Allow users to upload new files bool true

allow_move Allow users to move files/folders bool true

allow_delete Allow users to delete files bool true

allow_create_fold
Allow users to create new folders bool true
er

Allow users to rename files.

allow_rename bool true
Use with caution!

allow_crop Allow users to crop images bool true

Hides known thumbnails

hide_thumbnails and shows them as children bool true
of the parent image

Sets the quality of uploaded

quality int 90
images and thumbnails

allowed The allowed types to Object []

be uploaded/selected.

Empty object means all types.

https://voyager-docs.devdojo.com/~gitbook/pdf 42/96
5/27/24, 2:21 PM 1.6

Name Description Type Default

Files with other types

won't be displayed.

Allowed types

If you want your users to only be able to upload specific file-types you can do so by
passing an object with mime-types to the `allowed` prop, for example:

["image", "audio", "video"]

or

["image/jpeg", "image/png", "image/bmp"]

Expressions

The base_path and rename can contain the following placeholders:

{pk} the primary-key of the entry (only for base_path )

{uid} the user-id of the current logged-in user

{date:format} the current date in the format defined in format . For example
{date:d.m.Y}

{random:10} random string with N characters

So a base_path can, for example, look like the following:

{
"base_path": "/my-bread/{pk}/{date:Y}/{date:m}/"
}

Watermark

https://voyager-docs.devdojo.com/~gitbook/pdf 43/96
5/27/24, 2:21 PM 1.6

A watermark can be added to uploaded images. To do so, you need to define a source
property relative to Voyagers storage-disk. There are a few optional arguments you can
use:
position the position where the watermark is placed. Can be:

top-left (default)
top
top-right
left

center
right
bottom-left
bottom
bottom-right

x Relative offset to the position on the x-axis. Defaults to 0

y Relative offset to the position on the y-axis. Defaults to 0

size the size (in percent) of the watermark relative to the image. Defaults to 15

Thumbnails

You can generate thumbnails for each uploaded image.

A thumbnail can be one of three types:

Fit

Fit combines cropping and resizing to find the best way to generate a thumbnail matching
your dimensions.
You have to pass width and can pass height and position .
An example for fit would be:

https://voyager-docs.devdojo.com/~gitbook/pdf 44/96
5/27/24, 2:21 PM 1.6

{
"thumbnails": [
{
"type": "fit",
"name": "fit-500",
"width": 500, // Required
"height": 500, // Optional
"position": "center" // Optional. Refer to http://image.inter
}
]
}

Crop

Crop an image by given dimensions and position. You have to pass width and height
and can pass x and y .
An example for crop would be:

{
"thumbnails": [
{
"type": "crop",
"name": "crop-500-500",
"width": 500, // Required
"height": 500, // Required
"x": 50, // Optional. Left offset
"y": 50, // Optional. Top offset
}
]
}

Resize

Resize the image to the given dimensions. You have to pass width and/or height .
Some examples for resize :

https://voyager-docs.devdojo.com/~gitbook/pdf 45/96
5/27/24, 2:21 PM 1.6

{
"thumbnails": [
// Width will be 500px, height will be calculated based on the as
{
"type": "resize",
"name": "resize-500",
"width": 500,
"upsize": true, // Optional. Set to false to prevent upsizing
},
// Resizes the image to 500x500px
{
"type": "resize",
"name": "resize-500-500",
"width": 500,
"height": 500
},
// Height will be 500px, width will be auto-calculated
{
"type": "resize",
"name": "resize-500",
"width": null,
"height": 500
}
]
}

A watermark can also be inserted into each thumbnail. Just define the watermark-options
on the parent and set watermark to true for each thumbnail you want to insert the
watermark to.

https://voyager-docs.devdojo.com/~gitbook/pdf 46/96
5/27/24, 2:21 PM 1.6

Number
{
"step" : 0.1,
"min" : 0,
"max" : 10,
"default": 1,
}

These are standard attributes for number input field, default value for step is any if not
defined.

https://voyager-docs.devdojo.com/~gitbook/pdf 47/96
5/27/24, 2:21 PM 1.6

TinyMCE
If you want to customize TinyMCE within Voyager, you can do so by adding a additional
JS file to your config.

In this file you have to define a function like

function tinymce_init_callback(editor)
{
//...
}

If you need to manipulate TinyMCE before it was initialized, you can use

function tinymce_setup_callback(editor)
{
//...
}

If you want to customize TinyMCE init configuration Options you can merge your custom
options in BREAD details as follow:

{
"tinymceOptions" : {
"name": "value"
}
}

If you want to use tinyMCE outside it's default template rich_text_box you'll need
initialize it with:

tinymce.init(window.voyagerTinyMCE.getConfig());

For all possible variables, functions and configuration Options please refer to the
TinyMCE documentation.

https://voyager-docs.devdojo.com/~gitbook/pdf 48/96
5/27/24, 2:21 PM 1.6

Core concepts

https://voyager-docs.devdojo.com/~gitbook/pdf 49/96
5/27/24, 2:21 PM 1.6

Routing
After running the voyager installer you will see a few new routes that have been added to
your routes/web.php file which look like the following:

Route::group(['prefix' => 'admin'], function () {

Voyager::routes();
});

This is where the Voyager routes will be rendered. You can change the admin prefix if
you desire, or set any other route configuration you need, such as middleware or
domain .

When creating a new BREAD type and specifying a slug for that BREAD, you can then visit
that route from the following link:

URL/admin/slug-name

As an example, if we have a products table and we specified the slug to be products .

You will now be able to visit the following URL:

URL/admin/products

Notice
You may not see a link to your newly created routes or BREAD inside your admin menu. To
create a new link in your admin menu visit the documentation for the menu section.

https://voyager-docs.devdojo.com/~gitbook/pdf 50/96
5/27/24, 2:21 PM 1.6

Media Manager
Voyager has a full-fledged Media Manager which allows you to upload files, re-name files,
and delete files. You can also add new folders and move files/folders. Basically anything
that you would be able to do in any type of Media Manager you can do so in the Voyager
Media Manager.

You may also drag and drop files onto the 'upload' button to upload multiple files.
The media manager allows you to create thumbnails and add watermarks to uploaded
images through the configuration file.
Please visit the media-picker documentation to learn about the configuration options.

Notice on File Upload Size

If you are getting an error when trying to upload large files, this may be a setting that needs
to be changed in your PHP. Be sure to check max_file_upload and file_upload_size

https://voyager-docs.devdojo.com/~gitbook/pdf 51/96
5/27/24, 2:21 PM 1.6

Menus and Menu Builder

With Voyager you can easily create menus for your application. In fact the Voyager admin
is using the menu builder for the navigation you use on the left hand side.

You can view your current Menus by clicking on the Tools->Menu Builder button. You can
add, edit, or delete any current menu. This means that you can create a new menu for the
header, sidebar, or footer of your site. Create as many menus as you would like.

When you are ready to add menu items to your menu you can click on the builder button
of the corresponding menu:

This will take you to the Menu Builder where you can add, edit, and delete menu items.

https://voyager-docs.devdojo.com/~gitbook/pdf 52/96
5/27/24, 2:21 PM 1.6

After creating and configuring your menu, you can easily implement that menu in your
application. Say that we have a menu called main . Inside of any view file we could now
output the menu by using the following code:

menu('main');

This will output your menu in an unstyled unordered list. If you do use bootstrap to stylize
your web app you can pass a second argument to the menu display method telling it that
you want to stylize the menu with bootstrap styles like so:

menu('main', 'bootstrap');

Taking it one more step further you can even specify your own view and stylize your menu
however you would like. Say for instance that we had a file located at
resources/views/my_menu.blade.php , which contained the following code:

<ul>
@foreach($items as $menu_item)
<li><a href="{{ $menu_item->link() }}">{{ $menu_item->title }}</a
@endforeach
</ul>

https://voyager-docs.devdojo.com/~gitbook/pdf 53/96
5/27/24, 2:21 PM 1.6

Then anywhere you wanted to display your menu you can now call:

menu('main', 'my_menu');

And your custom menu will now be output.

Menu as JSON
If you dont want to render your menu but get an array instead, you can pass _json as
the second parameter. For example:

menu('main', '_json')

This will give you a collection of menu-items.

https://voyager-docs.devdojo.com/~gitbook/pdf 54/96
5/27/24, 2:21 PM 1.6

Database Manager
Voyager has some awesome database tools which allow you to Add/Edit/Delete or view
current database tables. The other cool part of Voyager is that you can add BREAD or
(Browse, Read, Edit, Add, & Delete) functionality to any of your tables.

Inside of your admin panel you can visit Tools->Database and you'll be able to view all
your current tables in your database. You may also click on 'Create a New Table' to create
a new table in your database. All newly created tables will use the charset defined in your
default database connection.

https://voyager-docs.devdojo.com/~gitbook/pdf 55/96
5/27/24, 2:21 PM 1.6

If you click the table name you can view the current schema. Additionally you can click on
the View, Edit, or Delete buttons to perform that action for that table.

You may also choose to Add BREAD (Browse, Read, Edit, Add, & Delete) for any of your
database tables. Once a table already has BREAD you may choose to edit the current
BREAD or Delete the BREAD for that table.

Read on further about the BREAD builder in the next section.

https://voyager-docs.devdojo.com/~gitbook/pdf 56/96
5/27/24, 2:21 PM 1.6

Settings
The Settings section allows you to add any site wide settings you would like. You can add
an image upload setting for your site logo or a text box for the main headline on your
homepage.

In this new version you have the ability to add different groups for different settings. So, if
you created a new setting inside of the site group and it had a key of title you
would then be able to reference that setting any where on your site by doing the following:

<?php
echo setting('site.title');

Or inside of any blade template like:

{{ setting('site.title') }}

https://voyager-docs.devdojo.com/~gitbook/pdf 57/96
5/27/24, 2:21 PM 1.6

So, now you can add all kinds of settings in Voyager and reference them in your
application.

https://voyager-docs.devdojo.com/~gitbook/pdf 58/96
5/27/24, 2:21 PM 1.6

Compass
The Compass section is a quick place for you to go for some link references, font
references, run some commands or view some logs.

In the first tab you will see a few link resources and you will see all the fonts that you can
use inside of Voyager.

In the Command section you can actually run some artisan commands directly from
Voyager.

https://voyager-docs.devdojo.com/~gitbook/pdf 59/96
5/27/24, 2:21 PM 1.6

And Lastly, under the Logs tab you will be able to view all your application logs.

https://voyager-docs.devdojo.com/~gitbook/pdf 60/96
5/27/24, 2:21 PM 1.6

Roles and Permissions

Voyager comes with Roles and Permissions out of the box. Each User has a Role which
has a set of Permissions.

Inside of the dashboard you can choose to Add, Edit, or delete the current Roles.
Additionally when you click to edit a particular role you can specify the BREAD
permissions.

New in version 1.0, we've changed Voyager's authorization system to be more in line with
Laravel! This means that you can check for permissions in the following ways:

// via user object

$canViewPost = $user->can('read', $post);
$canViewPost = Auth::user()->can('read', $post);

// via controller
$canViewPost = $this->authorize('read', $post);

https://voyager-docs.devdojo.com/~gitbook/pdf 61/96
5/27/24, 2:21 PM 1.6

Out of the box there are some permissions you can use by default:

browse_admin : Whether or not the user may browse the Voyager admin panel.

browse_database : Whether or not the user may browse the Voyager database menu
section.
browse_bread : Whether or not the user may browse the Voyager BREAD menu
section.
browse_media : Whether or not the user may browse the Voyager media section.

browse_menu : Whether or not the user may browse the Voyager menu section.

browse_settings : Whether or not the user may browse the Voyager settings section.

read_settings : Whether or not the user can view or see a particular setting.

edit_settings : Whether or not the user can edit a particular setting.

add_settings : Whether or not the user can add a new setting.

delete_settings : Whether or not the user can delete a particular setting.

Additionally you can Generate permissions for every BREAD type you create. This will
create the browse , read , edit , add and delete permission.

As an example, perhaps we are creating a new BREAD type from a products table. If we
choose to Generate permissions for our products table. Our permission keys will be
browse_products , read_products , edit_products , add_products and
delete_products .

Notice
If a menu item is associated with any kind of BREAD, then it will check for the browse
permission, for example for the Posts BREAD menu item, it will check for the
browse_posts permission. If the user does not have the required permission, that menu
item will be hidden.

Creating permissions for custom page

If you create a custom page and you want only allow specific user roles to access it, you
may use permissions.

https://voyager-docs.devdojo.com/~gitbook/pdf 62/96
5/27/24, 2:21 PM 1.6

This only works if your slug comes directly after /admin/ . So for a custom page of the
form /admin/sub/foo the menu item will not be hidden from the menu.

Create permission

First, create a permission in the permissions table (you could use BREAD for example,
model name is TCG\Voyager\Models\Permission ). The column table_name should
be set to null. The column key should be of the form browse_slug where slug has to
be replaced with the actual slug of your custom page. For example, to restrict access to
your custom page with url /admin/create_bill you may create the permission
browse_create_bill .

Set role

Check the permission for each role that you wish to grant access to the site at
admin/roles . In the above example you would find a new checkbox called "Browse
Create Bill". If a user does not have the required permission, the menu item leading to
your custom page will be hidden.

Customize controller

You may create your own gate

Gate::define('browse_create_bill', function ($user) {

return $user->hasPermission(`browse_create_bill`);
});

to use authorize in your controller:

public function index()

{
$this->authorize('browse_create_bill');
//..

If you do so, make sure add the custom guard to your controller:

https://voyager-docs.devdojo.com/~gitbook/pdf 63/96
5/27/24, 2:21 PM 1.6

/**
* Get the guard to be used during authentication.
*
* @return \Illuminate\Contracts\Auth\StatefulGuard
*/
protected function guard()
{
return Auth::guard(app('VoyagerGuard'));
}

Using Permissions in your Blade Template files

You can also check for permissions using blade syntax. Let's say for instance that you
want to check if a user can browse_posts , simple enough we can use the following
syntax:

@can('browse', $post)
I can browse posts
@endcan

Or perhaps you need to run an else condition for a permission. That's simple enough:

@can('browse', $post)
I can browse posts
@else
I cannot browse posts
@endcan

Couldn't be easier, right ;)

https://voyager-docs.devdojo.com/~gitbook/pdf 64/96
5/27/24, 2:21 PM 1.6

Helper methods
Voyager has several helper functions that are ready to use. Here you can find the list of
available function that may speed up your development.

Thumbnails URL
Voyager will generate thumbnails for Image field type when you specify the additional
field options.

After you have your thumbnails generated, you may want to display the thumbnails in
your view or get the thumbnail URL. In order to do that you need to add Resizable traits
to your model.

use TCG\Voyager\Traits\Resizable;

class Post extends Model

{
use Resizable;
}

Display a single image

@foreach($posts as $post)
<img src="{{Voyager::image($post->thumbnail('small'))}}" />
@endforeach

Or you can specify the optional image field name (attribute), default to image

@foreach($posts as $post)
<img src="{{Voyager::image($post->thumbnail('small', 'photo'))}}" />
@endforeach

Display multiple images

https://voyager-docs.devdojo.com/~gitbook/pdf 65/96
5/27/24, 2:21 PM 1.6

@foreach($posts as $post)
$images = json_decode($post->images);
@foreach($images as $image)
<img src="{{ Voyager::image($post->getThumbnail($image, 'small'))
@endforeach
@endforeach

https://voyager-docs.devdojo.com/~gitbook/pdf 66/96
5/27/24, 2:21 PM 1.6

Multilanguage
Voyager supports multiple languages for your models.To get started, you need to
configure some things first.

Setup
First you need to define some locales in your config/voyager.php file and enable
multilanguage:

'multilingual' => [
'enabled' => true,
'default' => 'en',
'locales' => [
'en',
'da',
],
],

After that you need to include the Translatable Trait in your model and define the
translatable attributes:

use TCG\Voyager\Traits\Translatable;
class Post extends Model
{
use Translatable;
protected $translatable = ['title', 'body'];
}

Now you will see a language-selection in your Pages BREAD.

Usage

Eager-load translations

https://voyager-docs.devdojo.com/~gitbook/pdf 67/96
5/27/24, 2:21 PM 1.6

// Loads all translations

$posts = Post::with('translations')->get();

// Loads all translations

$posts = Post::all();
$posts->load('translations');

// Loads all translations

$posts = Post::withTranslations()->get();

// Loads specific locales translations

$posts = Post::withTranslations(['en', 'da'])->get();

// Loads specific locale translations

$posts = Post::withTranslation('da')->get();

// Loads current locale translations

$posts = Post::withTranslation('da')->get();

Get default language value

echo $post->title;

Get translated value

echo $post->getTranslatedAttribute('title', 'locale', 'fallbackLocale');

If you do not define locale, the current application locale will be used. You can pass in
your own locale as a string. If you do not define fallbackLocale, the current application
fallback locale will be used. You can pass your own locale as a string. If you want to turn
the fallback locale off, pass false. If no values are found for the model for a specific
attribute, either for the locale or the fallback, it will set that attribute to null.

Translate the whole model

https://voyager-docs.devdojo.com/~gitbook/pdf 68/96
5/27/24, 2:21 PM 1.6

$post = $post->translate('locale', 'fallbackLocale');

echo $post->title;
echo $post->body;

// You can also run the `translate` method on the Eloquent collection
// to translate all models in the collection.
$posts = $posts->translate('locale', 'fallbackLocale');
echo $posts[0]->title;

If you do not define locale, the current application locale will be used. You can pass in
your own locale as a string. If you do not define fallbackLocale, the current application
fallback locale will be used. You can pass in your own locale as a string. If you want to
turn the fallback locale off, pass false. If no values are found for the model for a specific
attribute, either for the locale or the fallback, it will set that attribute to null.

Check if model is translatable

// with string
if (Voyager::translatable(Post::class)) {
// it's translatable
}

// with object of Model or Collection

if (Voyager::translatable($post)) {
// it's translatable
}

Set attribute translations

$post = $post->translate('da');
$post->title = 'foobar';
$post->save();

This will update or create the translation for title of the post with the locale da. Please
note that if a modified attribute is not translatable, then it will make the changes directly
to the model itself. Meaning that it will overwrite the attribute in the language set as
default.

https://voyager-docs.devdojo.com/~gitbook/pdf 69/96
5/27/24, 2:21 PM 1.6

Query translatable Models

To search for a translated value, you can use the whereTranslation method.
For example, to search for the slug of a post, you'd use

$page = Page::whereTranslation('slug', 'my-translated-slug');

// Is the same as
$page = Page::whereTranslation('slug', '=', 'my-translated-slug');
// Search only locale en, de and the default locale
$page = Page::whereTranslation('slug', '=', 'my-translated-slug', ['en',
// Search only locale en and de
$page = Page::whereTranslation('slug', '=', 'my-translated-slug', ['en',

whereTranslation accepts the following parameter:

field the field you want to search in

operator the operator. Defaults to = . Also can be the value (Same as where)

value the value you want to search for

locales the locales you want to search in as an array. Leave as null if you want to
search all locales
default also search in the default value/locale. Defaults to true.

https://voyager-docs.devdojo.com/~gitbook/pdf 70/96
5/27/24, 2:21 PM 1.6

Customization

https://voyager-docs.devdojo.com/~gitbook/pdf 71/96
5/27/24, 2:21 PM 1.6

Overriding files

Overriding BREAD Views

You can override any of the BREAD views for a single BREAD by creating a new folder in
resources/views/vendor/voyager/slug-name where slug-name is the slug that you
have assigned for that table. There are 4 files that you can override:

browse.blade.php
edit-add.blade.php
read.blade.php
order.blade.php

Alternatively you can override the views for all BREADs by creating any of the above files
under resources/views/vendor/voyager/bread

Overriding submit button:

You can override the submit button without the need to override the whole
edit-add.blade.php by extending the submit-buttons section:

@extends('voyager::bread.edit-add')
@section('submit-buttons')
@parent
<button type="submit" class="btn btn-primary save">Save And Publish</
@endsection

Using custom Controllers

You can override the controller for a single BREAD by creating a controller which extends
Voyagers controller, for example:

https://voyager-docs.devdojo.com/~gitbook/pdf 72/96
5/27/24, 2:21 PM 1.6

<?php

namespace App\Http\Controllers;

class VoyagerCategoriesController extends \TCG\Voyager\Http\Controllers\V

{
//...
}

After that go to the BREAD-settings and fill in the Controller Name with your fully-qualified
class-name:

You can now override all methods from the VoyagerBaseController

Overriding Voyagers Controllers

Only use this method if you know what you are doing
We don't recommend or support overriding all controllers as you won't get any code-changes
made in future updates.

If you want to override any of Voyagers core controllers you first have to change your
config file config/voyager.php :

https://voyager-docs.devdojo.com/~gitbook/pdf 73/96
5/27/24, 2:21 PM 1.6

/*
|------------------------------------------------------------------------
| Controllers config
|------------------------------------------------------------------------
|
| Here you can specify voyager controller settings
|
*/

'controllers' => [
'namespace' => 'App\\Http\\Controllers\\Voyager',
],

Then run php artisan voyager:controllers , Voyager will now use the child
controllers which will be created at App/Http/Controllers/Voyager

Overriding Voyager-Models
You are also able to override Voyagers models if you need to.
To do so, you need to add the following to your AppServiceProviders register method:

Voyager::useModel($name, $object);

Where name is the class-name of the model and object the fully-qualified name of your
custom model. For example:

https://voyager-docs.devdojo.com/~gitbook/pdf 74/96
5/27/24, 2:21 PM 1.6

<?php

namespace App\Providers;

use Illuminate\Support\ServiceProvider;
use Illuminate\Events\Dispatcher;
use TCG\Voyager\Facades\Voyager;

class AppServiceProvider extends ServiceProvider

{
public function boot()
{
Voyager::useModel('DataRow', \App\DataRow::class);
}
// ...
}

The next step is to create your model and make it extend the original model. In case of
DataRow :

<?php

namespace App;

class DataRow extends \TCG\Voyager\Models\DataRow

{
// ...
}

If the model you are overriding has an associated BREAD, go to the BREAD settings for
the model you are overriding and replace the Model Name with your fully-qualified class-
name. For example, if you are overriding the Voyager Menu model with your own
App\Menu model:

https://voyager-docs.devdojo.com/~gitbook/pdf 75/96
5/27/24, 2:21 PM 1.6

https://voyager-docs.devdojo.com/~gitbook/pdf 76/96
5/27/24, 2:21 PM 1.6

Overriding Routes
You can override any Voyager routes by writing the routes you want to overwrite below
Voyager::routes() . For example if you want to override your post LoginController:

Route::group(['prefix' => 'admin'], function () {

Voyager::routes();

// Your overwrites here

Route::post('login', ['uses' => 'MyAuthController@postLogin', 'as' =>
});

https://voyager-docs.devdojo.com/~gitbook/pdf 77/96
5/27/24, 2:21 PM 1.6

Additional CSS and JS

As of the latest version you can now add additional CSS and JS files to the voyager
master blade without having to copy or modify the blade file itself removing potential
manual migration headaches later on. The CSS and JS files are added after any Voyager
assets so you can override styles and functionality comfortably.

This is all handled via the voyager.php config file:

// Here you can specify additional assets you would like to be included i
'additional_css' => [
//'css/custom.css',
],
'additional_js' => [
//'js/custom.js',
],

The path will be passed to Laravels asset function.

https://voyager-docs.devdojo.com/~gitbook/pdf 78/96
5/27/24, 2:21 PM 1.6

Enabling Soft-Delete
This is only to assist with enabling soft-deletion for your models within Voyager. Please
refer to the Laravel documentation for specifics.

Table Configurations in Voyager

When creating a table using the Database Manager you've selected the 'Add Soft Deletes'
button and then when adding the BREAD functionality to that table you've added a Model
Name, you only have to edit your Model file to fully enable Soft-Delete on that table.

Editing the Table's Model

A default model will look like this:

<?php

namespace App;

use Illuminate\Database\Eloquent\Model;

class YourModelName extends Model

{

Just turn it into:

https://voyager-docs.devdojo.com/~gitbook/pdf 79/96
5/27/24, 2:21 PM 1.6

<?php

namespace App;

use Illuminate\Database\Eloquent\Model;
use Illuminate\Database\Eloquent\SoftDeletes;

class Documento extends Model

{
use SoftDeletes;
protected $dates = ['deleted_at'];
}

And from now on, every time you delete a record from that table, it won't actually be
deleted, only the deleted_at column will be written with the current timestamp.

https://voyager-docs.devdojo.com/~gitbook/pdf 80/96
5/27/24, 2:21 PM 1.6

Custom relationship attributes

With Voyager 1.1 you are able to define additional attributes which you can show in a
relationship.

For example a Post has an Author and you want to display the Users full-name. To
do so, we first need to define an Accessor

public function getFullNameAttribute()

{
return "{$this->first_name} {$this->last_name}";
}

After that we need to tell Voyager that there is an accessor we want to use:

public $additional_attributes = ['full_name'];

Thats it! You can now select full_name in your Relationship.

https://voyager-docs.devdojo.com/~gitbook/pdf 81/96
5/27/24, 2:21 PM 1.6

Adding custom Formfields

You can easily add a new Formfield to Voyager. In the example below we will add a
number form field (which is already included by default in Voyager).

First we create a new class in our project (it doesn't matter where it is placed) called
NumberFormField

<?php

namespace App\FormFields;

use TCG\Voyager\FormFields\AbstractHandler;

class NumberFormField extends AbstractHandler

{
protected $codename = 'number';

public function createContent($row, $dataType, $dataTypeContent, $opt

{
return view('formfields.number', [
'row' => $row,
'options' => $options,
'dataType' => $dataType,
'dataTypeContent' => $dataTypeContent
]);
}
}

The codename variable is used in the dropdown you see in the BREAD builder. In the
createContent method we are returning the view that is used to display our form field.

Next, we will create the view specified above.

<input type="number"
class="form-control"
name="{{ $row->field }}"
data-name="{{ $row->display_name }}"
@if($row->required == 1) required @endif
step="any"
placeholder="{{ isset($options->placeholder)? old($row->field, $opt
value="@if(isset($dataTypeContent->{$row->field})){{ old($row->fie

https://voyager-docs.devdojo.com/~gitbook/pdf 82/96
5/27/24, 2:21 PM 1.6

In the view we can add whatever logic we want.

When we are done with our view, we will tell Voyager that we have a new form field. We
will do this in a service provider (in the example below we use the AppServiceProvider .

<?php

namespace App\Providers;

use TCG\Voyager\Facades\Voyager;
use App\FormFields\NumberFormField;
use Illuminate\Support\ServiceProvider;

class AppServiceProvider extends ServiceProvider

{
//..

public function register()

{
Voyager::addFormField(NumberFormField::class);
}
}

https://voyager-docs.devdojo.com/~gitbook/pdf 83/96
5/27/24, 2:21 PM 1.6

Coordinates
With Voyager you are able to store coordinates and select them from a map.
To do so, you first need to make sure that the column in your table is either GEOMETRY or
POINT .

After that you have to include the Spatial-Trait in your Model and define the column:

<?php

namespace App;

use Illuminate\Database\Eloquent\Model;
use TCG\Voyager\Traits\Spatial;

class Category extends Model

{
use Spatial;

protected $spatial = ['your_column'];

}

Now you can go to the tables BREAD-settings and set your field to be Coordinates .

After that you will get a Map where you can select your Coordinates.

Make sure to set the Google Maps API-Key in your configuration.

This is also the place where you can define the default location of your map.

Getting the coordinates

You can get the coordinates from your model by calling

$model->getCoordinates();

https://voyager-docs.devdojo.com/~gitbook/pdf 84/96
5/27/24, 2:21 PM 1.6

This will return an array of coordinates with lat as the latitude and lng as the
longitude.

https://voyager-docs.devdojo.com/~gitbook/pdf 85/96
5/27/24, 2:21 PM 1.6

BREAD accessors
Sometimes you want to format an attribute only for one (or some) of the BREAD-actions.
For example if you have a name field and on the browse-page you want to display
something when the field is empty, you define the following in your model:

<?php

public function getNameBrowseAttribute()

{
return $this->name ?? 'Empty';
}

This will display "Empty" if the actual field is empty, or return the value if not.

Likewise you can do the same for the other BREAD-actions:

<?php

public function getNameReadAttribute()

{
//
}

public function getNameEditAttribute()

{
//
}

public function getNameAddAttribute()

{
//
}

https://voyager-docs.devdojo.com/~gitbook/pdf 86/96
5/27/24, 2:21 PM 1.6

Custom guard

Custom guard
Starting with Voyager 1.2 you can define a (custom) guard which is used throughout
Voyager.
To do so, just bind the name of your auth-guard to VoyagerGuard .
First, make sure you have defined a guard as per the Laravel documentation.
After that open your AuthServiceProvider and add the following to the register
method:

$this->app->singleton('VoyagerGuard', function () {
return 'your-custom-guard-name';
});

Now this guard is used instead of the default guard.

Example - using a different model and table for

Admins
First you have to create a new table. Let's call it admins :

<?php
Schema::create('admins', function (Blueprint $table) {
$table->bigIncrements('id');
$table->bigInteger('role_id')->unsigned()->nullable();
$table->string('name');
$table->string('email')->unique();
$table->string('avatar')->nullable()->default('users/default.png');
$table->string('password')->nullable();
$table->string('remember_token')->nullable();
$table->text('settings')->nullable()->default(null);
$table->timestamps();
$table->foreign('role_id')->references('id')->on('roles');
});

https://voyager-docs.devdojo.com/~gitbook/pdf 87/96
5/27/24, 2:21 PM 1.6

and a model which extends Voyagers user-model:

<?php

namespace App;

class Admin extends \TCG\Voyager\Models\User

{

Next, create a guard named admin in your config/auth.php :

'guards' => [
'admin' => [
'driver' => 'session',
'provider' => 'admins',
],

// ...
],

And a user provider called admins :

'providers' => [
'admins' => [
'driver' => 'eloquent',
'model' => App\Admin::class,
],

// ...
],

Next you have to tell Voyager to use your new guard.

Open you AppServiceProvider.php and add the following to the register method:

public function register()

{
$this->app->singleton('VoyagerGuard', function () {
return 'admin';
});
}

https://voyager-docs.devdojo.com/~gitbook/pdf 88/96
5/27/24, 2:21 PM 1.6

Please note that the user-bread is still responsible to edit users - not admins.
Create a BREAD for the admins table if you want to change Admins.

https://voyager-docs.devdojo.com/~gitbook/pdf 89/96
5/27/24, 2:21 PM 1.6

Action buttons

Action Buttons
Action buttons are displayed when browsing a BREAD next to each row

You can add your own buttons very easily. First we will create an Action-class which
extends Voyagers AbstractAction in app/Actions/MyAction.php

https://voyager-docs.devdojo.com/~gitbook/pdf 90/96
5/27/24, 2:21 PM 1.6

<?php

namespace App\Actions;

use TCG\Voyager\Actions\AbstractAction;

class MyAction extends AbstractAction

{
public function getTitle()
{
return 'My Action';
}

public function getIcon()

{
return 'voyager-eye';
}

public function getPolicy()

{
return 'read';
}

public function getAttributes()

{
return [
'class' => 'btn btn-sm btn-primary pull-right',
];
}

public function getDefaultRoute()

{
return route('my.route');
}
}

Next we need to tell Voyager that we want to use this action. For this open your
app/Providers/AppServiceProvider.php and search for the boot() method

https://voyager-docs.devdojo.com/~gitbook/pdf 91/96
5/27/24, 2:21 PM 1.6

<?php

namespace App\Providers;

use Illuminate\Support\ServiceProvider;
use Illuminate\Events\Dispatcher;
use TCG\Voyager\Facades\Voyager;

class AppServiceProvider extends ServiceProvider

{
public function boot()
{
Voyager::addAction(\App\Actions\MyAction::class);
}
}

After that you will see your new button when browsing any BREAD

Showing/hiding actions

If you only want to show your action for special datatypes you can implement a function
shouldActionDisplayOnDataType() in your action:

<?php

public function shouldActionDisplayOnDataType()

{
return $this->dataType->slug == 'posts';
}

If you want to show your action-button on a per-row-base, simply implement a method

shouldActionDisplayOnRow($row) and add your condition(s)

https://voyager-docs.devdojo.com/~gitbook/pdf 92/96
5/27/24, 2:21 PM 1.6

<?php

public function shouldActionDisplayOnRow($row)

{
return $row->id > 10;
}

Mass Actions
Mass actions are called for multiple instances of a model.
If you want your action to be a mass action, just implement the following method:

<?php

public function massAction($ids, $comingFrom)

{
// Do something with the IDs
return redirect($comingFrom);
}

https://voyager-docs.devdojo.com/~gitbook/pdf 93/96
5/27/24, 2:21 PM 1.6

Troubleshooting

https://voyager-docs.devdojo.com/~gitbook/pdf 94/96
5/27/24, 2:21 PM 1.6

Using HTTPS on yours site

Symptom: When visiting your site with HTTPS, images within Voyager fail to load.

Cause: Images urls are generated by Voyager using

Storage::disk(config('voyager.storage.disk'))->url($file);

If voyager.storage.disk is set to public, and the public disk is the default from Laravel,
then the url property in the disk configuration is set to

'url' => env('APP_URL').'/storage',

which uses the non-HTTPS APP_URL value to build an absolute url to the image.

Solution: If you remove env('APP_URL'). from the public disk configuration, then it will
render a domain-relative url, which will always use the current domain and protocol.

As an aside, if you need a fully-qualified URL, you could wrap the call to
Voyager::image('...') with asset() , so it would be

asset(Voyager::image('...'))

This will return the current protocol, domain, and correct path to that image.

https://voyager-docs.devdojo.com/~gitbook/pdf 95/96
5/27/24, 2:21 PM 1.6

Missing required parameter

Symptom: You get an error page saying

Missing required parameters for [Route...]

Cause: There are two possible causes:

1. You dont have a primary-key for your table

2. You have a primary-key but it's not called id

Solution: As there are two causes, there are also two solutions: 1. Simply create a field
id for the table
2. Tell your model about your primary-key:
protected $primaryKey = 'your_primary_key';

Please consider following Eloquents model conventions

https://voyager-docs.devdojo.com/~gitbook/pdf 96/96