README

Admin dashboard plugin for CakePHP 5 with Bootstrap UI integration.

Requirements

• PHP 8.2 or higher
• CakePHP 5.3 or higher
• brammo/auth ^1.1 (loaded automatically)
• Optional: ext-imagick for image resize in the File Manager

Installation

Install via Composer:

composer require brammo/admin

Loading the Plugin

Load the plugin in your application's src/Application.php:

public function bootstrap(): void
{
    parent::bootstrap();
    
    $this->addPlugin('Brammo/Admin');
}

Features

View Helpers

The plugin provides view helpers to simplify UI development:

• ButtonHelper — Bootstrap-styled buttons with icons
• FormHelper — extends BootstrapUI with image (File Manager picker), html (WYSIWYG HTML editor), and dateRange (paired date inputs) control types; Form/translations element for locale-tabbed translatable fields

AppView also loads Brammo Content helpers (Date, Image, Flag) and Authentication.Identity.

See docs/HELPERS.md for detailed documentation and examples.

Controllers

UserController

Provides user profile management:

• profile() - View and edit user profile

FileManagerController

Built-in file and image manager with upload, browse, and management capabilities.

See docs/FILEMANAGER.md for detailed documentation.

Authentication

The plugin integrates with CakePHP Authentication and Brammo Auth plugin for user management and authentication.

Configuration

All configuration options are documented in docs/CONFIGURATION.md, including:

• Internationalization (defaultLocale)
• Authentication defaults (config/auth.php)
• HTML editor (Admin.Editor.height)
• Brand customization
• Home link and page title
• Sidebar menu
• Layout assets (CSS, JavaScript, fonts)
• File Manager (Admin.FileManager)

Development

Running Tests

# Run all tests
composer test

# Run with verbose output
vendor/bin/phpunit --testdox

Static Analysis

The project uses both PHPStan and Psalm for static code analysis:

# Run PHPStan (level 8)
composer stan

# Run Psalm (level 1)
composer psalm

# Run tests, code style, and PHPStan
composer check

# Run PHPStan + Psalm
composer analyse

See docs/PHPSTAN.md and docs/PSALM.md for detailed documentation.

Code Quality

• PHPStan Level: 8 (strictest)
• Psalm Level: 1 (strictest)
• PHP Version: 8.2+

Directory Structure

brammo/admin/
├── config/              # Plugin configuration
├── docs/                # Documentation
├── resources/           # Resources (translations, etc.)
│   └── locales/         # Translation files
├── src/                 # Source code
│   ├── Controller/      # Controllers
│   ├── FileManager/     # FileManagerService (filesystem logic)
│   ├── View/            # View classes and helpers
│   │   └── Helper/      # View helpers
│   └── AdminPlugin.php  # Plugin bootstrap
├── templates/           # Templates
│   ├── element/         # Template elements
│   ├── layout/          # Layouts
│   └── User/            # User views
├── tests/               # Test suite
│   ├── Fixture/         # Test fixtures
│   └── TestCase/        # Test cases
└── webroot/             # Public assets
    ├── css/             # Stylesheets
    └── js/              # JavaScript files

Contributing

1. Fork the repository
2. Create your feature branch (git checkout -b feature/amazing-feature)
3. Make your changes
4. Run tests and static analysis (composer check)
5. Commit your changes (git commit -am 'Add amazing feature')
6. Push to the branch (git push origin feature/amazing-feature)
7. Create a Pull Request

Code Standards

• Follow PSR-12 coding standards
• Write tests for new features
• Ensure all tests pass
• Maintain PHPStan level 8 and Psalm level 1 compliance
• Add type hints to all methods

License

This project is licensed under the MIT License - see the LICENSE file for details.

Author

Roman Sidorkin

• Email: roman.sidorkin@gmail.com
• GitHub: @brammo

Related Projects

• brammo/auth - Authentication plugin for CakePHP