Difference between revisions of "ARK2/Technical"

From ARK
Jump to: navigation, search
(Front-end)
(Supported Platforms)
 
(38 intermediate revisions by the same user not shown)
Line 1: Line 1:
 
= Technical Details =
 
= Technical Details =
  
== Platforms ==
+
== Supported Platforms ==
  
* HTML5 will be used
+
ARK2 will only actively support platforms that are actively supported with security fixes by the upstream developers. ARK2 may run on platforms not actively supported, but this is not guaranteed and ARK2 may in the future require features only available in the supported platform versions.
* Browser support restricted to those supported by Bootstrap 3
+
 
* 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.
+
* Apache is supported and will require mod_rewrite, other servers may work.
* MySQL/MariaDB v5.5 or later (lowest supported MySQL) (5.6 for full-text index, 5.7.5 for spatial index)
+
* PHP: PHP 7.4 is required due to new language features. The minimum version will be the minimum supported by PHP (see in [http://php.net/supported-versions.php PHP Supported Versions].
* PostgreSQL v9.2 or later
+
* PHP intl extension and ICU will be required, the opcache and APCu cache extensions are strongly recommended for performance.
* SQLite 3.7.11 or later (required for multiple inserts)
+
* MySQL/MariaDB v5.7.8 or later (lowest supported MySQL, required for timestamps, full-text index, spatial index, and JSON type), utf8mb4 codeset only
* mod_rewrite will be required
+
* PostgreSQL v10 or later
* PHP intl extension and ICU will be required
+
* SQLite 3.9 or later (required for multiple inserts, full-text index, JSON type), Spatialite extension for spatial data
 +
* Redis is recommended for data caching
 +
* Linux and Mac are actively supported, Windows is also supported but minimally tested
 +
 
 +
== Browsers ==
 +
 
 +
ARK2 uses Bootstrap 3 for the default frontend. ARK2 therefore supports the browser versions supported by Bootstrap 3:
 +
 
 +
* Android 2.3
 +
* Android >= 4
 +
* Chrome >= 20
 +
* Firefox >= 24
 +
* Explorer >= 8
 +
* iOS >= 6
 +
* Opera >= 12
 +
* Safari >= 6
 +
 
 +
Note that particular features provided by add-ons may not support this set of browsers. Due to the separation of the ARK2 frontend, you are free to implement your own frontend in any toolkit should you have other requirements.
  
 
== Standards ==
 
== Standards ==
  
 
The [http://www.php-fig.org/psr/ PHP-FIG standards] will be used:
 
The [http://www.php-fig.org/psr/ PHP-FIG standards] will be used:
* PSR-1 and PSR-2 Coding Standards
+
* [http://www.php-fig.org/psr/psr-1/ PSR-1] and [http://www.php-fig.org/psr/psr-2/ PSR-2] Coding Standards
* PSR-3 Logging Interface for interchangeable logging objects
+
* [http://www.php-fig.org/psr/psr-3/ PSR-3] Logging API Standard
* PSR-4 Auto-Loading Standard
+
* [http://www.php-fig.org/psr/psr-4/ PSR-4] Auto-Loading Standard
* PSR-5 PHPDoc Standard (proposed)
+
* [http://www.php-fig.org/psr/psr-5/ PSR-5] PHPDoc Standard Proposal
* Symfony HTTP Foundation for interchangeable Request/Response objects
+
* [http://www.php-fig.org/psr/psr-6/ PSR-6] Caching API Standard
* PSR-7 HTTP Message Interface for interchangeable Request/Response objects if required for some components
+
* [http://symfony.com/doc/current/components/http_foundation.html Symfony HTTP Foundation] for interchangeable Request/Response objects
 +
* [http://www.php-fig.org/psr/psr-7/ PSR-7] HTTP Message Interface for interchangeable Request/Response objects if required for some components
 +
* HTML5 / CSS3 ES vTBD
 
* All files will be UTF8 using UNIX LF
 
* All files will be UTF8 using UNIX LF
  
Line 27: Line 46:
 
== Framework and Components ==
 
== Framework and Components ==
  
The chosen framework is the [http://silex.sensiolabs.org/ Silex] micro-framework built using [http://symfony.com/ Symphony] components
+
The chosen framework is the [http://silex.sensiolabs.org/ Silex] micro-framework built using [http://symfony.com/ Symphony] components, with a future upgrade path to the full Symfony Framework
  
 
Components will be carefully chosen to be well supported, stable, and interchangeable wherever possible. A number of criteria will be applied in selection:
 
Components will be carefully chosen to be well supported, stable, and interchangeable wherever possible. A number of criteria will be applied in selection:
Line 34: Line 53:
 
* Must be well documented
 
* Must be well documented
 
* Must be widely used and supported
 
* Must be widely used and supported
* Must have a strong community, small one-person efforts will only be considered if they are the de-facto standard
+
* Must have a strong community, small one-person efforts will only be considered if they are the de-facto standard or a 'well-known' developer
 
* Any database access must use Doctrine DBAL or ORM
 
* Any database access must use Doctrine DBAL or ORM
  
Line 45: Line 64:
 
* [http://auraphp.com/ Aura]
 
* [http://auraphp.com/ Aura]
 
* [https://github.com/silexphp/Silex/wiki/Third-Party-ServiceProviders-for-Silex-2.x Silex providers]
 
* [https://github.com/silexphp/Silex/wiki/Third-Party-ServiceProviders-for-Silex-2.x Silex providers]
 
* [http://www.userfrosting.com/ User frosting], a UserCake fork with RBAC user management, using Slim2, SBAdmin2, use for ideas
 
  
 
== PHP Autoloading ==
 
== PHP Autoloading ==
  
PSR-4 is used for packaging, namespace and auto-loading of OO code.
+
PSR-4 is used for packaging, namespace and auto-loading of code.
 
* [https://getcomposer.org/ Composer] will be required for dependency management and PSR-4 auto-loading
 
* [https://getcomposer.org/ Composer] will be required for dependency management and PSR-4 auto-loading
 
* All external libraries will be installed by Composer under vendor/
 
* All external libraries will be installed by Composer under vendor/
* All OO classes will be namespaced under ARK\
+
* All code to be Object Oriented and implemented using a namespace of ARK
* All OO code will be under src/
+
* All code will be under src/<namespace>
  
 
A good series of articles explaining PSR-4 and modern development and packaging in general can be found at the following:
 
A good series of articles explaining PSR-4 and modern development and packaging in general can be found at the following:
Line 61: Line 78:
 
* http://culttt.com/2014/05/07/create-psr-4-php-package/
 
* http://culttt.com/2014/05/07/create-psr-4-php-package/
  
== Git / Github ==
+
== Project Management ==
 +
 
 +
The ARK project is hosted on [https://gitlab.com/ GitLab], so you will need a free GitLab account to contribute to development. Bug reports may be opened using a Google or Facebook account. The code is also mirrored on GitHub.
 +
 
 +
The umbrella ARK project is organised under the [https://gitlab.com/arklab @arklab] group on GitLab, which includes the [https://gitlab.com/arklab/arkserver ARK Server] project. All public development and supported releases occur in this project repository. All code, issues, and wiki documentation on this project are public. All code contributions must pass formal code review before being merged. A separate GitLab group for [https://gitlab.com/lparchaeology L - P : Archaeology] manages private client forks and deployments of ARK Server.
  
Development is hosted on [https://github.com/lparchaeology Github], so you will need a free Github account to contribute code.
+
GitLab provides a very powerful web application for managing projects, but most local development is done using the standard git command line tools. If you are new to Git, you may find a desktop application easier to use. Options include [https://www.sourcetreeapp.com/ SourceTree], [https://www.gitkraken.com/ GitKraken], and [https://desktop.github.com/ Github desktop].
  
If you are new to Git, you may find the [https://desktop.github.com/ Github desktop application] easier to use. Alternatives are [https://www.sourcetreeapp.com/ SourceTree] and [https://www.gitkraken.com/ GitKraken].
+
=== Branching Strategy ===
  
We will use a simplifed version of the [https://wiki.qt.io/Branch_Guidelines Qt git workflow].
+
We will use a simplified version of the [https://wiki.qt.io/Branch_Guidelines Qt git workflow].
* '''dev''' branch is the semi-stable development branch for the next release
+
* '''master''' branch is the semi-stable development branch for the next release which should always be in a stable enough state to pass CI testing
* New feature or bugfix branches are branched off '''dev''' with the name of the author/group/client and the feature or bug number, e.g. '''jlayt/linked-data'''
+
* New feature or bugfix branches for the next release are branched off '''master''' prefixed with the name of the author/group/client and including the feature or bug number, e.g. '''jlayt/linked-data''' or '''jlayt/issue-1234'''
* Once a new feature is finished and passes testing, it is rebased onto the current '''dev''' and merged via a Github merge request with review
+
* Once a new feature is finished and passes testing, it is rebased onto the current '''master''' and merged via a merge request with review
* Alpha and Beta testing releases will be tagged on '''dev''' and not branched
+
* Alpha and Beta testing releases will be tagged on '''master''' and not branched
* Once '''dev''' is deemed feature complete and stable enough for a Release Candidate then a release branch will be branched off '''dev''' with the minor release number, e.g. '''release/2.0''', '''release/2.1''', etc
+
* Once '''master''' is deemed feature complete and stable enough for a Release Candidate then a release branch will be branched off '''master''' with the minor release number, e.g. '''release/2.0''', '''release/2.1''', etc
 
* Further testing will take place on the release branch, with fixes applied to to the release branch as required
 
* Further testing will take place on the release branch, with fixes applied to to the release branch as required
* Once ready for release, the release will be tagged with the point release number (e.g. 2.0.0) and all bugfixes merged back into '''dev'''
+
* Once ready for release, the release will be tagged with the point release number (e.g. 2.0.0) and all bugfixes merged back into '''master'''
* Any bugfixes for the stable release will be made in the earliest release branch they apply to and then merged forward through each release then eventually into '''dev''' (merges may be immediate or periodic depending on the volume)
+
* Any bugfixes for the stable release will be made in the earliest release branch they apply to and then merged forward through each release then eventually into '''master''' (merges may be immediate or periodic depending on the volume)
 +
* Bugfix branches for the stable release are branched off the release branch prefixed with the name of the branch and including the feature or bug number, e.g. '''fix/2.1/issue-1234'''
 +
 
 +
For practical purposes during alpha development of ARK Server 2.0 a simplified approach will be used:
 +
* '''dev''' branch is a temporary unstable development branch where code changes are developed
 +
* '''master''' branch will occasionally be refreshed from '''dev''' with finished near-stable features
 +
 
 +
=== Custom Forks ===
 +
 
 +
The following approach is recommended for developing custom versions of ARK Server outside the main ARK Server project
 +
* Create a new empty development repository
 +
* Add the arklab/arkserver repository as a git remote
 +
* Create a '''dev''' branch tracking a formal release branch on arklab/arkserver
 +
* Create a '''test''' branch tracking the '''dev''' branch
 +
* Create a '''prod''' branch tracking the '''test''' branch
 +
* All custom code development occurs on the '''dev''' branch
 +
* When custom code is stable for deployment to test server the '''dev''' branch is merged into the '''test''' branch
 +
* When custom code is stable for deployment to production server the '''test''' branch is merged into the '''prod''' branch
 +
* Production hotfixes can be developed on '''prod''' or a branch forked from '''prod'''
 +
* When a new ARK Server version is released the '''dev''' branch is rebased onto the new remote release branch for testing and then merged forward for testing
 +
* Test server deployment is a clone of the dev repository checked-out to the '''test''' branch and rebased when new test releases occur. Test config settings may be committed to the repo here.
 +
* Production server deployment is a clone of the dev repository checked-out to the '''prod''' branch and rebased when new production releases occur. Prod config settings may be committed to the repo here.
 +
 
 +
The steps to set this up on GitLab are:
 +
* Create the new project
 +
* Create the dev branch tracking the arklab/arkserver release branch
 +
* Create the test branch tracking the dev branch
 +
* Create the prod branch tracking the test branch
 +
* Protect the test and prod branches to allow only push/merge by Masters
 +
 
 +
The git commands required to set this up on a local server:
 +
* mkdir <project>
 +
* cd <project>
 +
* git init
 +
* git remote add arklab git@gitlab.com:arklab/arkserver.git
 +
* git fetch arklab
 +
* git branch -t dev arklab/master
 +
* git branch -t test dev
 +
* git branch -t prod test
 +
* git checkout dev
  
 
== Folder Structure ==
 
== Folder Structure ==
Line 83: Line 143:
 
  /
 
  /
 
  |- bin/
 
  |- bin/
   |- console
+
   |- sysadmin
 
  |- build/
 
  |- build/
 
   |- <see [[ARK2/Frontend|Frontend]]>
 
   |- <see [[ARK2/Frontend|Frontend]]>
Line 91: Line 151:
 
  |- var/
 
  |- var/
 
   |- cache/
 
   |- cache/
   |- logs/
+
   |- log/
 
  |- vendor/
 
  |- vendor/
  
* The 'bin' folder holds any executable binaries, primarily the admin console script
+
* The 'bin' folder holds any executable binaries, primarily the sysadmin console script
 
* The 'build' folder holds tools and source files for building [[ARK2/Frontend|frontends]]
 
* The 'build' folder holds tools and source files for building [[ARK2/Frontend|frontends]]
 
* The 'sites' folder holds the site specific files in a way that supports multi-site installs
 
* The 'sites' folder holds the site specific files in a way that supports multi-site installs
* The 'src' folder holds the ARK source code
+
* The 'src' folder holds the namespaced source code, e.g. src/ARK, src/MySite, etc
 
* The 'tests' folder holds the ARK auto-tests
 
* The 'tests' folder holds the ARK auto-tests
* The 'var' folder holds transitory site files, such as caches and logs
+
* The 'var' folder holds install-wide transitory files, such as caches and logs (site-specific go in the site folder)
 
* The 'vendor' holds the component library code managed by Composer
 
* The 'vendor' holds the component library code managed by Composer
  
Tarball packaging for release will not include the 'build' or 'test' folders, nor the contents of the 'vendor' folder.
+
Tarball packaging for release will not include the 'build', 'test', or 'vendor' folders.
  
 
The ARK2 'src' folder is organised as follows:
 
The ARK2 'src' folder is organised as follows:
Line 120: Line 180:
 
   |- <project>/
 
   |- <project>/
 
     |- frontend/
 
     |- frontend/
 +
      |- <custom>/
 +
    |- server/
 
       |- <custom>/
 
       |- <custom>/
  
Line 125: Line 187:
 
* The 'src/ARK/server' folder holds the ARK Server code, i.e. the backend code, API, database, etc
 
* The 'src/ARK/server' folder holds the ARK Server code, i.e. the backend code, API, database, etc
 
* The 'src/ARK/frontend' folder holds the ARK Web Front-end code. See [[ARK2/Frontend|Frontend]] for more details.
 
* The 'src/ARK/frontend' folder holds the ARK Web Front-end code. See [[ARK2/Frontend|Frontend]] for more details.
* The 'src/ARK/schema' folder holds the ARK Server code, i.e. the backend code, API, database, etc
+
* The 'src/ARK/schema' folder holds the ARK Server data schemas, such as database table definitions, instance data models, etc
* The 'src/<project>' folder would hold custom front-end code where another project wishes to run their own multi-site install with a single custom frontend, see [[ARK2/Frontend|Frontend]] for more details
+
* The 'src/<project>' folder would hold custom code where another project wishes to run their own multi-site install with a single custom frontend, see [[ARK2/Frontend|Frontend]] for more details
  
 
The ARK2 'sites' folder is organised as follows:
 
The ARK2 'sites' folder is organised as follows:
Line 133: Line 195:
 
  |- sites/
 
  |- sites/
 
   |- <site>/
 
   |- <site>/
 +
    |- bin/
 +
      |- console
 
     |- config/
 
     |- config/
 +
      |- credentials.json
 
       |- database.json
 
       |- database.json
 
       |- site.json
 
       |- site.json
Line 143: Line 208:
 
     |- translations/
 
     |- translations/
 
       |- <frontend>/
 
       |- <frontend>/
 +
    |- var/
 +
      |- cache/
 +
      |- log/
 
     |- web/
 
     |- web/
 
       |- .htaccess
 
       |- .htaccess
Line 150: Line 218:
  
 
* The 'sites/<site>' folder holds all the custom files required for a site. This allows for multi-site installs, as well as a simple site backup/transfer strategy. The <site> name is recommended to be the reverse domain name for the site if unique (e.g. com.example.www) or the subfolder if using a shared domain (e.g. mysite).
 
* The 'sites/<site>' folder holds all the custom files required for a site. This allows for multi-site installs, as well as a simple site backup/transfer strategy. The <site> name is recommended to be the reverse domain name for the site if unique (e.g. com.example.www) or the subfolder if using a shared domain (e.g. mysite).
 +
* The 'sites/<site>/bin' folder holds any site-specific executable binaries, primarily the site admin console script
 
* The 'sites/<site>/config' folder holds all the configuration files for the site.
 
* The 'sites/<site>/config' folder holds all the configuration files for the site.
 
* The 'sites/<site>/files' folder holds all the data files for the site, such as photos and documents. See [[ARK2/Files|Files]] for more details.
 
* The 'sites/<site>/files' folder holds all the data files for the site, such as photos and documents. See [[ARK2/Files|Files]] for more details.
Line 155: Line 224:
 
* The 'sites/<site>/templates' folder holds the frontend template files.
 
* The 'sites/<site>/templates' folder holds the frontend template files.
 
* The 'sites/<site>/translations' folder holds the frontend translation files.
 
* The 'sites/<site>/translations' folder holds the frontend translation files.
* The 'sites/<site>/web' folder is the webroot for the site, isolating only the front-controller and assets in this folder improves security.
+
* The 'sites/<site>/web' folder is the webroot for the site, isolating the front-controller and assets in this folder improves security.
 
* The 'sites/<site>/web/assets' folder holds the assets for the frontend(s), usually as a symlink back to the 'src/ARK/web/<frontend>/assets' folder to allow for easy updates. See [[ARK2/Frontend|Frontend]] for more details.
 
* The 'sites/<site>/web/assets' folder holds the assets for the frontend(s), usually as a symlink back to the 'src/ARK/web/<frontend>/assets' folder to allow for easy updates. See [[ARK2/Frontend|Frontend]] for more details.
  
== Environment ==
+
=== IDE ===
 
 
To develop ARK requires the following tools to be installed:
 
* [https://git-scm.com/ Git]
 
* [https://getcomposer.org/ Composer]
 
* [https://nodejs.org/en/ Node.js] (for frontend/theme development only)
 
 
 
You will also require PHP, a web server (Apache/PHP), a database server (MySQL/PostreSQL/SQLite), a web browser (Chrome/Firefox), and a an API client (Postman).
 
 
 
The following tools are recommend to adhere to ARK code quality standards:
 
* php-cs-fixer
 
* PHP CodeSniffer
 
 
 
=== macOS ===
 
 
 
On macOS, while you can install the requirements via standalone packages, we recommend using HomeBrew as it makes installing and updating all the tools used easier.
 
 
 
* Install XCode
 
* Install the Command Line Tools (includes Git)
 
* Download and install [http://brew.sh/ HomeBrew]
 
* <pre>brew install homebrew/php/composer homebrew/completions/composer-completion homebrew/php/php-cs-fixer homebrew/php/php-code-sniffer homebrew/php/sqlformat homebrew/php/phplint</pre>
 
* If you need to do front end development you will also need <pre>brew install node tidy-html5</pre><pre>cd build</pre><pre>./console build:install</pre>To update your build environment run <pre>./console build:update</pre>
 
* (Optional) Modify your .profile to enable command-line auto-complete
 
export HOMEBREW_GITHUB_API_TOKEN="token"
 
source /Library/Developer/CommandLineTools/usr/share/git-core/git-completion.bash
 
source /Library/Developer/CommandLineTools/usr/share/git-core/git-prompt.sh
 
GIT_PS1_SHOWDIRTYSTATE=true
 
PS1='\u@\h \W$(__git_ps1 " (%s)") \$ '
 
export PATH=/Users/odysseus/.bin:$PATH
 
 
 
NOTE add Homebrew to path!!!
 
 
 
The easiest way to run a webserver and database server is using [https://www.mamp.info/en/ MAMP]. Simply install MAMP and create a soft-link from the MAMP webroot to the location of your ARK git repository. The alternative is to use HomeBrew to configure and run your own install. The HomeBrew method is recommended for developing with PostgreSQL (TODO).
 
* <pre>brew install homebrew/php/php70 homebrew/php/php70-tidy homebrew/php/php70-xdebug</pre>
 
 
 
 
 
 
 
For QGIS Python:
 
* 'brew install python qt pyqt'
 
* 'pip install pep8 autopep8 jedi pb_tool '
 
 
 
TODO
 
* xdebug setup
 
* apache / php /mysql / mamp
 
* linter/fixer rulesets
 
 
 
=== Atom Editor ===
 
 
 
While text editors and IDEs are a deeply personal choice, we recommend using [https://atom.io/ Atom] as it is a cross-platform Open Source editor with powerful plugins to support the tools used by ARK. Using Atom ensures you have an environment consistent with the core ARK developers and ARK development standards.
 
 
 
After installing Atom, check the commandline tools have been installed.
 
 
 
Recommended Atom Packages:
 
* <pre>apm install atom-autocomplete-php atom-beautify atom-bootstrap3 atom-symfony2 autocomplete-sass doctrine linter-bootlint linter-csslint linter-eslint linter-jsonlint linter-markdown linter-php linter-phpcs linter-sass-lint linter-tidy linter-twig php-composer-completion php-cs-fixer php-debug php-twig symfony-snippets</pre>
 
 
 
Useful Atom Packages:
 
* sublime-style-column-selection
 
* autoclose-html
 
* browser-plus
 
* docblockr
 
* git-plus
 
* highlight-line
 
* highlight-selected
 
* minimap
 
* open-recent
 
* pigments
 
* platformio-ide-terminal
 
* project-manager
 
* sort-lines
 
* sync-settings
 
 
 
== Install ==
 
 
 
composer install
 
 
 
== Front-end ==
 
 
 
The front-end is built from the source assets files in the 'build/' folder and installed in the 'src/' folder. The individual site folders then symlink to the required front-end in 'src/', or copy if they wish to edit in place.
 
 
 
The front end build and install is managed by the build and admin consoles. The build console is in the 'build/' folder and is used to build/rebuild/install a front end if required. The Admin Console is used to link the installed front end to a site.
 
 
 
To build a front end you first need to install the build environment (see Environment for installing the prerequisites):
 
 
 
  ./console build:install
 
 
 
You may occasionally need to update the build environment, especially after an ARK upgrade:
 
 
 
  ./console build:update
 
 
 
To clone the build assets for a new front end from the Core front end, run the create command. You must provide a name for your new front end
 
 
 
  ./console build:frontend:create <frontend>
 
 
 
To build and install a frontend run the frontend command. You can supply a front end name to install or default to the core front end, and optionally a namespace for it to be installed under in 'src/'. Only use the ARK namespace if the front end is intended for the main ARK project.
 
 
 
  ./console build:frontend <frontend=core> <namespace=ARK>
 
 
 
This will install the built front end into 'src/<namespace>/frontend/<frontend>'.
 
 
 
You can also choose to build just one type of asset to save time, e.g. if you only changed a template and don't want to wait for the js to be rebuilt as well:
 
 
 
  ./console build:frontend:css <frontend=core> <namespace=ARK>
 
  ./console build:frontend:js <frontend=core> <namespace=ARK>
 
  ./console build:frontend:twig <frontend=core> <namespace=ARK>
 
 
 
To use a front end for a site, run the Admin Console.
 
 
 
To create an entirely new site, use the create command. This will create a new database, site folder, config and web subfolders, and link/copy the chosen front-end.
 
 
 
  site:create <site> <frontend> <namespace=ARK>
 
 
 
You will be asked if you want to link or copy the front-end. It is recommended to use the default link option as you will not need to update the site folder when the front-end changes. Only copy the front-end if you want to make small changes to the front-end without having to build a new namespaced front-end. This however is discouraged, you should build a namespaced front-end instead.
 
 
 
To enable a front-end other than core, you will need to edit the '<site>/config/site.json' file to set the name of the front-end.
 
 
 
To add another front-end to a site, or to refresh a copied front-end:
 
  
  site:frontend <site> <frontend> <namespace=ARK>
+
While text editors and IDEs are a deeply personal choice, we recommend using Eclipse or [https://atom.io/ Atom] as they are cross-platform Open Source IDEs with powerful plugins to support the tools used by ARK. Using Eclipse or Atom ensures you have an environment consistent with the core ARK developers and ARK development standards.

Latest revision as of 15:40, 21 September 2021

Technical Details

Supported Platforms

ARK2 will only actively support platforms that are actively supported with security fixes by the upstream developers. ARK2 may run on platforms not actively supported, but this is not guaranteed and ARK2 may in the future require features only available in the supported platform versions.

  • Apache is supported and will require mod_rewrite, other servers may work.
  • PHP: PHP 7.4 is required due to new language features. The minimum version will be the minimum supported by PHP (see in PHP Supported Versions.
  • PHP intl extension and ICU will be required, the opcache and APCu cache extensions are strongly recommended for performance.
  • MySQL/MariaDB v5.7.8 or later (lowest supported MySQL, required for timestamps, full-text index, spatial index, and JSON type), utf8mb4 codeset only
  • PostgreSQL v10 or later
  • SQLite 3.9 or later (required for multiple inserts, full-text index, JSON type), Spatialite extension for spatial data
  • Redis is recommended for data caching
  • Linux and Mac are actively supported, Windows is also supported but minimally tested

Browsers

ARK2 uses Bootstrap 3 for the default frontend. ARK2 therefore supports the browser versions supported by Bootstrap 3:

  • Android 2.3
  • Android >= 4
  • Chrome >= 20
  • Firefox >= 24
  • Explorer >= 8
  • iOS >= 6
  • Opera >= 12
  • Safari >= 6

Note that particular features provided by add-ons may not support this set of browsers. Due to the separation of the ARK2 frontend, you are free to implement your own frontend in any toolkit should you have other requirements.

Standards

The PHP-FIG standards will be used:

  • PSR-1 and PSR-2 Coding Standards
  • PSR-3 Logging API Standard
  • PSR-4 Auto-Loading Standard
  • PSR-5 PHPDoc Standard Proposal
  • PSR-6 Caching API Standard
  • Symfony HTTP Foundation for interchangeable Request/Response objects
  • PSR-7 HTTP Message Interface for interchangeable Request/Response objects if required for some components
  • HTML5 / CSS3 ES vTBD
  • All files will be UTF8 using UNIX LF

Plugins are available for Eclipse, Atom, and other IDEs to automatically check and/or apply these standards.

Framework and Components

The chosen framework is the Silex micro-framework built using Symphony components, with a future upgrade path to the full Symfony Framework

Components will be carefully chosen to be well supported, stable, and interchangeable wherever possible. A number of criteria will be applied in selection:

  • Must be standards compliant
  • Must be well supported with a solid development history
  • Must be well documented
  • Must be widely used and supported
  • Must have a strong community, small one-person efforts will only be considered if they are the de-facto standard or a 'well-known' developer
  • Any database access must use Doctrine DBAL or ORM

Significant and reliable sources of components include:

PHP Autoloading

PSR-4 is used for packaging, namespace and auto-loading of code.

  • Composer will be required for dependency management and PSR-4 auto-loading
  • All external libraries will be installed by Composer under vendor/
  • All code to be Object Oriented and implemented using a namespace of ARK
  • All code will be under src/<namespace>

A good series of articles explaining PSR-4 and modern development and packaging in general can be found at the following:

Project Management

The ARK project is hosted on GitLab, so you will need a free GitLab account to contribute to development. Bug reports may be opened using a Google or Facebook account. The code is also mirrored on GitHub.

The umbrella ARK project is organised under the @arklab group on GitLab, which includes the ARK Server project. All public development and supported releases occur in this project repository. All code, issues, and wiki documentation on this project are public. All code contributions must pass formal code review before being merged. A separate GitLab group for L - P : Archaeology manages private client forks and deployments of ARK Server.

GitLab provides a very powerful web application for managing projects, but most local development is done using the standard git command line tools. If you are new to Git, you may find a desktop application easier to use. Options include SourceTree, GitKraken, and Github desktop.

Branching Strategy

We will use a simplified version of the Qt git workflow.

  • master branch is the semi-stable development branch for the next release which should always be in a stable enough state to pass CI testing
  • New feature or bugfix branches for the next release are branched off master prefixed with the name of the author/group/client and including the feature or bug number, e.g. jlayt/linked-data or jlayt/issue-1234
  • Once a new feature is finished and passes testing, it is rebased onto the current master and merged via a merge request with review
  • Alpha and Beta testing releases will be tagged on master and not branched
  • Once master is deemed feature complete and stable enough for a Release Candidate then a release branch will be branched off master with the minor release number, e.g. release/2.0, release/2.1, etc
  • Further testing will take place on the release branch, with fixes applied to to the release branch as required
  • Once ready for release, the release will be tagged with the point release number (e.g. 2.0.0) and all bugfixes merged back into master
  • Any bugfixes for the stable release will be made in the earliest release branch they apply to and then merged forward through each release then eventually into master (merges may be immediate or periodic depending on the volume)
  • Bugfix branches for the stable release are branched off the release branch prefixed with the name of the branch and including the feature or bug number, e.g. fix/2.1/issue-1234

For practical purposes during alpha development of ARK Server 2.0 a simplified approach will be used:

  • dev branch is a temporary unstable development branch where code changes are developed
  • master branch will occasionally be refreshed from dev with finished near-stable features

Custom Forks

The following approach is recommended for developing custom versions of ARK Server outside the main ARK Server project

  • Create a new empty development repository
  • Add the arklab/arkserver repository as a git remote
  • Create a dev branch tracking a formal release branch on arklab/arkserver
  • Create a test branch tracking the dev branch
  • Create a prod branch tracking the test branch
  • All custom code development occurs on the dev branch
  • When custom code is stable for deployment to test server the dev branch is merged into the test branch
  • When custom code is stable for deployment to production server the test branch is merged into the prod branch
  • Production hotfixes can be developed on prod or a branch forked from prod
  • When a new ARK Server version is released the dev branch is rebased onto the new remote release branch for testing and then merged forward for testing
  • Test server deployment is a clone of the dev repository checked-out to the test branch and rebased when new test releases occur. Test config settings may be committed to the repo here.
  • Production server deployment is a clone of the dev repository checked-out to the prod branch and rebased when new production releases occur. Prod config settings may be committed to the repo here.

The steps to set this up on GitLab are:

  • Create the new project
  • Create the dev branch tracking the arklab/arkserver release branch
  • Create the test branch tracking the dev branch
  • Create the prod branch tracking the test branch
  • Protect the test and prod branches to allow only push/merge by Masters

The git commands required to set this up on a local server:

  • mkdir <project>
  • cd <project>
  • git init
  • git remote add arklab git@gitlab.com:arklab/arkserver.git
  • git fetch arklab
  • git branch -t dev arklab/master
  • git branch -t test dev
  • git branch -t prod test
  • git checkout dev

Folder Structure

The following install root folder structure is used by ARK2, based on the default Silex and Composer structure, but adapted to support multi-site and multi-tenant.

/
|- bin/
  |- sysadmin
|- build/
  |- <see Frontend>
|- sites/
|- src/
|- tests/
|- var/
  |- cache/
  |- log/
|- vendor/
  • The 'bin' folder holds any executable binaries, primarily the sysadmin console script
  • The 'build' folder holds tools and source files for building frontends
  • The 'sites' folder holds the site specific files in a way that supports multi-site installs
  • The 'src' folder holds the namespaced source code, e.g. src/ARK, src/MySite, etc
  • The 'tests' folder holds the ARK auto-tests
  • The 'var' folder holds install-wide transitory files, such as caches and logs (site-specific go in the site folder)
  • The 'vendor' holds the component library code managed by Composer

Tarball packaging for release will not include the 'build', 'test', or 'vendor' folders.

The ARK2 'src' folder is organised as follows:

/
|- src/
  |- ARK/
    |- frontend/
      |- api/
      |- admin/
      |- core/
    |- server/
      |- php/
      |- schema/
        |- database/
        |- json/
  |- <project>/
    |- frontend/
      |- <custom>/
    |- server/
      |- <custom>/
  • The 'src/ARK' folder holds the ARK Project specific code, this code is not intended for custom site code and will be over-written by any ARK update
  • The 'src/ARK/server' folder holds the ARK Server code, i.e. the backend code, API, database, etc
  • The 'src/ARK/frontend' folder holds the ARK Web Front-end code. See Frontend for more details.
  • The 'src/ARK/schema' folder holds the ARK Server data schemas, such as database table definitions, instance data models, etc
  • The 'src/<project>' folder would hold custom code where another project wishes to run their own multi-site install with a single custom frontend, see Frontend for more details

The ARK2 'sites' folder is organised as follows:

/
|- sites/
  |- <site>/
    |- bin/
      |- console
    |- config/
      |- credentials.json
      |- database.json
      |- site.json
    |- files
      |- <see Files>
    |- schema/
    |- templates/
      |- <frontend>/
    |- translations/
      |- <frontend>/
    |- var/
      |- cache/
      |- log/
    |- web/
      |- .htaccess
      |- index.php
      |- assets/
        |- <frontend>/
  • The 'sites/<site>' folder holds all the custom files required for a site. This allows for multi-site installs, as well as a simple site backup/transfer strategy. The <site> name is recommended to be the reverse domain name for the site if unique (e.g. com.example.www) or the subfolder if using a shared domain (e.g. mysite).
  • The 'sites/<site>/bin' folder holds any site-specific executable binaries, primarily the site admin console script
  • The 'sites/<site>/config' folder holds all the configuration files for the site.
  • The 'sites/<site>/files' folder holds all the data files for the site, such as photos and documents. See Files for more details.
  • The 'sites/<site>/schema' folder holds the site specific JSON Schema files.
  • The 'sites/<site>/templates' folder holds the frontend template files.
  • The 'sites/<site>/translations' folder holds the frontend translation files.
  • The 'sites/<site>/web' folder is the webroot for the site, isolating the front-controller and assets in this folder improves security.
  • The 'sites/<site>/web/assets' folder holds the assets for the frontend(s), usually as a symlink back to the 'src/ARK/web/<frontend>/assets' folder to allow for easy updates. See Frontend for more details.

IDE

While text editors and IDEs are a deeply personal choice, we recommend using Eclipse or Atom as they are cross-platform Open Source IDEs with powerful plugins to support the tools used by ARK. Using Eclipse or Atom ensures you have an environment consistent with the core ARK developers and ARK development standards.