v3.2

Release summary

• added --stdout option to database export utility

v3.1

Release summary

• docker fixes
• cleanup README.md

bug fixes and documentation

Release Summary

• many bug fixes to command-line utilities
• configuration changes:
  • setting a "default-timezone" is now optional
  • no longer possible to specify a custom clientcal config root directory path (app/config/clientcal)
  • no longer possible to specify a custom autoload file path (vendor/autoload.php)

backwards-incompatible changes (edge-cases only)

This release SHOULD be backwards compatible with most existing installations, allowing for an easy upgrade, however, the following EDGE-CASE deployment scenarios will not be backwards compatible:

• If an existing deployment had a changed the contents of the "app/config/clientcal-config-path.php" file, and thus, the local deployment's location of the clientcal config root was not in the default location (i.e., not in app/config/clientcal), this could cause all entrypoints (scripts in "web" and "bin") to either crash or for the "wrong" configuration to be applied.

  • The solution is to move the deployment's clientcal config root to the default (now mandatory) location.

• If an existing deployment had changed the contents of the "app/config/autoloader-path.php" file, and thus, used autoloading that was not controlled by the local Composer configuration, all entrypoints (scripts in "web" and "bin") might crash due to unfulfilled dependencies.

  • The solution is either to use Composer to install the dependencies, or create a custom made script in "vendor/autoload.php" that registers class autoloading (outside the control of the local Composer configuration) or otherwise fulfills the necessary dependencies.

docker environment

Created a basic docker environment.

Docker environment requirements

• docker version 18.03 or newer
• docker-compose version 1.19 or newer

Docker environment for development and testing

The default configuration is suitable for local development and testing.

• Default configuration url: http://localhost:8080

basic usage

cd docker/compose/clientcal
docker-compose build
docker-compose start

Docker environment for public deployment

The docker environment is not suitable for public deployment of ClientCal as provided. It could be made suitable to deploy publicly only if modifications are made to provide provide SSL.

Examples of the easier ways this could be done are as follows:

• modifying the provided nginx configuration (such as with a volume mount) to use SSL
• deploying a separate public facing HTTP server with SSL that is configured to be a reverse proxy to the clientcal docker network port 8080
• deploying a separate public facing HTTP server with SSL that is configured to use CGI over the clientcal docker network port 9000

Cleanup, improvements, and fixes

This release contains fixes and improvements to the utility scripts, and some housekeeping to the application source code. End-user experience and UI is not affected by the changes included in this release.

---

Release Summary

• fixes were made to the bin/db-update.php utility to allow for safe database migrations
• sql-schema files were modified to correspond with changes to the db-update.php utility
• the RESTful API needs to be revamped; the related source code is thus considered abandoned and removed
• the templating system needs to be revamped; the related source code is thus considered abandoned and removed

Updates

The updates in this release involve bug fixes and some new utility scripts for the backend.
End-user experience and UI is not affected by the changes included in this release.

---

Release Summary

• new utility scripts to assist with installation, updates, and user management:
  • bin/config-update.php
  • bin/clientcal-user.php
• fixes for a variety of bugs and other issues

---

Utility Script Details

Two new scripts were created to assist with applying configuration (during installation or updates) and user management.

---

bin/config-update.php
Use the command line config update script (bin/config-update.php) to customize and properly configure the local clientcal installation.

The config update script can be invoked without any arguments; it will prompt for all the necessary configuration values.

php bin/config-update.php

The --help switch will provide details on more advanced usage (such as quiet and non-interactive modes).

php bin/config-update.php --help

---

bin/clientcal-user.php
The command line user manager script (bin/clientcal-user.php) can be used to manage ClientCal login users.

Usage:

php bin/clientcal-user.php <ACTION:add|change|remove> <USERNAME> [<PASSWORD>]

The add <ACTION> creates a new user:

php bin/clientcal-user.php add my_user

The change <ACTION> modifies an existing user's password:

php bin/clientcal-user.php change my_user

The remove <ACTION> removes an existing user:

php bin/clientcal-user.php remove my_user

The --help and --usage switches will provide details on more advanced usage (such as quiet mode and avoiding password prompts):

php bin/clientcal-user.php --help
php bin/clientcal-user.php --usage

Application Design Refactored

With this release; end-user will not experience any changes in their workflow or UI experience (except some very minor ones described below). The goal was to refactor the project design to prepare for significant updates in the future.

Feature Changes

This is the beginning of a set of feature changes that will be made in the future based on end-user feedback. I was able to make a few feature changes that affect end user experience in minor (hopefully positive) ways.

• customer pages /customer.php?edit={customer-id}
  • Removed ability to email 'customer files', as this feature was require when iOS did not support uploading via Safari. The normal 'file upload' feature works fine on all iOS devices now.
  • Minor UI changes to use icons to denote expanding/collapsing the 'files' area of a customer.
• schedule entry pages /sentry.php?show={senty-id}
  • Removed option to use Google Maps as it was strange to have users "choose" between Bing and Google.
  • Minor UI changes to use icons to denote expanding/collapsing the 'files' area of a customer.

Project Design Changes

The project design and code have been significantly altered. The purpose of these changes is to prepare for major UI updates to implementing Bootstrap 4 for a mobile friendly experience. The original code was written for earlier versions of php 5; having a project design that left much to be desired. While there are still quite a few deficiencies in the code; but, with this refactoring to a more ideal project design, it is at least on the right track! The following is a summary and description of the design changes.

• Moved the "include" folder contents to the "lib" folder.

• Config Files
  Configuration values used to be contained in a set of files in the "include" folder "settings.inc.php", "settings.sentry.inc.php"."settings.balive.inc.php". Functions which needed a configuration setting would perform a require "settings.inc.php" command to obtain the needed configuration values. This has been changed to a system using php files which return associative arrays containing the expected values, but referenced by an associative keys rather than defining variable names. See the "example 5" section regarding includes in the PHP manual.

  • separate 'config' files in app/config/clientcal. These are expected to return an associative array of configuration values, for example...

  /*begin config_file_example.php */
  $config=[];
  $config['setting1']='my_value1';
  $config['setting2'] = 'my_value2';
  return $config;
  /*end of config_file_example.php */

  • 'config' convenience class usage (class defined in src/config.php). For example, to obtain a particular config value through a simple class/method:

  use clientcal\config;
  $setting1 = (new config("config_file_exampl"))->getValue('setting1');

• php composer integration
  There were many project changes to facilitate use of composer's class and file autoloading.

  • Removed all code logic with require('exmple.php') commands for function definitions, such as...

  require("file-with-function definitions");

  • And, instead of above, made use of composer.json autoloading instead, for example...

  {"autoload": {
        "files": [
            "lib/DAL/customer.php",
            "lib/etc..."
         ]
    }}

• entry points and controllers
  Web based entry points for the application were previously located in the project root folder, they have now been moved to the web folder. Routing for applying UI and business logic is contained in corresponding controller files in app/Resources/controller. For example, given that the URL "https://example.com/sentry.php" corresponds to the entry point web/sentry.php. The entry points files consist of boilerplate code to prepare the app and activate the corresponding controller, for example, web/sentry, would include the controller app/Resources/controller/sentry.php.

  • sentry.php
    • view schedule entries (jobs) in various formats
      • monthly
      • weekly
      • single entry
    • create/edit/delete schedule entries
  • login.php
    • user authentication via user/pass login
  • _customer.php_
    • view customer information
    • upload files (such as photos) related to a customer ('customer files')
    • view, rename, and delete 'customer files'