Difference between revisions of "ARK2"

Revision as of 20:15, 5 May 2016

This page details the progress on development of ARK 2.0

Supported Platforms

ARK will only actively support platforms that are actively supported by their maintainers. ARK may work on earlier versions but this is not guaranteed.

• PHP: A minimum of v5.6 will be supported (5.6 is in Security Support, 5.7 in active support, see http://php.net/supported-versions.php), v7 will be supported.
• MySQL/MariaDB v5.5 (lowest supported MySQL)
• PostgreSQL and SQLite may be considered later (most likely using a proper ORM abstraction library)

Code Repository

Development of ARK 2.0 is occurring in the open on GitHub https://github.com/lparchaeology/ark2

Standards

The PHP-FIG standards will be applied where-ever possible.

• PSR-1 and PSR-2 Coding Standards
• PSR-3 Logging Interface for interchangeable logging objects
• PSR-4 Auto-Loading Standard
• PSR-7 HTTP Message Interface for interchangeable Request/Response objects

PSR-3 and PSR-7 allow mixing and matching of component libraries from different vendors, and supports future-proofing by allowing switching between libraries with minimal code changes.

PSR-4 will be used for packaging, namespace and auto-loading of OO code. A good series of articles explaining PSR-4 and modern development and packaging in general can be found at the following:

• http://culttt.com/2013/01/07/what-is-php-composer/
• http://culttt.com/2014/03/12/build-php-package/
• http://culttt.com/2014/05/07/create-psr-4-php-package/

In consequence:

• Composer will be required for dependency management and OO class auto-loading
• All new external libraries will be installed by Composer under vendor/ and not libs/
• All new OO classes will be namespaced under LPArchaeology\ARK\
• All new OO code will be under src/ and not php/ (this will also clearly separate new code from old)

Framework

NOTE: This goal is more likely to be for ARK 3.0.

It is proposed to implement a new RESTful Request/Response framework using a Front Controller model, based on external components adhering to the PHP-FIG standards. This will reduce the amount of code maintained internally, update the code-base to modern web-app design principals, and provide a degree of future-proofing. Choosing a full framework at this point would force refactoring all of the model and view code at the same time, but by initially building our own light-weight controller framework we can migrate the model and view later. Once all parts are migrated, a full framework could be considered if required.

• Symphony components will be used to build the framework (alternative Slim?)

Read the following for further info:

• http://symfony.com/doc/current/book/http_fundamentals.html
• http://symfony.com/doc/current/book/from_flat_php_to_symfony2.html
• http://symfony.com/doc/current/create_framework/index.html

The ARK root folder will contain only the index.php file which will act as a dispatcher, receiving all Requests, matching the Route and dispatching them to the correct Controller. Each ARK page type and the api will have a Controller to read the model and construct the view before returning the Response. This will allow future flexibility for new request formats while still being able to support persistent legacy links. It will also allow for database config and user auth driven routing, e.g. one install may only expose the RESTful API, while others may only expose read-only pages.

Besides the core HTTP and Routing modules, the Security, Translations, Forms, Validation, and Console components should be considered.

Security

ARK currently uses PEAR LiveUser for user authentication and authorisation, but this hasn't been updated since 2010. The ARK API currently uses plain text user and password in the request URL which is insecure. ARK2 should require a new security solution.

Requirements

• User Authentication
  • Token-based
  • Local user database for stand-alone/internal use
  • Via OAuth and OpenID authentication services (Google, Facebook, etc)
• User Authorisation
  • Multiple User Roles/Groups with inherited permissions
• API authentication via token and secure login

Configuration

Significant changes to the configuration of ARK are being made to move from PHP file based configuration to database based configuration. This section will document these changes.

• The config/ folder will contain all user-editable php files required, all other config will be in the database
• The env_settings.php file is replaced by server.php and paths.php
• server.php contains the settings for the database connection and root server path and should be the only file requiring editing for a default ARK install
• paths.php contains the settings for the server file paths and should not need editing
• To set-up an ARK, copy the config folder from php/arkdb/config to teh root folder and edit as required
• preflight_checks.php now defaults to off, so needs to be enabled before running, and then deleted form config afterwards
• settings.php has moved from config/ to php/settings/ and no longer requires user editing, all settings are now held in the database and should be configured per the instructions

Database

• Configuration has been moved to the database
• A new ADO class wrapping PDO has been created to provide all database access for the new OO config classes
• db_functions.php has been cleaned up to move repeated code into new routines:
  • dbTimestamp() returns a timestamp
  • dbRunAddQuery() inserts a single row into a table
  • dbUpdateSingleIdRow() updates a single ID table row
  • dbUpdateAllRows() updates all rows matching a given key
• All DB functions have been moved into db_functions.php and use the new DB routines so they no longer create SQL themselves

Changes

Other significant changes are documented here.

• A number of config global variables have been renamed for consistency
  • Any var ending in _dir is an absolute filesystem directory path
  • Any var ending in _path is a URL path relative to the hostname and always starts with a '/'
  • Neither var ever ends in a separator
  • $ark_server_path -> $ark_root_dir
  • $ark_dir -> $ark_root_path and no longer ends in a /
  • $registered_files_host -> $registered_files_path
  • $phMagickDir -> $phmagick_file
  • ark_web_maptemp_dir -> ark_maptemp_path
  • $ark_lib_dir and $ark_lib_path point to the library folder
  • $skins_dir and $skins_path point to the skins folder
  • $skin_dir and $skin_path point to the current skin folder

• A number of config global variables have been renamed for clarity
  • $mode -> $search_mode
  • $ftx_mode -> $search_ftx_mode

• A number of config global variables have been deleted as they are not used:
  • $default_year
  • $conf_non_search_words
  • $conf_langs
  • $loaded_map_modules
  • $default_output_mode

• The logging globals have been changed
  • $log, $conf_log_add, $conf_log_edt, $conf_log_del are deleted
  • $log_ins, $log_upd and $log_del are used instead

• The $fs_path_sep and $fs_slash have been removed, use PATH_SEPARATOR and DIRECTORY_SEPARATOR constants instead.