Composer PHP Application

https://github.com/slowlyo/owl-admin
Admin
A PHP application structured with Composer, featuring admin views, database management, and...
Tokens:54,823
Snippets:631
Trust Score:7.8
License:MIT
Update:4 months ago
Show doc for...
Tokens:
Raw
### Publish and Install Owl Admin

Source: https://github.com/slowlyo/owl-admin/blob/master/README.md

Publish the framework's resources and then run the installation command for Owl Admin. Configuration can be adjusted in config/admin.php before installation.

```shell
# First publish framework resources
php artisan admin:publish
# Execute installation (you can modify some configurations in config/admin.php before executing the installation command)
php artisan admin:install
```

--------------------------------

### AdminRole Key Methods

Source: https://github.com/slowlyo/owl-admin/blob/master/_autodocs/05-models-and-database.md

Examples of attaching users and synchronizing permissions for a role.

```php
$role->users()->attach($userId);
$role->permissions()->sync([1, 2, 3]);  // Replace permissions
```

--------------------------------

### AdminMenuController Example

Source: https://github.com/slowlyo/owl-admin/blob/master/_autodocs/04-controllers-and-services.md

Example of an AdminMenuController managing navigation menus and handling custom save order requests.

```php
class AdminMenuController extends AdminController
{
    protected string $serviceName = AdminMenuService::class;
    
    public function saveOrder(Request $request)  // Custom
}
```

--------------------------------

### Report Controller Example

Source: https://github.com/slowlyo/owl-admin/blob/master/_autodocs/07-extension-system.md

Example of a controller for an extension, extending the base AdminController and using a service.

```php
<?php
namespace Vendor\MyExtension\Http\Controllers;

use Slowlyo\OwlAdmin\Controllers\AdminController;
use Vendor\MyExtension\Services\ReportService;

class ReportController extends AdminController
{
    protected string $serviceName = ReportService::class;
    
    public function index()
    {
        return $this->response()->success(
            $this->service->listQuery()->paginate()
        );
    }
}
```

--------------------------------

### Configure Database and Install API Module

Source: https://github.com/slowlyo/owl-admin/blob/master/README.md

Set up your database connection in the .env file and install the API module for Laravel 11+.

```dotenv
# .env
DB_CONNECTION=mysql
DB_HOST=127.0.0.1
DB_PORT=3306
DB_DATABASE=owl_admin
DB_USERNAME=root
DB_PASSWORD=
```

```shell
php artisan install:api
```

--------------------------------

### AdminMenu Example Data

Source: https://github.com/slowlyo/owl-admin/blob/master/_autodocs/05-models-and-database.md

Example data structure for creating a new menu item.

```php
[
    'parent_id' => 0,
    'title' => 'User Management',
    'icon' => 'fa fa-users',
    'url' => '/admin/system/admin_users',
    'order' => 10,
    'visible' => 1,
    'permission' => 'admin_users.view',
]
```

--------------------------------

### AdminUser Key Methods

Source: https://github.com/slowlyo/owl-admin/blob/master/_autodocs/05-models-and-database.md

Examples of creating Sanctum tokens and checking authorization.

```php
// Sanctum token creation (from Authenticatable)
$token = $user->createToken('api')->plainTextToken;

// Authorization check (from Authorizable)
$user->can('permission.sign');
$user->cannot('permission.sign');

// Role/permission assignment
$user->roles()->attach($roleId);
$user->roles()->detach($roleId);
```

--------------------------------

### GET /admin/_settings

Source: https://github.com/slowlyo/owl-admin/blob/master/_autodocs/08-routes-and-endpoints.md

Retrieves all system settings as key-value pairs.

```APIDOC
## GET /admin/_settings

### Description
Gets all settings (key-value pairs).

### Method
GET

### Endpoint
/admin/_settings

### Response
#### Success Response (200)
- **status** (integer) - Indicates the success of the operation (0 for success).
- **data** (object) - An object containing system settings.
  - **timezone** (string) - The current timezone setting.
  - **locale** (string) - The current locale setting.
  - **theme** (string) - The current theme setting.

#### Response Example
```json
{
    "status": 0,
    "data": {
        "timezone": "UTC",
        "locale": "en",
        "theme": "light"
    }
}
```
```

--------------------------------

### Create and Configure a Page Renderer

Source: https://github.com/slowlyo/owl-admin/blob/master/_autodocs/03-renderers-base.md

Example of creating a 'page' renderer with a title, body content, and sidebar configuration.

```php
Page::make()
    ->title('Dashboard')
    ->body([
        // child components
    ])
    ->aside([
        // sidebar content
    ])
```

--------------------------------

### Auth Guard Configuration Example

Source: https://github.com/slowlyo/owl-admin/blob/master/_autodocs/11-configuration.md

Configure the 'admin' authentication guard and its associated user provider in `config/auth.php`.

```php
'guards' => [
    'admin' => [
        'driver' => 'sanctum',
        'provider' => 'admin_users',
    ],
],

'providers' => [
    'admin_users' => [
        'driver' => 'eloquent',
        'model' => Slowlyo\OwlAdmin\Models\AdminUser::class,
    ],
],
```

--------------------------------

### Custom API Template Example

Source: https://github.com/slowlyo/owl-admin/blob/master/_autodocs/06-api-system.md

Example of a custom API template class in PHP, demonstrating custom logic and response handling.

```php
<?php
namespace App\ApiTemplates;

use Slowlyo\OwlAdmin\Support\Apis\AdminBaseApi;
use Slowlyo\OwlAdmin\Models\AdminApi;

class MyCustomApi extends AdminBaseApi
{
    public string $title = 'My Custom API';
    public string $method = 'post';
    
    public function handle()
    {
        $args = $this->getArgs();
        
        // Custom logic here
        $result = $this->processData($args);
        
        return response()->json([
            'status' => 0,
            'data' => $result,
        ]);
    }
    
    private function processData($args)
    {
        // Implementation
    }
}
```

--------------------------------

### GetSettingsApi Response Format

Source: https://github.com/slowlyo/owl-admin/blob/master/_autodocs/06-api-system.md

Example response format for GetSettingsApi, retrieving key-value settings.

```json
{
    "timezone": "UTC",
    "locale": "en",
    "app_name": "My App"
}
```

