PHPackages                             queencitycodefactory/butter-cream - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [Framework](/categories/framework)
4. /
5. queencitycodefactory/butter-cream

ActiveCakephp-plugin[Framework](/categories/framework)

queencitycodefactory/butter-cream
=================================

Butter Cream - A CakePHP Bootstrap 5 Theme/Plugin

v0.1.4(6y ago)11.5kMITPHPCI passing

Since Feb 26Pushed 1mo ago7 watchersCompare

[ Source](https://github.com/QueenCityCodeFactory/butter-cream)[ Packagist](https://packagist.org/packages/queencitycodefactory/butter-cream)[ Docs](https://github.com/QueenCityCodeFactory/butter-cream)[ RSS](/packages/queencitycodefactory-butter-cream/feed)WikiDiscussions cake-5.x Synced 1w ago

READMEChangelog (4)Dependencies (4)Versions (10)Used By (0)

Butter Cream
============

[](#butter-cream)

[![CI](https://github.com/QueenCityCodeFactory/butter-cream/workflows/ButterCream%20CI/badge.svg)](https://github.com/QueenCityCodeFactory/butter-cream/workflows/ButterCream%20CI/badge.svg)[![License: MIT](https://camo.githubusercontent.com/fdf2982b9f5d7489dcf44570e714e3a15fce6253e0cc6b5aa61a075aac2ff71b/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f4c6963656e73652d4d49542d79656c6c6f772e737667)](https://opensource.org/licenses/MIT)

A CakePHP 5 Plugin with Bootstrap 5 theme, custom helpers, components, and bake templates for rapid application development.

Requirements
------------

[](#requirements)

- PHP 8.4 or higher
- CakePHP 5.3 or higher
- Bootstrap 5 (via FriendsOfCake/bootstrap-ui)

Installation
------------

[](#installation)

Install the plugin via Composer:

```
composer require queencitycodefactory/butter-cream
```

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

```
public function bootstrap(): void
{
    parent::bootstrap();
    $this->addPlugin('ButterCream');
}
```

Features
--------

[](#features)

### Custom Base Classes

[](#custom-base-classes)

#### Controller

[](#controller)

- **`ButterCream\Controller\Controller`** - Extended base controller with:
    - Ajax pagination support with configurable limits
    - Automatic ajax layout switching
    - Enhanced pagination with page-out-of-bounds handling
    - Auto-loaded Flash and Referer components
    - PDF and Spreadsheet view support

### Components

[](#components)

#### Flash Component

[](#flash-component)

- **`ButterCream\Controller\Component\FlashComponent`**
- Enhanced flash messaging with HTML support by default
- Methods: `success()`, `error()`, `set()`

#### Referer Component

[](#referer-component)

- **`ButterCream\Controller\Component\RefererComponent`**
- Smart referer tracking and redirection
- Configurable ignored URLs
- Normalizes URLs for consistent matching
- Methods:
    - `setReferer()` - Store referer for later use
    - `getReferer()` - Retrieve current referer
    - `redirect()` - Redirect to referer or fallback
    - `isMatch()` - Check if referer matches a URL
    - `ignore()` - Add URL to ignore list

#### Export Component

[](#export-component)

- **`ButterCream\Controller\Component\ExportComponent`**
- Export controller support for spreadsheet and PDF downloads

### View Helpers

[](#view-helpers)

#### Ajax Helper

[](#ajax-helper)

- **`ButterCream\View\Helper\AjaxHelper`**
- `relatedData()` - Create containers for AJAX-loaded content

#### Alert Helper

[](#alert-helper)

- **`ButterCream\View\Helper\AlertHelper`**
- Bootstrap 5 alert and callout rendering
- `success()`, `error()`, `warning()`, `info()` - Typed alerts with icons
- `callout()` - Callout-style alerts
- Dismissible and non-dismissible variants

#### Badge Helper

[](#badge-helper)

- **`ButterCream\View\Helper\BadgeHelper`**
- Bootstrap 5 badge rendering with configurable color maps
- `badge()` - Generic badge with any variant
- `status()` - Status badges with automatic color mapping
- `priority()` - Priority badges with automatic color mapping
- `boolean()` - Yes/No badges for boolean values

#### Card Helper

[](#card-helper)

- **`ButterCream\View\Helper\CardHelper`**
- Bootstrap 5 card rendering
- `card()` - Standard card with header, body, footer
- `statsCard()` - Stats/metric display card
- `listGroupCard()` - Card with list group body

#### Flash Helper

[](#flash-helper)

- **`ButterCream\View\Helper\FlashHelper`**
- Enhanced flash message rendering with Bootstrap 5 styling

#### Filters Helper

[](#filters-helper)

- **`ButterCream\View\Helper\FiltersHelper`**
- Bootstrap 5 dropdown-based filter drawer for index pages
- `setup()` - Configure drawer ID, title, update selector, URL
- `addControl()` - Register filter fields (passed through to FormHelper)
- `render()` - Output toggle button and drawer panel with GET form
- Works in both standalone page and AJAX (relatedData) contexts
- Active filter count shown as badge on toggle button

#### Form Helper

[](#form-helper)

- **`ButterCream\View\Helper\FormHelper`**
- Extended Bootstrap 5 form helper
- `create()` - Automatic referer tracking in forms
- `postLink()` - Enhanced POST links with modal confirmation
- `deleteBtn()` - Pre-configured delete button
- `saveButton()` - Pre-configured save button with icon
- `cancelButton()` - Cancel with referer redirect
- `backButton()` - Back navigation button
- `continueButton()` - Continue/next step button
- `confirmButton()` - Modal-confirm enabled button
- `resetButton()` - Form reset button with icon
- `switch()` - Bootstrap 5 form-switch toggle
- `colorPicker()` - Color picker input with Bootstrap styling
- `control()` - Enhanced with `enhancedSelect` (auto TomSelect), input groups (`prepend`/`append`), floating labels

#### Format Helper

[](#format-helper)

- **`ButterCream\View\Helper\FormatHelper`**
- `ssn()` - Format US Social Security Numbers
- `zip()` - Format US ZIP codes (5 or 9 digit)
- `phone()` - Format US phone numbers
- `parsePhone()` - Parse phone number parts
- `formatString()` - Apply custom formatting patterns
- `maskString()` - Mask sensitive data

#### HTML Helper

[](#html-helper)

- **`ButterCream\View\Helper\HtmlHelper`**
- Extended Bootstrap 5 HTML helper
- `icon()` - Font Awesome icon shorthand
- `nullSafe()` - Display em-dash for null values
- `accordion()` - Bootstrap 5 accordion from array config
- `viewBtn()` / `editBtn()` / `addBtn()` - Pre-styled action buttons
- `actionDropdownMenu()` - Bootstrap 5 dropdown action menu

#### Paginator Helper

[](#paginator-helper)

- **`ButterCream\View\Helper\PaginatorHelper`**
- Bootstrap 5 styled pagination
- `ajaxTemplateOptions()` - Configure AJAX pagination link templates with `data-update` attribute
- Custom Font Awesome icons for prev/next
- Enhanced `prev()`, `next()`, `numbers()` methods

#### Progress Helper

[](#progress-helper)

- **`ButterCream\View\Helper\ProgressHelper`**
- Bootstrap 5 progress bar rendering
- `bar()` - Single progress bar with variant, label, striped, animated options
- `stacked()` - Multiple stacked progress bars

#### Table Helper

[](#table-helper)

- **`ButterCream\View\Helper\TableHelper`**
- `header()` - Generate sortable table column headers with sort direction indicators
- Bootstrap 5 table styling
- AJAX-aware: generates `ajax-pagination-link` class and `data-update` attributes when in AJAX context

#### Time Helper

[](#time-helper)

- **`ButterCream\View\Helper\TimeHelper`**
- `semantic()` - `` element with Bootstrap tooltip showing relative time
- `relativeTime()` - Human-friendly relative time strings
- `userFormat()` - Configurable date/datetime formatting

#### URL Helper

[](#url-helper)

- **`ButterCream\View\Helper\UrlHelper`**
- Extended URL helper

#### Gravatar Helper

[](#gravatar-helper)

- **`ButterCream\View\Helper\GravatarHelper`**
- Generate Gravatar image URLs

#### Filters Helper

[](#filters-helper-1)

- **`ButterCream\View\Helper\FiltersHelper`**
- Bootstrap 5 dropdown-based filter drawer for index pages
- Register filter controls in templates; the layout calls `render()` for the toggle button and drawer panel
- Works in both standalone page and AJAX (relatedData) contexts

#### Nested Tree Helper

[](#nested-tree-helper)

- **`ButterCream\View\Helper\NestedTreeHelper`**
- Render nested tree structures

### View Traits

[](#view-traits)

#### ButterCreamHelpersTrait

[](#buttercreamhelperstrait)

- **`ButterCream\View\ButterCreamHelpersTrait`**
- Reusable trait for loading the standard ButterCream helper stack in any View class
- Call `loadButterCreamHelpers()` from your View's `initialize()` method

### Model Layer

[](#model-layer)

#### AppTable

[](#apptable)

- **`ButterCream\Model\Table\AppTable`**
- Automatic data cleaning for weird character encodings (smart quotes, em dashes, etc.)
- Base table class with reusable callbacks

#### TreeviewTrait

[](#treeviewtrait)

- **`ButterCream\Model\TreeviewTrait`**
- `findTreeview()` - Custom finder for nested tree data
- Configurable key fields and nesting

#### Validation

[](#validation)

- **`ButterCream\Model\Validation`**
- `phone()` - Validate US phone numbers
- `postal()` - Validate US ZIP codes
- `ssn()` - Validate US Social Security Numbers
- `birthdate()` - Validate birthdate (not in future)

#### File Entity

[](#file-entity)

- **`ButterCream\Model\Entity\File`**
- File management entity with path and base64 getters
- Flysystem integration

### Services

[](#services)

#### FileService

[](#fileservice)

- **`ButterCream\Service\FileService`**
- Service-layer class for file storage, retrieval, resizing, and deletion
- Uses Flysystem for filesystem abstraction
- Model/foreign key pattern to associate files with any table record
- Image resizing with Imagick support
- Replaces the deprecated `FileApi`

### Exceptions

[](#exceptions)

#### ButterCreamException

[](#buttercreamexception)

- **`ButterCream\Http\Exception\ButterCreamException`**
- Base exception class for the plugin

#### StatusMessageException

[](#statusmessageexception)

- **`ButterCream\Message\Exception\StatusMessageException`**
- Exception for user-facing errors with flash message support

### Middleware

[](#middleware)

#### Session Timeout Middleware

[](#session-timeout-middleware)

- **`ButterCream\Routing\Middleware\SessionTimeoutMiddleware`**
- Configurable session timeout management
- AJAX-aware session extension
- Automatic session destruction on timeout

#### Trust Proxy Middleware

[](#trust-proxy-middleware)

- **`ButterCream\Routing\Middleware\TrustProxyMiddleware`**
- Configure proxy trust settings

### Utility Classes

[](#utility-classes)

#### Format

[](#format)

- **`ButterCream\Utility\Format`**
- Static formatting methods for SSN, phone, ZIP codes
- Pattern-based string formatting and masking

#### Muddle

[](#muddle)

- **`ButterCream\Utility\Muddle`**
- Array manipulation utilities
- `insert()` - Insert values using path notation
- `buildDotNotationPath()` - Build paths from arrays

### Database Types

[](#database-types)

#### JsonArrayType

[](#jsonarraytype)

- **`ButterCream\Database\Type\JsonArrayType`**
- Custom JSON array type with batch casting support

### Views

[](#views)

#### AppView

[](#appview)

- **`ButterCream\View\AppView`**
- Pre-configured with all ButterCream helpers

#### PdfView

[](#pdfview)

- **`ButterCream\View\PdfView`**
- PDF generation support via CakePdf
- Pre-configured with ButterCream helpers

### Bake Templates

[](#bake-templates)

Custom bake templates for rapid development with Bootstrap 5 styling:

- **Controllers** - Pre-configured with Search component and ButterCream base
- **Models/Tables** - Enhanced table templates with callbacks
- **Templates** - Bootstrap 5 styled CRUD views
    - `add.twig` - Create forms
    - `edit.twig` - Edit forms
    - `index.twig` - List views with tables
    - `view.twig` - Detail views
- **Form Elements** - Bootstrap 5 form styling

### Error Handling

[](#error-handling)

#### ExceptionRenderer

[](#exceptionrenderer)

- **`ButterCream\Error\ExceptionRenderer`**
- Custom error rendering with ButterCream theme
- Safe error message handling
- Debug-aware error messages

Usage Examples
--------------

[](#usage-examples)

### Using the Base Controller

[](#using-the-base-controller)

```
namespace App\Controller;

use ButterCream\Controller\Controller;

class ArticlesController extends Controller
{
    // Automatic Flash and Referer components loaded
    // Ajax pagination configured
    // PDF and Spreadsheet views available
}
```

### Using Referer Component

[](#using-referer-component)

```
public function delete($id)
{
    $article = $this->Articles->get($id);
    if ($this->Articles->delete($article)) {
        $this->Flash->success('Article deleted.');
    }

    // Redirect back to where user came from
    return $this->Referer->redirect(['action' => 'index']);
}
```

### Using Format Helper

[](#using-format-helper)

```
// In a template
echo $this->Format->phone('5551234567'); // (555) 123-4567
echo $this->Format->ssn('123456789'); // 123-45-6789
echo $this->Format->zip('12345'); // 12345
echo $this->Format->zip('123456789'); // 12345-6789
```

### Using Table Helper

[](#using-table-helper)

```
// Create sortable table headers