ARK2/Technical

From ARK
Revision as of 09:15, 25 April 2018 by John Layt (talk | contribs) (→‎Git / Github)

Jump to: navigation, search

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.1 is required due to new language features. In future 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.5 or later (lowest supported MySQL, 5.5 for timestamps, 5.6 for full-text index, 5.7.5 for spatial index), utf8mb4 codeset only
  • PostgreSQL v9.2 or later
  • SQLite 3.7.11 or later (required for multiple inserts)
  • 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:

Git / Github

Development is hosted on Github, so you will need a free Github account to contribute code.

If you are new to Git, you may find the Github desktop application easier to use. Alternatives are SourceTree and GitKraken.

We will use a simplifed 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

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.

Retrieved from "https://ark.lparchaeology.com/wiki/index.php?title=ARK2/Technical&oldid=124970"