--------------------------------

### Get All Settings

Source: https://github.com/slowlyo/owl-admin/blob/master/_autodocs/08-routes-and-endpoints.md

Retrieves all system settings, which are stored as key-value pairs. Use this to fetch current configuration values.

```json
{
    "status": 0,
    "data": {
        "timezone": "UTC",
        "locale": "en",
        "theme": "light"
    }
}
```

--------------------------------

### Accessing Registered APIs

Source: https://github.com/slowlyo/owl-admin/blob/master/_autodocs/06-api-system.md

Example of how to retrieve and use registered API instances within the application.

```php
$apis = Admin::context()->get('apis');

foreach ($apis as $apiClass) {
    $instance = new $apiClass();
    echo $instance->getTitle();
}
```

--------------------------------

### DataDetailApi URL Example

Source: https://github.com/slowlyo/owl-admin/blob/master/_autodocs/06-api-system.md

Example URL structure for accessing a specific record using the DataDetailApi. The `{id}` placeholder represents the primary key of the record.

```text
/api/users/{id}
```

--------------------------------

### Create and Configure a Form Renderer

Source: https://github.com/slowlyo/owl-admin/blob/master/_autodocs/03-renderers-base.md

Example of creating a 'form' renderer with a title, API endpoint, body containing input controls, and action buttons.

```php
Form::make()
    ->title('Create User')
    ->api('post:/admin/users')
    ->body([
        TextControl::make()->name('username')->label('Username'),
        TextControl::make()->type('input-password')->name('password')->label('Password'),
        SelectControl::make()->name('role_id')->label('Role')->options([...]),
    ])
    ->actions([
        SubmitAction::make(),
        CancelAction::make(),
    ])
```

--------------------------------

### Throwing Basic AdminException

Source: https://github.com/slowlyo/owl-admin/blob/master/_autodocs/09-exceptions-and-errors.md

A simple example of throwing an `AdminException` with only an error message.

```php
throw new AdminException('Operation failed');
```

--------------------------------

### Listening for ExtensionChanged Event

Source: https://github.com/slowlyo/owl-admin/blob/master/_autodocs/07-extension-system.md

Example of listening for the ExtensionChanged event to perform actions when an extension is enabled.

```php
Event::listen(ExtensionChanged::class, function ($event) {
    if ($event->action === 'enabled') {
        // Extension was enabled
        Log::info("Extension enabled: {$event->name}");
    }
});
```

--------------------------------

### Get and Set Configuration at Runtime

Source: https://github.com/slowlyo/owl-admin/blob/master/_autodocs/11-configuration.md

Demonstrates how to retrieve configuration values using Admin::config() and temporarily set configuration values for the current request using the global config() helper. Also shows how to verify model configurations.

```php
// Get config
$prefix = Admin::config('admin.route.prefix');

// Set config (only for current request)
config(['admin.route.prefix' => 'dashboard']);

// Verify model
$userModel = Admin::adminUserModel();

```

--------------------------------

### AdminSetting Model Usage

Source: https://github.com/slowlyo/owl-admin/blob/master/_autodocs/05-models-and-database.md

Demonstrates how to get and set settings using the AdminSetting model and its facade. Useful for managing application-wide configurations.

```php
// Get setting
$timezone = AdminSetting::query()->find('timezone');
$value = $timezone->value;

// Set setting
AdminSetting::query()->updateOrCreate(
    ['key' => 'timezone'],
    ['value' => 'UTC']
);

// Via facade
Admin::setting()->get('timezone');
Admin::setting()->set('timezone', 'UTC');
```

--------------------------------

### Example Usage of Owl Admin Class

Source: https://github.com/slowlyo/owl-admin/blob/master/_autodocs/02-admin-class.md

Demonstrates common operations like retrieving the current user, building responses, accessing context, checking configurations, and adding menus.

```php
<?php
use Slowlyo\OwlAdmin\Admin;

// Get current user
$user = Admin::user();

// Build response
return Admin::response()->success([
    'id' => $user->id,
    'name' => $user->name,
], 'User data retrieved');

// Access context
Admin::context()->set('request_id', uniqid());

// Check configuration
$apiPrefix = Admin::config('admin.route.prefix'); // '/admin'

// Build menu
Admin::menu()->add([
    'title' => 'Dashboard',
    'icon'  => 'fa fa-home',
    'url'   => '/admin/dashboard',
]);
```

--------------------------------

### Success Response Pattern

Source: https://github.com/slowlyo/owl-admin/blob/master/_autodocs/04-controllers-and-services.md

Example of returning a successful API response with data and a message.

```php
return $this->response()->success(
    data: ['id' => 1, 'name' => 'John'],
    message: 'User created successfully'
);

// Output: {"status": 0, "msg": "User created successfully", "data": {...}}
```

--------------------------------

### Create Laravel Project

Source: https://github.com/slowlyo/owl-admin/blob/master/README.md

Use Composer to create a new Laravel project. This is the first step before installing Owl Admin.

```shell
composer create-project laravel/laravel example-app
```

--------------------------------

### Storage Disk Configuration Example

Source: https://github.com/slowlyo/owl-admin/blob/master/_autodocs/11-configuration.md

Configure local and S3 storage disks in `config/filesystems.php`. The 'disk' option in Owl Admin's upload configuration specifies which disk to use.

```php
'disks' => [
    'public' => [
        'driver' => 'local',
        'root'   => storage_path('app/public'),
        'url'    => env('APP_URL') . '/storage',
        'visibility' => 'public',
    ],
    's3' => [
        'driver' => 's3',
        'key'    => env('AWS_ACCESS_KEY_ID'),
        'secret' => env('AWS_SECRET_ACCESS_KEY'),
        'region' => env('AWS_DEFAULT_REGION'),
        'bucket' => env('AWS_BUCKET'),
    ],
],
```

```php
'upload' => [
    'disk' => 's3',  // Use S3
],
```

--------------------------------

### DataCreateApi Configuration

Source: https://github.com/slowlyo/owl-admin/blob/master/_autodocs/06-api-system.md

Configuration example for the DataCreateApi template, used for creating new records. Requires the model to be specified.

```json
{
    "template": "DataCreateApi",
    "args": {
        "model": "App\\Models\\User"
    }
}
```

