▲▼ D A R K W A V E

Web application development kit

DW is a "batteries-included" tool kit for quickly developing data-driven web applications. It's a pragmatic configuration of helpful libraries, light application boilerplate, and a turn-key solution for user authentication and management. It also establishes sensible conventions you can use to quickly build custom CRUD apps or SaaS projects to suit your individual needs.

What's Included?

Core tools

• Slim - base PHP framework
• Slime - Slim application scaffolding and rendering helpers
• Handlebars - template rendering via LightnCandy
• Bootstrap - base UI framework
• Tabler - Bootstrap-based UI kit
• Alpine.js - JS utility framework
• htmx - utilities for AJAX, CSS transitions, websockets, SSE
• DW Utilities (PHP) - back-end utility functions for authentication, image conversion, etc.
• DW Utilities (JS) - front-end utility functions for authentication, modals, form handlers, etc.
• php-image-resize - GD-based image manipulation library
• phpdotenv - automatic .env variable loading
• psr-jwt - PSR-compliant JWT middleware

Optional included libraries

• Dropzone - file uploader
• Litepicker - date picker
• List.js - table sorter
• TinyMCE - WYSIWYG text editor

Boilerplate functionality

• Full authentication process (login, register, forgot/reset pw)
• Sample blank application starter frame
• User management system which also provides full-stack examples of how to use DW for CRUD operations, form handling, photo uploading, and more

Requirements

• PHP >= 7.4 (8.1 recommended) compiled with GD
• MySQL (other PDO-compatible databases should work, but haven't been tested)
• Apache

Installation

Use Composer for the easiest installation:

composer create-project jyoungblood/dw new-project-name

You could also download the zip with all the files, or clone this repository with GIT or Degit (npx degit jyoungblood/darkwave). If you do any of these, be sure to run composer install the files are on your system.

Getting Started

Darkwave is designed to function in a LAMP environment, so we recommend developing on an actual web server (VPS or shared host).

Of course, it's still possible to develop your application locally with the common php -S localhost:8080 command. Just make sure you also have a MySQL host running in your local environemt as well (MAMP, DBngn, etc).

Once your environemt is set up, visit the url for your site to initiate the configuration process. This will generate a .env file with your database connection and basic site info and create an "Admin" user for your application.

_{* Note that DW ships with a blank .env as part of the repository. It's required for the application to operate, but as a best practice we'd recommend adding this to the .gitignore before making your own repository with this codebase.}

After configuration, log in with the newly-created admin account to see the boilerplate application frame and an introductory demo of DW's primary features.

Building with DW

The official documentation and user guide are perpetual works in progress and may not be completely ready for a while. In the mean time, take a look at the various pieces of the users section to see functional examples of how to manage data collections and perform CRUD operations with this tool kit:

• controllers/users.php
• templates/dw/users-list.html
• templates/dw/users-edit.html

This section also provides examples of working with modals, input validation, image uploading and resizing, table sorting, and more. If you're looking for a "best practices" illustration of working with DW, this is a good place to start.

Deployment

Deployment is intended to be very straightforward, just put the files in your production environment and you should be good to go. Aside from this, there are a few minor points worth considering:

• In your production .env file, set the SITE_MODE variable to "production"
• It's helpful to run the following commands to optimize your composer packages and CSS files:
  • composer update --optimize-autoloader
  • purgecss --css css/lib/*.css --content "templates/**/*.hbs" --output css/build
• For security purposes, the .htaccess file has certain file extensions disabled from being served by default. If you need to enable any of them for your application (.json, for example), remember to be security conscious and deny access to specific files (composer.json, for example) to prevent leaking sensitive information.
• Further performance and security optimizations can be made, of course, but be careful not to let the optimizing get in the way of providing value for your users and customers :)

Reference and Resources

DW / Core

• DW docs
• DW field guide
• Slim 4 docs
• Slim 4 cheatsheet
• SLIME Render
• VPHP - DB Kit
• VPHP - X-Utilities
• VPHP - HTTP Request
• HBS Cookbook
• HBS Cheatsheet

Bootstrap / UI

• HTML5 Cheatsheet
• Bootstrap docs
• Bootstrap cheatsheet
• Awesome Bootstrap
• Tabler docs
• Tabler components

Colors

• Reasonable Colors
• Open Color

JS libraries

• Alpine.js docs
• Alpine Toolbox
• List.js docs
• Dropzone docs
• Litepicker docs
• TinyMCE 6 docs

Icons

• Bootstrap Icons
• Tabler Icons
• React Icons

Misc

• Subnav - When using the default base template and components, a subnav can be easily added using a simple PHP array. See the /demo section of the index controller and the subnav section of the base template.

• HBS helpers - Slime-render provides a couple custom HBS helpers and makes it easy to add your own. See the initialize_handlebars_helpers() section of the slime-render class for an example. The HBS Cookbook provides more information for building simple and block custom helpers.

• More BS components - There are A LOT of Bootstrap components out there. The official BS examples and BS cheatsheet are good places to start.

• Customizing Tabler - Tabler is designed to be easily customized with CSS variables added to the :root element. See the Tabler docs for a customization example, and tabler.css for the default variable names and values.