queencitycodefactory/app

Willetts Technology's Custom CakePHP skeleton app

5.3.1 2026-02-12 16:28 UTC

Requires

• php: >=8.2
• cakephp/cakephp: 5.3.*
• cakephp/migrations: ^5.0
• cakephp/plugin-installer: ^2.0
• mobiledetect/mobiledetectlib: ^4.8.03

Requires (Dev)

• cakephp/bake: ^3.6
• cakephp/cakephp-codesniffer: ^5.3
• cakephp/debug_kit: ^5.2
• josegonzalez/dotenv: ^4.0
• phpunit/phpunit: ^11.5.3 || ^12.1.3 || ^13.0

Suggests

• cakephp/repl: Console tools for a REPL interface for CakePHP applications.
• dereuromark/cakephp-ide-helper: After baking your code, this keeps your annotations in sync with the code evolving from there on for maximum IDE and PHPStan/Psalm compatibility.
• markstory/asset_compress: An asset compression plugin which provides file concatenation and a flexible filter system for preprocessing and minification.
• phpstan/phpstan: PHPStan focuses on finding errors in your code without actually running it. It catches whole classes of bugs even before you write tests for the code.

MIT

README

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)
• bulk-select.js - Table row select-all / bulk action checkboxes
• clipboard.js - Clipboard API wrapper
• dark-mode.js - Bootstrap 5.3 light/dark/auto theme toggle
• dependent-selects.js - Cascading AJAX-powered dependent dropdowns
• 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

Enums (src/Enum/)

PHP 8.4 native backed enums with a shared LabeledEnum interface and HasLabeledOptionsTrait trait:

• Priority - low, medium, high, critical (with Bootstrap badge colors)
• Status - draft, active, inactive, archived (with Bootstrap badge colors)
• UsState - All 50 US states + DC
• CanadianProvince - All 13 Canadian provinces and territories

Enums provide options() for Form select helpers, values() for inList() validation, and label()/color() for display.

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

• 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