--------------------------------

### Permission-Aware UI Elements

Source: https://github.com/slowlyo/owl-admin/blob/master/_autodocs/10-helper-functions.md

This example demonstrates how to control the visibility or state of UI elements based on user permissions using `amis()->Action` and `amis()->Dialog` with the `permission` method.

```php
$deleteAction = amis()->Action()
    ->label('Delete')
    ->permission('reports.delete', '');  // Hidden if no permission

$editDialog = amis()->Dialog()
    ->permission('reports.edit', null)   // Disabled if no permission
    ->title('Edit Report')
    ->body([...]);
```

--------------------------------

### Owl Admin Artisan Commands

Source: https://github.com/slowlyo/owl-admin/blob/master/_autodocs/INDEX.md

Common Artisan commands for managing the Owl Admin installation and features.

```bash
php artisan admin:install         # Install Owl Admin
php artisan admin:publish         # Publish assets and config
php artisan admin:doctor          # Check installation
php artisan admin:menu            # Generate menu
php artisan admin:create-user     # Create admin user
php artisan admin:reset-password  # Reset user password
```

--------------------------------

### Building a CRUD Table with Helper Functions

Source: https://github.com/slowlyo/owl-admin/blob/master/_autodocs/10-helper-functions.md

This example demonstrates building an admin page with a CRUD table, utilizing `table_columns` to dynamically set table columns and `admin_url` for API endpoints.

```php
<?php
use Slowlyo\OwlAdmin\Controllers\AdminController;

class ReportController extends AdminController
{
    public function index()
    {
        $columns = table_columns('reports');
        
        $page = amis()->Page()
            ->title('Reports')
            ->body([
                amis()->CRUDTable()
                    ->api('get:' . admin_url('/reports', true))
                    ->columns(array_map(function($col) {
                        return amis()->TableColumn()
                            ->name($col)
                            ->label(ucfirst($col));
                    }, $columns))
            ]);
        
        return $this->response()->success($page->toArray());
    }
    
    public function show($id)
    {
        $user = admin_user();
        admin_abort_if(!$user->can('reports.view'), 'Permission denied');
        
        // Get report...
    }
}
```

--------------------------------

### OptionsApi Response Format

Source: https://github.com/slowlyo/owl-admin/blob/master/_autodocs/06-api-system.md

Example response format for OptionsApi, providing label-value pairs for select controls.

```json
[
    {"label": "Admin", "value": 1},
    {"label": "User", "value": 2}
]
```

--------------------------------

### DataDetailApi Configuration

Source: https://github.com/slowlyo/owl-admin/blob/master/_autodocs/06-api-system.md

Configuration example for the DataDetailApi template, used for retrieving a single record's details. Requires the model to be specified.

```json
{
    "template": "DataDetailApi",
    "args": {
        "model": "App\\Models\\User"
    }
}
```

--------------------------------

### Access Configuration Values

Source: https://github.com/slowlyo/owl-admin/blob/master/_autodocs/02-admin-class.md

Get configuration values, with support for module-specific fallbacks. Provide a default value if the key is not found.

```php
$prefix = Admin::config('admin.route.prefix');
$custom = Admin::config('admin.custom_key', 'default_value');
```

--------------------------------

### Get Owl Admin Version

Source: https://github.com/slowlyo/owl-admin/blob/master/_autodocs/02-admin-class.md

Retrieve the current version string of the Owl Admin package.

```php
echo Admin::version(); // e.g., "1.0.0"
```

--------------------------------

### Creating Nested Menu Trees

Source: https://github.com/slowlyo/owl-admin/blob/master/_autodocs/10-helper-functions.md

This example shows how to convert a flat array of menu items fetched from the database into a hierarchical tree structure using the `array2tree` function.

```php
$menuItems = DB::table('admin_menus')->get()->toArray();
$menuTree = array2tree($menuItems);

foreach ($menuTree as $item) {
    echo $item['title'];
    if (!empty($item['children'])) {
        foreach ($item['children'] as $child) {
            echo '  - ' . $child['title'];
        }
    }
}
```

--------------------------------

### Full Owl Admin Configuration Example

Source: https://github.com/slowlyo/owl-admin/blob/master/_autodocs/11-configuration.md

This is the complete configuration array for Owl Admin, typically found in config/admin.php. It covers routing, authentication, database connections, file uploads, model mappings, and more.

```php
<?php
return [
    'route' => [
        'prefix'     => 'admin',
        'domain'     => null,
        'middleware' => ['admin'],
    ],
    
    'auth' => [
        'guard'         => 'admin',
        'login_captcha' => false,
    ],
    
    'database' => [
        'connection' => 'admin',
    ],
    
    'upload' => [
        'disk'           => 'public',
        'max_file_size'  => 104857600,
        'chunk_size'     => 10485760,
        'allowed_types'  => ['jpg', 'jpeg', 'png', 'gif', 'pdf'],
    ],
    
    'logo'  => '/favicon.ico',
    'https' => false,
    'directory' => 'admin',
    'bootstrap' => base_path('admin/bootstrap.php'),
    
    'show_development_tools' => true,
    
    'models' => [
        'admin_user'       => Slowlyo\OwlAdmin\Models\AdminUser::class,
        'admin_role'       => Slowlyo\OwlAdmin\Models\AdminRole::class,
        'admin_permission' => Slowlyo\OwlAdmin\Models\AdminPermission::class,
        'admin_menu'       => Slowlyo\OwlAdmin\Models\AdminMenu::class,
    ],
    
    'auto_load_permission' => true,
];

```

--------------------------------

### Define Default Extension Settings

Source: https://github.com/slowlyo/owl-admin/blob/master/_autodocs/07-extension-system.md

Returns an array of default settings for the extension. These values are used when the extension is first installed or if no custom settings are saved.

```php
public function settings()
{
    return [
        'api_key' => '',
        'environment' => 'sandbox',
    ];
}
```

--------------------------------

### Admin::boot()

Source: https://github.com/slowlyo/owl-admin/blob/master/_autodocs/02-admin-class.md

Initializes framework services. This method is called automatically during the bootstrap process and handles various registrations and configurations.

