Willetts Technology CakePHP Application Skeleton

A custom application skeleton for creating applications with CakePHP 5.x, enhanced with Willetts Technology's development tools and customizations.

This skeleton builds upon cakephp/app with additional features for streamlined development and deployment.

Tech Stack

Layer	Technology
Framework	CakePHP 5.3 (PHP 8.4+)
Database	MySQL 8.4+
Web Server	Nginx with PHP-FPM
Frontend	Bootstrap 5.3 via ButterCream plugin
Icons	Font Awesome 7 (CSS + webfonts)
JS Libraries	Vanilla JS (no jQuery), TomSelect, Inputmask
Build Tool	Gulp 5 (SCSS compilation, JS bundling, font installation)
Dev VM	Multipass via Innkeeper
Provisioning	Ansible playbooks (ansible/playbooks/development.yml)
Dev Services	Memcached, Mailpit (email testing), Chrony, SSL (self-signed)

Custom Features & Enhancements

ButterCream Plugin

This skeleton includes QueenCityCodeFactory/butter-cream, a custom CakePHP plugin providing Bootstrap 5 integration and theme components.

Development Environment

• Innkeeper / Ansible provisioning - Complete playbooks and roles for automated development environment setup
• Pre-configured services: PHP 8.4+ with FPM, Nginx with SSL, MySQL, Memcached, Mailpit, Node.js (NVM), Chrony

Frontend Asset Pipeline

• Gulp 5 build system - Automated SCSS compilation, JavaScript bundling, and asset optimization
• Modern frontend stack: Bootstrap 5.3+, Font Awesome 7, TomSelect, Inputmask
• No jQuery - All JavaScript is vanilla JS using native DOM APIs and Bootstrap 5 APIs

Custom JavaScript Modules

Pre-built JavaScript utilities in assets/app/js/:

• ajax-pagination.js - AJAX pagination, search forms, clear buttons, page-limit selects
• app-core.js - Core initialization (tooltips, popovers, masks, TomSelect, FormatTime)
• app-util.js - Shared utilities (HTML/attribute escaping)
• clipboard.js - Clipboard API wrapper
• format-time.js - UTC-to-local time conversion using Intl.DateTimeFormat
• modal-confirm.js - Bootstrap 5 confirmation modals for CakePHP helpers
• poptart.js - Bootstrap 5 toast notification system
• session-monitor.js - Session timeout monitoring with in-page re-login
• tmp-file-upload.js - Temporary file upload with progress bars

Custom SCSS Components

Organized styles in assets/app/scss/:

• Action dropdowns, button groups, custom buttons (xs sizes, square buttons)
• Callouts, cards, form enhancements, navigation
• Filter drawer, responsive layout, PDF-specific styles
• Template-specific styles

Additional Configuration

• US States configuration file (config/states.php)
• Enhanced .gitignore for development environment
• Crontab management
• Development-specific SSL configuration

The framework source code can be found here: cakephp/cakephp.

Quick Start

See docs/development-environment.md for full setup instructions.

1. Clone this repository and configure:

   cp config/app_local.example.php config/app_local.php

2. Launch the development environment:

   innkeeper up

3. Install dependencies and build assets:

   innkeeper exec composer install
   innkeeper exec npm install
   innkeeper exec gulp

Frontend Assets

Build with Gulp:

innkeeper exec gulp            # Build all (lint, compile, fonts, cache-bust)
innkeeper exec gulp styles     # Rebuild CSS only
innkeeper exec gulp scripts    # Lint + rebuild JS only
innkeeper exec gulp fonts      # Reinstall font files
innkeeper exec gulp watch      # Build then watch for changes

Documentation

• docs/development-environment.md - Local setup walkthrough
• docs/database.md - Database configuration (Docker / VM MySQL)
• docs/frontend-assets.md - Gulp pipeline, SCSS, JS, vendor libraries
• docs/innkeeper.md - Innkeeper CLI reference
• docs/migrations.md - Migration creation, consolidation, cleanup
• CHANGELOG.md - Version history and notable changes

Configuration

Read and edit the environment specific config/app_local.php and set up the 'Datasources' and any other configuration relevant for your application. Other environment agnostic settings can be changed in config/app.php.

The layout includes:

• Responsive navigation
• Custom button styles and components
• Card and callout components
• Form enhancements
• PDF-optimized styles
• Mobile-responsive design

Maintenance

Updating

Since this skeleton includes custom modifications on top of the upstream CakePHP/app, updates should be done carefully:

1. Fetch the latest upstream changes:

   git fetch upstream 5.x

2. Review the changes before merging:

   git log HEAD..upstream/5.x

3. Merge upstream changes:

   git merge upstream/5.x

4. Test thoroughly, particularly:

   • Custom controller and view modifications
   • ButterCream plugin compatibility
   • Asset compilation
   • Ansible playbooks

Dependencies

• PHP: 8.4 or higher
• CakePHP: 5.3+
• Node.js: 20+ (managed via NVM in the VM)
• Composer: Latest version

Credits

• Built on CakePHP
• Customized by Willetts Technology, Inc.
• Maintained by QueenCityCodeFactory