Download the PHP package codeartlv/joona without Composer

Joona

Joona is a Laravel admin panel package with user management, roles and permissions, activity logging, and a Bootstrap 5–based UI layer. Unlike opinionated admin builders, it does not force predefined CRUD screens—you build your own Blade views and routes while reusing layouts, form helpers, and JavaScript components.

Requirements

• PHP 8.2+
• Laravel 11.x (recommended for new projects; the package can be added to existing apps)
• Node.js and npm (for compiling your Vite assets)
• Composer

The package ships database migrations. If your application already has tables with the same names (admin_users, roles, etc.), resolve naming conflicts before migrating.

Installation

1. Install the package

Laravel auto-discovers Codeart\Joona\Providers\JoonaProvider, which registers migrations and Artisan commands.

2. Publish assets and application provider

This command:

• Runs npm install inside the package asset directory (vendor/codeartlv/joona/resources/assets)
• Publishes flag images to public/vendor/joona
• Publishes config/joona.php
• Publishes app/Providers/JoonaServiceProvider.php (extends JoonaPanelProvider)
• Registers JoonaServiceProvider in bootstrap/providers.php (Laravel 11+)

On Laravel 10 and below, add App\Providers\JoonaServiceProvider::class to config/app.php manually if it was not added automatically.

3. Run migrations and seed

Default login (change immediately in production):

The seeded password satisfies the default policy in config/joona.php (min:8,max:20,mixed,number,special). Stricter rules apply when users change passwords through the UI.

Frontend setup (Vite)

Joona does not ship pre-built CSS/JS for your app. You compile your own entry files and point the panel at them via addViteResources().

SCSS entry

Create e.g. resources/scss/admin.scss:

JavaScript entry

Create e.g. resources/js/admin.js:

main.js exports the runtime singleton as window.Joona. Call Joona.ready() once to bind data-bind handlers, load translations, and initialize built-in components.

Vite configuration

Run npm install in your Laravel project, then build:

Register Vite entries in the panel

Edit app/Providers/JoonaServiceProvider.php:

Layouts load these files with @vite($vite_resources) in resources/views/global.blade.php.

Custom <head> / body snippets

Publish or create:

• resources/views/vendor/joona/head.blade.php
• resources/views/vendor/joona/body.blade.php

They are included from the main layout automatically.

Panel configuration

Configure the panel in JoonaServiceProvider::configure() using the Panel instance:

Navigation pages

Top-level IDs appear in the sidebar; dotted IDs nest under the first segment.

Locales

Flag SVGs are served from public/vendor/joona/images/flags/{map}.svg.

Authentication and guards

Joona merges an admin guard and joona user provider into config/auth.php:

• Guard: admin (session driver)
• Provider model: Codeart\Joona\Models\User\AdminUser
• Facade helper: joona.auth resolves Auth::guard('admin')

Use Auth::guard('admin') or the joona.auth binding in your code. Do not confuse this with Laravel’s default web guard.

Routes and middleware

Package routes are registered under Panel::getBasePath() with the web and admin.web middleware groups. Authenticated package routes also use admin.auth.

Adding your own admin routes

Register routes in JoonaServiceProvider::configure():

Or pass a route file path:

• secure — wrapped in admin.auth (must be logged in).
• free — only web + admin.web (e.g. login pages you add yourself).

Equivalent manual grouping:

Named routes are available in JavaScript via Ziggy (@routes in the layout). Use the global route() helper the same way as in PHP.

Views and layouts

Page layout (<x-content>)

The content component renders a page title, optional sidebar, header controls, main area, and footer:

• With a sidebar slot, the sidebar layout is used.
• Without it, the simple full-width layout is used.

Extending package layouts directly

Other layouts: joona::global, joona::simple, joona::sidebar.

Blade directives

Blade components

Components are registered without a namespace prefix—use <x-form>, <x-button>, etc.

Forms

The form renders data-bind="components.form" and submits via AJAX. Show feedback in an element with data-role="form.response" (created automatically if missing).

Field-level errors: use data-field="field_name" on a container, or rely on name matching inputs. Use * as the field key for global errors.

FormResponse (controller)

JSON shape: status (success|error), fields, message, actions, data.

Supported actions: redirect, reload, reset, close_popup, close_popup_reload.

Buttons

role maps to Bootstrap btn-{role}. Additional attributes are merged onto the <button> (default type="submit").

Alerts

Roles follow Bootstrap alert variants (info, success, danger, etc.).

Dialog (modal content)

Use inside a modal loaded by the JS Modal class or as inline modal markup:

Paginator

Hidden when only one page exists.

Input, textarea, select, checkbox

<x-select> options are Codeart\Joona\View\Components\Select\Option instances or Group objects for optgroups.

Datepicker, color picker, range

Pass extra data-* attributes for JS options (see component templates).

Password validator

Autocomplete

data-route is required (converted to route in JS). Optional: data-proxy, data-input.

Multiselect

Tags (Tagify)

Uploader

Preload files using Codeart\Joona\View\Components\Uploader\File\Image or Document (extend UploadedFile). Return UploadResponse from upload/delete endpoints.

Optional: data-croproute, data-sortable, data-captions, crop presets via [data-role="crop-presets"] JSON.

Gallery

Items should expose id, url, thumbnail for the template.

Editor (Editor.js)

Text editor (Pell)

Data table

Enables SortableJS when sortable is set (e.g. handle for drag handle selector).

Tree editor

Rows implement TreeNode (id, parentId, title, etc.).

Chart

$chartConfig is passed to Chart.js as JSON in the template.

Map picker

Other components

JavaScript API

Runtime (Joona)

Translations: trans('joona::common.ok') and choice() after ready() (backed by lang.js).

Modal

While open, window.JoonaModalInstance references the active modal.

Confirm dialog

Closes automatically when a button is pressed.

Custom JS handlers

Handlers group DOM behavior behind data-bind="plugin.action" attributes.

1. Create a handler class

edit-form in HTML maps to the editForm method.

2. Register and bind

3. Return instances for cross-component access

Return a plain object or a Promise from handler methods to store retrievable instances.

Built-in components handler

These data-bind values are handled automatically:

The admin handler covers panel UI (theme switch, sidebar, notifications, profile modal, etc.).

Permissions

When useRolesAndPermissions(true):

• Routes can be tied to permissions via RoutePermission inside PermissionGroup objects.
• Menu items hide automatically when Gate::denies() the page route.
• Middleware CheckPermissions runs on admin.auth routes.

Register custom permissions in configure():

Configuration (config/joona.php)

Artisan commands

Package structure (reference)

Notes

• The package adds an admin guard and joona provider—plan naming if you add more guards.
• Static images (logos, flags) live under public/vendor/joona after publish.
• For HTMX projects, the runtime re-initializes bindings on htmx:afterSwap / htmx:oobAfterSwap when HTMX is loaded in your app (not bundled with Joona).
• Override package views by placing files in resources/views/vendor/joona/.