```APIDOC
## Admin::boot()

### Description
Initializes framework services. Called automatically during bootstrap.

### Method
`static boot(): void`

### Handles
- Relationship registration
- API template registration
- Sanctum token model configuration
- Laravel Octane integration

### Example
```php
Admin::boot();
```
```

--------------------------------

### AdminBaseApi blankService Method

Source: https://github.com/slowlyo/owl-admin/blob/master/_autodocs/06-api-system.md

Creates a new, empty instance of the base `AdminService`. This is typically used as a starting point before setting specific model names or other configurations.

```php
$service = $api->blankService();
$service->setModelName(MyModel::class);
```

--------------------------------

### Common Admin Environment Variables

Source: https://github.com/slowlyo/owl-admin/blob/master/_autodocs/11-configuration.md

Example environment variables for configuring Owl Admin, including routing, authentication, database, uploads, and development settings.

```env
# Admin Configuration
ADMIN_ROUTE_PREFIX=admin
ADMIN_ROUTE_DOMAIN=
ADMIN_GUARD=admin
ADMIN_DIR=admin
ADMIN_HTTPS=false
ADMIN_LOGO=/favicon.ico

# Authentication
ADMIN_LOGIN_CAPTCHA=false

# Database (separate from main app)
ADMIN_DB_CONNECTION=admin
ADMIN_DB_HOST=127.0.0.1
ADMIN_DB_PORT=3306
ADMIN_DB_DATABASE=owl_admin
ADMIN_DB_USERNAME=root
ADMIN_DB_PASSWORD=secret

# Upload
ADMIN_UPLOAD_DISK=public
ADMIN_MAX_FILE_SIZE=104857600        # 100MB in bytes
ADMIN_CHUNK_SIZE=10485760            # 10MB in bytes

# Development
ADMIN_SHOW_DEV_TOOLS=true
ADMIN_BOOTSTRAP=admin/bootstrap.php
```

--------------------------------

### DataListApi Configuration

Source: https://github.com/slowlyo/owl-admin/blob/master/_autodocs/06-api-system.md

Configuration example for the DataListApi template, used for paginated data retrieval. Specifies the model, items per page, and optional relations to eager load.

```json
{
    "template": "DataListApi",
    "args": {
        "model": "App\\Models\\User",
        "per_page": 20,
        "with_relations": ["roles"]  // Optional
    }
}
```

--------------------------------

### Get Current Module Name

Source: https://github.com/slowlyo/owl-admin/blob/master/_autodocs/02-admin-class.md

Retrieve the name of the current module. Optionally, get the name in lowercase with underscores.

```php
$module = Admin::currentModule();        // e.g., "user-management"
$lower = Admin::currentModule(true);     // e.g., "user_management"
```

--------------------------------

### Owl Admin Extension Service Provider

Source: https://github.com/slowlyo/owl-admin/blob/master/_autodocs/12-code-examples.md

Example of an extension service provider for Owl Admin. It defines the extension name, boots the extension by loading routes and migrations, and configures settings, permissions, and menu items.

```php
<?php
namespace VendorName\MyExtension;

use Slowlyo\OwlAdmin\Extend\ServiceProvider;
use Slowlyo\OwlAdmin\Renderers\Page;
use Slowlyo\OwlAdmin\Renderers\Form;
use Slowlyo\OwlAdmin\Renderers\TextControl;
use Slowlyo\OwlAdmin\Renderers\SelectControl;

class MyExtensionServiceProvider extends ServiceProvider
{
    protected string $extensionName = 'my-extension';
    
    public function boot()
    {
        parent::boot();
        
        if (file_exists($routes = __DIR__ . '/../routes.php')) {
            $this->loadRoutesFrom($routes);
        }
        
        $this->loadMigrationsFrom(__DIR__ . '/../database/migrations');
    }
    
    public function settingPanel()
    {
        return Page::make()
            ->title('My Extension Settings')
            ->body([
                Form::make()
                    ->api('post:' . admin_url('/my-extension/settings', true))
                    ->body([
                        TextControl::make()
                            ->name('api_key')
                            ->label('API Key')
                            ->type('input-password')
                            ->required(),
                            
                        SelectControl::make()
                            ->name('environment')
                            ->label('Environment')
                            ->options([
                                ['label' => 'Production', 'value' => 'prod'],
                                ['label' => 'Sandbox', 'value' => 'sandbox'],
                            ]),
                            
                        TextControl::make()
                            ->name('webhook_url')
                            ->label('Webhook URL')
                            ->type('input-url'),
                    ])
            ]);
    }
    
    public function permission()
    {
        return [
            [
                'name' => 'View Reports',
                'slug' => 'my-extension.reports.view',
                'description' => 'View extension reports',
            ],
            [
                'name' => 'Edit Settings',
                'slug' => 'my-extension.settings.edit',
                'description' => 'Edit extension settings',
            ],
        ];
    }
    
    public function menu()
    {
        return [
            [
                'title' => 'My Extension',
                'icon'  => 'fa fa-chart-line',
                'url'   => '/admin/my-extension',
                'order' => 30,
            ],
        ];
    }
}

```

--------------------------------

### Creating a Custom UserController

Source: https://github.com/slowlyo/owl-admin/blob/master/_autodocs/04-controllers-and-services.md

Demonstrates how to create a custom controller by extending AdminController and setting a specific service.

```php
<?php
namespace App\Admin\Controllers;

use Slowlyo\OwlAdmin\Controllers\AdminController;
use App\Admin\Services\UserService;

class UserController extends AdminController
{
    // Set the service for this controller
    protected string $serviceName = UserService::class;
    
    // Standard CRUD methods (optional, inherited from AdminController traits)
    public function index()
    {
        // Retrieve and display list of users
    }
    
    public function create()
    {
        // Show create form
    }
    
    public function store(\Illuminate\Http\Request $request)
    {
        // Save new user
        $result = $this->service->store($request->all());
        return $this->autoResponse($result, 'User');
    }
}
```

--------------------------------

### Get Single Admin User Response

Source: https://github.com/slowlyo/owl-admin/blob/master/_autodocs/08-routes-and-endpoints.md

The JSON response for retrieving a single admin user's details via GET /admin/system/admin_users/{id}. Includes user ID, username, name, email, and assigned roles.

