Skip to content
locations / 1

Installation & Setup

Last updated:

On this page

Installing

Locations and its Javaabu dependencies aren't on Packagist yet. Add their repositories, then require the package:

"repositories": [
    { "type": "vcs", "url": "https://github.com/Javaabu/locations" },
    { "type": "vcs", "url": "https://github.com/Javaabu/stencil" },
    { "type": "vcs", "url": "https://github.com/Javaabu/permissions" },
    { "type": "vcs", "url": "https://github.com/Javaabu/forms" },
    { "type": "vcs", "url": "https://github.com/Javaabu/manifest" }
]
composer require javaabu/locations:^1.0@dev

The service provider is discovered automatically.

Migrating and seeding

php artisan migrate
php artisan locations:seed
php artisan permissions:sync

locations:seed adds every country, the atolls and the named islands (see Seeding the data). permissions:sync creates the package's permissions (view_islands, edit_islands, …) for your guards.

Routes

Nothing is registered until you call the macros, so you choose the prefix, middleware and guard. Put them in your admin route group:

// routes/web.php
use Illuminate\Support\Facades\Route;

Route::middleware('web')->group(function () {
    // The read-only endpoint the cascading selects load their options from
    Route::locationOptions();

    // The admin pages: /admin/locations/countries, /admin/locations/islands, …
    Route::prefix('admin')->name('admin.')->group(function () {
        Route::locations(['guard' => 'web_admin']);
    });
});
Macro Registers
Route::locationOptions() GET location-options/{countries,states,cities,atolls,islands}, named location-options.*. Public by default: wrap it in your own middleware to change that
Route::locations() The index, create, show, edit and delete pages of every location type, named locations.{resource}.* and behind auth:{guard}

Every cascading select (Blade, React or stencil) needs Route::locationOptions(). Both macros take options, see Admin pages and The options endpoint.

Blade

The Blade pages extend layouts.app and fill its content section. Point them at your layout:

// config/locations.php (php artisan vendor:publish --tag=locations-config)
'layout' => 'layouts.admin',
'layout_section' => 'content',

The layout needs manifest's tags (@manifestStyles and @manifestScripts), or its automatic injection, as every javaabu/forms page does. That loads javaabu/forms' select script, which handles the cascades.

Inertia React

Render the admin pages with Inertia instead of Blade:

LOCATIONS_VIEWS=inertia

Then set up manifest's Vite plugin and page resolver, if your app doesn't already have them:

// vite.config.js
import manifest from "./vendor/javaabu/manifest/dist/vite.js"

export default defineConfig({
  plugins: [laravel({ input: ["resources/js/app.tsx"] }), manifest(), react()],
})
// resources/js/app.tsx
import { resolvePage } from "@javaabu/manifest/inertia"

createInertiaApp({
  resolve: (name) => resolvePage(name, import.meta.glob("./Pages/**/*.tsx")),
  // …
})

The pages are locations::Resources/Index, locations::Resources/Form and locations::Resources/Show. They render the forms with @javaabu/stencil's StencilForm. Your own pages import the selects from @javaabu/locations:

import { IslandSelect } from "@javaabu/locations"

php artisan manifest:check lists the npm packages your app still needs. Locations' (@javaabu/forms, React) are only listed once your package.json has @inertiajs/react, so a Blade app isn't asked for them; --scope=pages checks them anyway.

Publishing

Tag What
locations-config config/locations.php
locations-migrations The migration (then call Locations::ignoreMigrations(), see Models)
locations-translations lang/vendor/locations
locations-views resources/views/vendor/locations

React pages and components are overridden through manifest, see Overriding controllers and views.

Documentation
All packages

javaabu/locations

Source on GitHub