DOCSEARCHbyAlgolia
Submit Docs

webman admin plugin

repository·main·Indexed 18 days ago

https://github.com/webman-php/admin

An administrative interface plugin for the webman PHP framework that provides a ready-to-use management dashboard. It includes a Menu API for managing hierarchical menu structures, an AccountController for administrator authentication and profile management, and a base Crud class to simplify the creation of CRUD controllers with built-in data permission limits and lifecycle hooks.

Tokens
8.5K
Snippets
29
Records
46
Agent score
63%

What's inside webman-php/admin

  4. Manage user roles via RoleController

    main

    The RoleController provides a CRUD interface for managing hierarchical user roles within the admin panel. It handles role creation, updates, deletion, and permission assignment.

    Key behaviors:

    • Hierarchical Structure: Roles are organized in a tree structure using a pid (parent ID) field. When a role is deleted, all its descendant roles are also deleted.
    • Permission Inheritance: When updating a role's permissions (rules), the system automatically synchronizes descendant roles by intersecting their existing permissions with the new set to ensure they don't hold permissions that the parent no longer allows.
    • Super Admin Protection: The super admin role (ID 1) cannot be deleted. Roles with rules set to * are treated as super roles; their rules and pid fields cannot be modified via standard updates.
    • Scoped Access: Non-super admin users are restricted to managing roles within their own scope (determined by Auth::getScopeRoleIds()).

  5. Implement data permission limits in Crud controllers

    main

    The Crud class provides built-in mechanisms to restrict data access based on the logged-in administrator. You can configure this by setting the following properties in your controller:

    • $dataLimit: Set to 'personal' to restrict users to only seeing/managing records they created, or 'auth' to restrict them to records within their assigned scope.
    • $dataLimitField: The name of the database column used to enforce the limit (e.g., admin_id).

    When $dataLimit is active, the select, insert, update, and delete methods will automatically inject or verify these constraints.

  6. Customize Crud data formatting

    main

    The Crud class supports different data formats for the select endpoint via the format request parameter. You can override these methods in your controller to change how data is returned to the frontend:

    • formatNormal: Standard paginated list response.
    • formatSelect: A simple key-value list (e.g., for dropdowns) containing name and value.
    • formatTree: Returns a hierarchical tree structure (requires a pid field on the model).
    • formatTableTree: Returns a tree structure based on the raw items.

    To change the default behavior, override the corresponding formatX method.

  7. AdminController permission and data constraints

    main

    The AdminController uses specific properties to control how data is accessed and which methods are protected by authentication:

    • $noNeedAuth: An array of method names that bypass authentication checks. By default, select is included.
    • $dataLimit: Defines the mechanism used to restrict data access. Set to 'auth' to use the authentication system's scoping.
    • $dataLimitField: The database field used for data limiting (defaults to 'id').

    Permission Rules

    • Super Admin: Bypasses most scope restrictions when inserting, updating, or deleting.
    • Role Scoping: When assigning roles, non-super-admins can only assign roles returned by Auth::getScopeRoleIds().
    • Data Scoping: When deleting, non-super-admins are restricted to the IDs returned by Auth::getScopeAdminIds().

  8. Synchronize permission rules from classes to the database

    main

    The syncRules method (called during select operations) automatically synchronizes permission rules defined in your PHP classes with the database.

    How it works:

    1. It scans existing rules in the database that have a class-based key (containing \).
    2. For each class, it uses Reflection to find public methods.
    3. It skips methods that are:
      • Named index.
      • Start with __ (magic methods).
      • Are listed in the class's $noNeedAuth or $noNeedLogin properties.
    4. For valid methods, it generates a key in the format ClassName@methodName.
    5. It uses the method's first line of DocBlock comment as the title for the rule.
    6. If the method exists in the class but not in the database, a new Rule is created with type set to 2.

    Note: This mechanism allows you to define permissions directly in your controller code and have them automatically appear in the admin panel.

  9. Extend the Crud class to implement admin controllers

    main

    The Crud class is a base class designed to simplify the creation of CRUD (Create, Read, Update, Delete) controllers for the admin panel. To use it, create a new controller that extends Crud and define the protected $model property with an Eloquent model instance.

    By extending this class, you automatically inherit standard API endpoints for select, insert, update, and delete. You can customize the behavior by overriding specific protected methods (hooks) such as doSelect, doInsert, doUpdate, doDelete, or afterQuery.

    namespace appasease;

use pluginaseaserameworkasease_controller;
use pluginaseaserameworkasease_crud;
use appaseaserameworkasease_model;

class MyController extends BaseCrud
{
    /**
     * @var BaseModel
     */
    protected $model = new MyModel();

    /**
     * Customize data after it is queried from the database
     */
    protected function afterQuery($items)
    {
        foreach ($items as $item) {
            // Modify items here
        }
        return $items;
    }
}

  11. Configure Pear Admin Menu

    main

    The menu configuration controls how the navigation menu is loaded and behaves. It supports asynchronous loading from a JSON data source.

    Key options:

    • data: Path to the JSON file containing menu data.
    • method: HTTP method used to fetch the menu data (e.g., GET).
    • accordion: Enables accordion-style expanding/collapsing menus.
    • collapse: Determines if the menu is collapsed by default.
    • control: Enables menu control features.
    • controlWidth: The width of the menu control element.
    • select: The number of items to select/show.
    • async: Whether to load the menu asynchronously.
    {
	"menu": {
		"data": "admin/data/menu.json",
		"method": "GET",
		"accordion": true,
		"collapse": false,
		"control": false,
		"controlWidth": 500,
		"select": "10",
		"async": true
	}
}