```json
{
    "status": 0,
    "data": {
        "id": 1,
        "username": "admin",
        "name": "Administrator",
        "email": "admin@example.com",
        "roles": [1, 2]
    }
}
```

--------------------------------

### User Settings Response

Source: https://github.com/slowlyo/owl-admin/blob/master/_autodocs/08-routes-and-endpoints.md

The JSON response from GET /admin/user_setting, displaying the current user's profile details and theme preference.

```json
{
    "status": 0,
    "data": {
        "name": "John Admin",
        "email": "john@example.com",
        "theme": "light"
    }
}
```

--------------------------------

### Get Page Schema

Source: https://github.com/slowlyo/owl-admin/blob/master/_autodocs/INDEX.md

Retrieves the schema definition for a page.

```APIDOC
## GET /admin/page_schema

### Description
Retrieves the page schema.

### Method
GET

### Endpoint
/admin/page_schema
```

--------------------------------

### GET /admin/menus

Source: https://github.com/slowlyo/owl-admin/blob/master/_autodocs/08-routes-and-endpoints.md

Retrieves the navigation menu structure for the current user.

```APIDOC
## GET /admin/menus

### Description
Gets navigation menu structure for current user.

### Method
GET

### Endpoint
/admin/menus

### Response
#### Success Response (200)
- **status** (integer) - Indicates the success of the operation (0 for success).
- **data** (array of objects) - The navigation menu structure.
  - **id** (integer) - The menu item ID.
  - **title** (string) - The title of the menu item.
  - **icon** (string) - The icon class for the menu item.
  - **url** (string or null) - The URL for the menu item.
  - **children** (array of objects) - Nested menu items.
  - **visible** (integer) - Indicates if the menu item is visible.

#### Response Example
```json
{
    "status": 0,
    "data": [
        {
            "id": 1,
            "title": "Dashboard",
            "icon": "fa fa-home",
            "url": "/admin/dashboard",
            "children": [],
            "visible": 1
        },
        {
            "id": 2,
            "title": "System",
            "icon": "fa fa-cogs",
            "url": null,
            "children": [
                {"id": 3, "title": "Users", "url": "/admin/system/admin_users", ...}
            ]
        }
    ]
}
```
```

--------------------------------

### Creating a Custom UserService

Source: https://github.com/slowlyo/owl-admin/blob/master/_autodocs/04-controllers-and-services.md

Shows how to create a custom service by extending AdminService, overriding methods like listQuery and store.

```php
<?php
namespace App\Admin\Services;

use Slowlyo\OwlAdmin\Services\AdminService;
use App\Models\User;

class UserService extends AdminService
{
    protected string $modelName = User::class;
    
    // Override listQuery to add filters
    public function listQuery()
    {
        return parent::listQuery()
            ->where('enabled', 1)
            ->orderBy('created_at', 'desc');
    }
    
    // Custom method for business logic
    public function deactivateInactiveUsers($days = 30)
    {
        $date = now()->subDays($days);
        return $this->query()
            ->where('last_login', '<', $date)
            ->update(['enabled' => 0]);
    }
    
    // Override with custom create logic
    public function store(array $data)
    {
        // Validate
        if (!$this->validate($data)) {
            return false;
        }
        
        // Create
        $user = $this->getModel()->create($data);
        $this->setCurrentModel($user);
        
        // Post-processing
        $this->sendWelcomeEmail($user);
        
        return true;
    }
}
```

--------------------------------

### Helper Functions

Source: https://github.com/slowlyo/owl-admin/blob/master/_autodocs/README.md

Reference for global helper functions provided by the Owl Admin framework. This section includes documentation for over 10 functions with practical usage examples.

```APIDOC
## Helper Functions

### Description
This section documents the global helper functions available within the Owl Admin framework. It provides signatures, parameter descriptions, return types, and usage examples for each function.

### Function Documentation Format
Each helper function is documented with:
- **Function Signature**: The name and parameters of the function.
- **Parameters**: Description of each parameter, including its type and whether it is required or optional.
- **Return Type**: The data type of the value returned by the function.
- **Description**: A brief explanation of what the function does.
- **Example**: A code snippet demonstrating how to use the function.

### Example Helper Function (Illustrative)
```markdown
### `format_date(string $date, string $format = 'Y-m-d H:i:s'): string`

#### Description
Formats a given date string into a specified format.

#### Parameters
- **$date** (string) - Required - The date string to format.
- **$format** (string) - Optional - The desired output format. Defaults to 'Y-m-d H:i:s'.

#### Return Type
string - The formatted date string.

#### Example
```php
$formatted = format_date('2023-10-27 10:30:00', 'd/m/Y');
// $formatted will be '27/10/2023'
```
```

--------------------------------

### Auto-created API Records

Source: https://github.com/slowlyo/owl-admin/blob/master/_autodocs/06-api-system.md

Examples of API records automatically generated during code generation. The 'args' can be provided as an array or JSON encoded string.

```php
// Auto-created during code generation
AdminApi::create([
    'template' => 'DataListApi',
    'args' => [
        'model' => 'App\\Models\\User',
        'per_page' => 20,
    ],
]);

AdminApi::create([
    'template' => 'DataCreateApi',
    'args' => ['model' => 'App\\Models\\User'],
]);
```

--------------------------------

### GET /admin/current-user

Source: https://github.com/slowlyo/owl-admin/blob/master/_autodocs/08-routes-and-endpoints.md

Retrieves the profile information of the currently authenticated user.

```APIDOC
## GET /admin/current-user

### Description
Gets currently authenticated user profile.

### Method
GET

### Endpoint
/admin/current-user

### Response
#### Success Response (200)
- **status** (int) - 0 for success
- **data** (object) - User profile details
  - **id** (int) - User ID
  - **username** (string) - Username
  - **name** (string) - User's full name
  - **email** (string) - User's email address
  - **avatar** (string) - URL to user's avatar
  - **roles** (array) - List of user roles

#### Response Example
```json
{
    "status": 0,
    "data": {
        "id": 1,
        "username": "admin",
        "name": "Administrator",
        "email": "admin@example.com",
        "avatar": "...",
        "roles": [...] 
    }
}
```
```

--------------------------------

### GET /admin/logout

Source: https://github.com/slowlyo/owl-admin/blob/master/_autodocs/08-routes-and-endpoints.md

Logs out the current user by revoking their authentication token.

```APIDOC
## GET /admin/logout

