README

English | 中文

A PHP attribute extension for EasyAdmin Bundle that provides a comprehensive set of attributes to configure admin interfaces using PHP 8 attributes. This package simplifies EasyAdmin configuration by leveraging PHP 8's attribute system to create clean, type-safe admin interfaces.

Table of Contents

• Features
• Requirements
• Installation
• Quick Start
  • Basic Entity Configuration
  • Permission-based Access Control
  • Advanced Configuration
• Available Attributes
  • Action Attributes
  • Field Attributes
  • Column Attributes
  • Filter Attributes
  • Permission Attributes
  • Event Attributes
• Configuration Examples
  • List Configuration
  • Form Field Configuration
  • Column Configuration
• Advanced Features
  • Tree View Support
  • Custom Events
  • Import/Export Configuration
• Contributing
• License

Features

• PHP 8 Attributes: Configure EasyAdmin entities using modern PHP 8 attributes
• Rich Field Types: Support for Text, RichText, Select, ImagePicker, LinkageField and more
• CRUD Operations: Complete set of attributes for List, Create, Edit, Delete, Copy, Import/Export operations
• Advanced Filtering: Comprehensive filtering and search capabilities with keyword support
• Form Validation: Built-in form layout configuration and validation attributes
• Data Formatting: Automatic column formatting for FileSize, Boolean, Images, and other common types
• Soft Delete: Support for soft delete operations with configurable behaviors
• Flexible Display: Customizable display conditions, sorting options, and pagination
• Permission System: Role-based access control with AsPermission attribute
• Event Handling: Rich event system for customizing CRUD operations
• Sub-CRUD Pages: Drawer-style popup sub-pages for complex data management
• Custom Actions: Configurable header and row-level action buttons
• Tree View: Hierarchical data display with parent-child relationships
• Remote Data Loading: Support for large datasets with remote loading capabilities

Requirements

• PHP 8.1 or higher
• EasyAdmin Bundle 4.x
• chrisullyott/php-filesize: ^4.2

Installation

composer require tourze/easy-admin-attribute

Quick Start

Basic Entity Configuration

<?php

use Tourze\EasyAdmin\Attribute\Action\Listable;
use Tourze\EasyAdmin\Attribute\Field\FormField;
use Tourze\EasyAdmin\Attribute\Action\Deletable;
use Tourze\EasyAdmin\Attribute\Column\ListColumn;

#[Listable]
#[Deletable(softDelete: true)]
class Product
{
    #[ListColumn]
    #[FormField(required: true)]
    private string $name;

    #[ListColumn]
    #[FormField(required: true)]
    private float $price;

    #[FormField]
    private string $description;
}

Permission-based Access Control

<?php

use Tourze\EasyAdmin\Attribute\Permission\AsPermission;
use Tourze\EasyAdmin\Attribute\Action\Listable;

#[AsPermission(name: 'product', title: 'Product Management')]
#[Listable(showTotal: true)]
class Product
{
    // Entity properties
}

Advanced Configuration

<?php

use Tourze\EasyAdmin\Attribute\Action\Listable;
use Tourze\EasyAdmin\Attribute\Field\SelectField;
use Tourze\EasyAdmin\Attribute\Column\PictureColumn;
use Tourze\EasyAdmin\Attribute\Filter\Filterable;

#[Listable(
    showPagination: true,
    actionWidth: 120,
    scrollX: 'max-content',
    showTotal: true,
    sortColumn: ['created_at' => 'DESC']
)]
#[Filterable]
class Product
{
    #[SelectField(entity: Category::class, choice: 'name')]
    private Category $category;

    #[PictureColumn(width: 60, height: 60)]
    private string $thumbnail;
}

Available Attributes

Action Attributes

• Listable: Configure list view with pagination, sorting, and display options
• Creatable: Enable entity creation with form configuration
• Editable: Configure edit operations with custom validations
• Deletable: Enable delete operations with soft delete support
• Copyable: Add copy functionality to duplicate entities
• Importable: Enable data import with template generation and field mapping
• Exportable: Configure data export with custom column selection
• BatchDeletable: Enable batch delete operations
• CurdAction: Configure sub-CRUD pages with drawer-style popup
• HeaderAction: Add custom action buttons to page headers
• ListAction: Add custom action buttons to list rows

Field Attributes

• FormField: Configure form fields with validation, layout, and display options
• SelectField: Create select fields with entity relations and custom choices
• RichTextField: Rich text editor integration with customizable toolbar
• ImagePickerField: Image upload and selection with preview functionality
• LinkageField: Create dependent dropdown fields with dynamic options
• ImportField: Configure field mappings for data import operations

Column Attributes

• ListColumn: Configure list view columns with sorting and formatting
• ExportColumn: Specify export settings and column transformations
• ImportColumn: Define import field mappings and data validation
• FileSizeColumn: Automatic file size formatting (bytes to human readable)
• PictureColumn: Image display configuration with thumbnail support
• BoolColumn: Boolean value formatting with custom labels
• CopyColumn: Column copying configuration for duplicate operations
• TreeView: Configure hierarchical data display with parent-child relationships

Filter Attributes

• Filterable: Add filtering capabilities to entity lists
• Keyword: Enable keyword search on specific fields

Permission Attributes

• AsPermission: Configure role-based access control for entities

Event Attributes

• OnRowFormat: Customize row formatting in list views
• OnLinkage: Handle linkage field dependencies
• BeforeCreate/AfterCreate: Hooks for entity creation
• BeforeEdit/AfterEdit: Hooks for entity editing
• AfterSwitch: Handle field switching events
• OnFilterQuery: Customize filter query building

Configuration Examples

List Configuration

#[Listable(
    showPagination: true,
    actionWidth: 120,
    scrollX: 'max-content',
    showTotal: true,
    totalTitleColumn: 'name',
    sortColumn: ['created_at' => 'DESC']
)]

Form Field Configuration

#[FormField(
    required: true,
    span: 12,
    label: 'Custom Label',
    placeholder: 'Enter value here',
    help: 'This is a help text'
)]

Column Configuration

#[ListColumn(
    sortable: true,
    width: 150,
    label: 'Custom Column Label'
)]

Advanced Features

Tree View Support

#[TreeView(
    parentField: 'parent',
    titleField: 'name',
    expandAll: false
)]

Custom Events

#[OnRowFormat(callback: 'formatProductRow')]
#[BeforeCreate(callback: 'validateProduct')]
#[AfterEdit(callback: 'updateProductCache')]

Import/Export Configuration

#[Importable(
    templateColumns: ['name', 'price', 'category'],
    requiredColumns: ['name', 'price']
)]
#[Exportable(
    filename: 'products-export',
    columns: ['name', 'price', 'category.name']
)]

Contributing

Please see CONTRIBUTING.md for details.

License

The MIT License (MIT). Please see License File for more information.