### Description
Logs out current user and revokes token.

### Method
GET

### Endpoint
/admin/logout

### Response
#### Success Response (200)
- **status** (int) - 0 for success
- **msg** (string) - Logout successful

#### Response Example
```json
{
    "status": 0,
    "msg": "Logout successful"
}
```
```

--------------------------------

### Check for Admin Tables

Source: https://github.com/slowlyo/owl-admin/blob/master/_autodocs/05-models-and-database.md

Check if the necessary admin tables exist in the database during application bootstrap. The `php artisan admin:install` command creates these tables.

```php
if (Admin::hasTable('admin_users')) {
    // Admin system is installed
}
```

--------------------------------

### Boot All Registered Extensions

Source: https://github.com/slowlyo/owl-admin/blob/master/_autodocs/07-extension-system.md

Boots all registered extensions. This method is called by the service provider during the boot phase after all extensions have been registered.

```php
Admin::extension()->boot();
```

--------------------------------

### Get Menu Structure

Source: https://github.com/slowlyo/owl-admin/blob/master/_autodocs/INDEX.md

Retrieves the hierarchical structure of admin menus.

```APIDOC
## GET /admin/menus

### Description
Retrieves the menu structure.

### Method
GET

### Endpoint
/admin/menus
```

--------------------------------

### Start Chunked File Upload

Source: https://github.com/slowlyo/owl-admin/blob/master/_autodocs/08-routes-and-endpoints.md

Initiates a chunked file upload process by providing file details. This endpoint returns an upload ID required for subsequent chunk uploads.

```json
{
    "filename": "large_file.zip",
    "total": 100,
    "chunk_size": 1024000
}
```

--------------------------------

### Get Admin Frontend HTML View

Source: https://github.com/slowlyo/owl-admin/blob/master/_autodocs/02-admin-class.md

Returns the HTML view for the admin frontend, with injected configuration like the API prefix and logo path. Reads from `public/admin-assets/index.html` or a vendor fallback.

```php
$html = Admin::view('/api');
```

--------------------------------

### GET /admin/user_setting

Source: https://github.com/slowlyo/owl-admin/blob/master/_autodocs/08-routes-and-endpoints.md

Retrieves the current user's settings and profile information.

```APIDOC
## GET /admin/user_setting

### Description
Gets current user's settings/profile.

### Method
GET

### Endpoint
/admin/user_setting

### Response
#### Success Response (200)
- **status** (int) - 0 for success
- **data** (object) - User settings
  - **name** (string) - User's name
  - **email** (string) - User's email
  - **theme** (string) - User's preferred theme

#### Response Example
```json
{
    "status": 0,
    "data": {
        "name": "John Admin",
        "email": "john@example.com",
        "theme": "light"
    }
}
```
```

--------------------------------

### Get Composer Autoloader

Source: https://github.com/slowlyo/owl-admin/blob/master/_autodocs/02-admin-class.md

Retrieve the Composer autoloader instance for class loading.

```php
$loader = Admin::classLoader();
```

--------------------------------

### Message Only Response Pattern

Source: https://github.com/slowlyo/owl-admin/blob/master/_autodocs/04-controllers-and-services.md

Example of returning a success response with only a message and no specific data.

```php
return $this->response()->successMessage('Operation completed');

// Output: {"status": 0, "msg": "Operation completed", "data": []}
```

--------------------------------

### Initialize Framework Services

Source: https://github.com/slowlyo/owl-admin/blob/master/_autodocs/02-admin-class.md

Boots the framework services, handling relationship registration, API template registration, Sanctum token model configuration, and Laravel Octane integration. Called automatically during bootstrap.

```php
Admin::boot();
```

--------------------------------

### AggregateApi Response Format

Source: https://github.com/slowlyo/owl-admin/blob/master/_autodocs/06-api-system.md

Example response format for AggregateApi, containing computed statistics.

```json
{
    "total_revenue": 50000,
    "order_count": 150,
    "avg_order": 333.33
}
```

--------------------------------

### Create Admin Instance

Source: https://github.com/slowlyo/owl-admin/blob/master/_autodocs/02-admin-class.md

Instantiates the Admin class. Typically not needed as static methods can be used directly.

```php
$admin = Admin::make();
```

--------------------------------

### GET /admin/system/admin_users/{id}

Source: https://github.com/slowlyo/owl-admin/blob/master/_autodocs/08-routes-and-endpoints.md

Retrieves the detailed information for a specific admin user by their ID.

```APIDOC
## GET /admin/system/admin_users/{id}

### Description
Get single user detail.

### Method
GET

### Endpoint
/admin/system/admin_users/{id}

### Parameters
#### Path Parameters
- **id** (int) - Required - The ID of the user to retrieve

### Response
#### Success Response (200)
- **status** (int) - 0 for success
- **data** (object) - User details
  - **id** (int) - User ID
  - **username** (string) - Username
  - **name** (string) - User's full name
  - **email** (string) - User's email address
  - **roles** (array) - List of user roles

#### Response Example
```json
{
    "status": 0,
    "data": {
        "id": 1,
        "username": "admin",
        "name": "Administrator",
        "email": "admin@example.com",
        "roles": [1, 2]
    }
}
```
```

--------------------------------

### POST /admin/_settings

Source: https://github.com/slowlyo/owl-admin/blob/master/_autodocs/08-routes-and-endpoints.md

Saves system settings.

```APIDOC
## POST /admin/_settings

### Description
Saves settings.

### Method
POST

### Endpoint
/admin/_settings

### Request Body
- **timezone** (string) - Optional - The timezone to set.
- **locale** (string) - Optional - The locale to set.
- **theme** (string) - Optional - The theme to set.

### Request Example
```json
{
    "timezone": "America/New_York",
    "locale": "en",
    "theme": "dark"
}
```

### Response
#### Success Response (200)
- **status** (integer) - Indicates the success of the operation (0 for success).
- **msg** (string) - A message confirming the action.

#### Response Example
```json
{
    "status": 0,
    "msg": "Settings saved"
}
```
```

--------------------------------

### GET /admin/captcha

Source: https://github.com/slowlyo/owl-admin/blob/master/_autodocs/08-routes-and-endpoints.md

Generates and returns a new captcha image and its corresponding session key.

```APIDOC
## GET /admin/captcha

### Description
Gets new captcha image for login form.

### Method
GET

### Endpoint
/admin/captcha

### Response
#### Success Response (200)
- **captcha_img** (string) - Base64 encoded captcha image
- **captcha_key** (string) - Unique session key for the captcha

#### Response Example
```json
{
    "captcha_img": "data:image/png;base64,...".
    "captcha_key": "unique_session_key"
}
```
```

--------------------------------

### Error Response Pattern

Source: https://github.com/slowlyo/owl-admin/blob/master/_autodocs/04-controllers-and-services.md

Example of returning an API error response with a message and empty data.

```php
return $this->response()->fail(
    message: 'User not found',
    data: []
);

// Output: {"status": 1, "msg": "User not found", "data": []}
```

--------------------------------

### Create Extension Directory Structure

Source: https://github.com/slowlyo/owl-admin/blob/master/_autodocs/07-extension-system.md

Use this method to programmatically create the necessary directory structure and initial files for a new extension.

```php
Extension::make()->createDir('vendor/my-extension', 'Vendor\MyExtension');
```

--------------------------------

### DataToggleApi Request Body

Source: https://github.com/slowlyo/owl-admin/blob/master/_autodocs/06-api-system.md

Example request body for toggling a boolean field using DataToggleApi.

```json
{
    "id": 1,
    "value": true
}
```

--------------------------------

### Create Extension Structure via Artisan Command

Source: https://github.com/slowlyo/owl-admin/blob/master/_autodocs/07-extension-system.md

Execute this Artisan command to generate the boilerplate file structure for a new extension.

```bash
php artisan admin:extension:create vendor/my-extension Vendor\MyExtension
```

--------------------------------

### DataUpdateApi Request Body

Source: https://github.com/slowlyo/owl-admin/blob/master/_autodocs/06-api-system.md

Example request body for updating a user record using DataUpdateApi.

```json
{
    "id": 1,
    "name": "Jane Doe",
    "email": "jane@example.com"
}
```

--------------------------------

### POST /admin/upload_chunk_start

Source: https://github.com/slowlyo/owl-admin/blob/master/_autodocs/08-routes-and-endpoints.md

Initiates a chunked file upload process.

```APIDOC
## POST /admin/upload_chunk_start

### Description
Start chunked file upload.

### Method
POST

### Endpoint
/admin/upload_chunk_start

### Request Body
- **filename** (string) - Required - The name of the file being uploaded.
- **total** (integer) - Required - The total number of chunks the file will be divided into.
- **chunk_size** (integer) - Required - The size of each chunk in bytes.

### Request Example
```json
{
    "filename": "large_file.zip",
    "total": 100,
    "chunk_size": 1024000
}
```

### Response
#### Success Response (200)
- **status** (integer) - Indicates the success of the operation (0 for success).
- **data** (object) - Contains information to continue the upload.
  - **upload_id** (string) - A unique identifier for this upload session.

#### Response Example
```json
{
    "status": 0,
    "data": {
        "upload_id": "unique_upload_id"
    }
}
```
```

--------------------------------

### GET /admin/login

Source: https://github.com/slowlyo/owl-admin/blob/master/_autodocs/08-routes-and-endpoints.md

Displays the login page, which includes fields for username, password, and an optional captcha.

```APIDOC
## GET /admin/login

### Description
Displays login page.

### Method
GET

### Endpoint
/admin/login

### Response
Returns HTML form with username, password, and optional captcha fields
```

--------------------------------

### Create Form and Table Renderers

Source: https://github.com/slowlyo/owl-admin/blob/master/_autodocs/03-renderers-base.md

Use the static `make()` method to create new instances of Form and Table renderers.

```php
$form = Form::make();
$table = Table::make();
```

--------------------------------

### Get Module Manager Instance

Source: https://github.com/slowlyo/owl-admin/blob/master/_autodocs/02-admin-class.md

Obtain the module manager instance to access all registered modules.

```php
$module = Admin::module();
$modules = $module->allModules();
```

--------------------------------

### Admin::setting()

Source: https://github.com/slowlyo/owl-admin/blob/master/_autodocs/02-admin-class.md

Retrieves the settings service instance, which provides functionality for key-value storage.

```APIDOC
## Admin::setting()

### Description
Returns the settings service for key-value storage.

### Method
`static setting(): AdminSettingService`

### Returns
`AdminSettingService`

### Service Binding
`app('admin.setting')`

### Example
```php
$setting = Admin::setting();
$value = $setting->get('some_key');
```
```

--------------------------------

### Require Owl Admin Package

Source: https://github.com/slowlyo/owl-admin/blob/master/README.md

Install the Owl Admin package into your Laravel project using Composer.

```shell
composer require slowlyo/owl-admin
```

--------------------------------

### Build a CRUD Admin Page for Users

Source: https://github.com/slowlyo/owl-admin/blob/master/_autodocs/12-code-examples.md

This snippet demonstrates how to create a full CRUD (Create, Read, Update, Delete) interface for managing users in an admin panel. It utilizes the OwlAdmin framework and AMIS renderers for building the user interface and handling API interactions.

```php
<?php
namespace App\Admin\Controllers;

use Slowlyo\OwlAdmin\Controllers\AdminController;
use App\Admin\Services\UserService;
use Slowlyo\OwlAdmin\Renderers\CRUDTable;
use Slowlyo\OwlAdmin\Renderers\Page;
use Slowlyo\OwlAdmin\Renderers\Dialog;
use Slowlyo\OwlAdmin\Renderers\Form;
use Slowlyo\OwlAdmin\Renderers\TextControl;
use Slowlyo\OwlAdmin\Renderers\SelectControl;
use Slowlyo\OwlAdmin\Renderers\Action;

class UserController extends AdminController
{
    protected string $serviceName = UserService::class;
    
    public function index()
    {
        $page = Page::make()
            ->title('User Management')
            ->body([
                CRUDTable::make()
                    ->api('get:' . admin_url('/system/admin_users', true))
                    ->createApi('post:' . admin_url('/system/admin_users', true))
                    ->updateApi('put:' . admin_url('/system/admin_users/{id}', true))
                    ->deleteApi('delete:' . admin_url('/system/admin_users/{id}', true))
                    ->columns([
                        amis()->TableColumn()->name('id')->label('ID')->width('80px'),
                        amis()->TableColumn()->name('username')->label('Username')->width('150px'),
                        amis()->TableColumn()->name('email')->label('Email'),
                        amis()->TableColumn()->name('name')->label('Name'),
                        amis()->TableColumn()
                            ->name('enabled')
                            ->label('Status')
                            ->type('status')
                            ->width('100px'),
                    ])
                    ->operations([
                        Action::make()
                            ->label('Edit')
                            ->actionType('drawer')
                            ->drawer($this->getEditForm()),
                        Action::make()
                            ->label('Delete')
                            ->actionType('ajax')
                            ->api('delete:' . admin_url('/system/admin_users/{id}', true))
                            ->confirmText('Confirm delete?'),
                    ])
            ]);
        
        return $this->response()->success($page->toArray());
    }
    
    private function getEditForm()
    {
        return Dialog::make()
            ->title('Edit User')
            ->body([
                Form::make()
                    ->api('put:' . admin_url('/system/admin_users/{id}', true))
                    ->body([
                        TextControl::make()
                            ->name('username')
                            ->label('Username')
                            ->disabled()
                            ->required(),
                        TextControl::make()
                            ->name('email')
                            ->label('Email')
                            ->type('input-email')
                            ->required(),
                        TextControl::make()
                            ->name('name')
                            ->label('Full Name'),
                        SelectControl::make()
                            ->name('enabled')
                            ->label('Status')
                            ->options([
                                ['label' => 'Enabled', 'value' => 1],
                                ['label' => 'Disabled', 'value' => 0],
                            ]),
                    ])
            ]);
    }
}

```

--------------------------------

### Implement Extension Service Provider

Source: https://github.com/slowlyo/owl-admin/blob/master/_autodocs/07-extension-system.md

The Service Provider is the core of an extension, handling registration, booting, settings, permissions, and menu items.

```php
<?php
namespace Vendor\MyExtension;

use Slowlyo\OwlAdmin\Extend\ServiceProvider;
use Slowlyo\OwlAdmin\Renderers\Form;
use Slowlyo\OwlAdmin\Renderers\TextControl;
use Slowlyo\OwlAdmin\Renderers\Page;

class MyExtensionServiceProvider extends ServiceProvider
{
    protected string $extensionName = 'my-extension';
    
    public function register()
    {
        parent::register();
        
        // Register services
        $this->app->singleton('my-extension.service', MyService::class);
    }
    
    public function boot()
    {
        parent::boot();
        
        // Load routes
        if (file_exists($routes = __DIR__ . '/../routes.php')) {
            $this->loadRoutesFrom($routes);
        }
        
        // Load migrations
        $this->loadMigrationsFrom(__DIR__ . '/../database/migrations');
    }
    
    public function settingPanel()
    {
        return Page::make()
            ->title('My Extension Settings')
            ->body([
                Form::make()
                    ->api('post:/admin/my-extension/settings')
                    ->body([
                        TextControl::make()
                            ->name('api_key')
                            ->label('API Key')
                            ->required(),
                    ]),
            ]);
    }
    
    public function settings()
    {
        return [
            'api_key' => env('MY_EXTENSION_API_KEY', ''),
        ];
    }
    
    public function permission()
    {
        return [
            [
                'name' => 'View Reports',
                'slug' => 'my-extension.reports.view',
                'description' => 'View extension reports',
            ],
            [
                'name' => 'Configure Settings',
                'slug' => 'my-extension.settings.edit',
                'description' => 'Configure extension settings',
            ],
        ];
    }
    
    public function menu()
    {
        return [
            [
                'title' => 'My Extension',
                'icon' => 'fa fa-chart-bar',
                'url' => '/admin/my-extension',
                'order' => 40,
            ],
        ];
    }
}
```

--------------------------------

### Admin::make()

Source: https://github.com/slowlyo/owl-admin/blob/master/_autodocs/02-admin-class.md

Creates a new Admin instance. This is typically not needed as static methods can be used directly.

```APIDOC
## Admin::make()

### Description
Creates a new Admin instance.

### Method
`static make(): static`

### Returns
`Admin` instance

### Usage
Typically not needed; use static methods directly.

### Example
```php
$admin = Admin::make();
```
```

--------------------------------

### GET /admin/system/admin_users

Source: https://github.com/slowlyo/owl-admin/blob/master/_autodocs/08-routes-and-endpoints.md

Retrieves a paginated list of all admin users, with options to filter by username and enabled status.

```APIDOC
## GET /admin/system/admin_users

### Description
List all admin users with pagination.

### Method
GET

### Endpoint
/admin/system/admin_users

### Parameters
#### Query Parameters
- **page** (int) - Page number
- **pageSize** (int) - Items per page
- **username** (string) - Filter by username
- **enabled** (int) - Filter by enabled status (0 or 1)

### Response
#### Success Response (200)
- **status** (int) - 0 for success
- **data** (object) - List of admin users and pagination info
  - **items** (array) - Array of user objects
    - **id** (int) - User ID
    - **username** (string) - Username
    - **name** (string) - User's full name
    - **email** (string) - User's email
    - **enabled** (int) - User enabled status
  - **total** (int) - Total number of users
  - **page** (int) - Current page number
  - **pageSize** (int) - Items per page

#### Response Example
```json
{
    "status": 0,
    "data": {
        "items": [
            {"id": 1, "username": "admin", "name": "Admin", "email": "admin@example.com", "enabled": 1}
        ],
        "total": 10,
        "page": 1,
        "pageSize": 20
    }
}
```
```

--------------------------------

### Admin::bootstrap()

Source: https://github.com/slowlyo/owl-admin/blob/master/_autodocs/02-admin-class.md

Loads the bootstrap file from the configuration, if it exists. This is used for executing initialization code during middleware bootstrap.

```APIDOC
## Admin::bootstrap()

### Description
Loads the bootstrap file from config, if it exists.

### Method
`static bootstrap(): void`

### Config Key
`admin.bootstrap`

### Usage
Called during middleware bootstrap to execute initialization code.

### Example
```php
Admin::bootstrap();
```
```
Tokens:
Raw