Revision as of 13:19, 9 January 2017

Technical Details

Supported Platforms

Apache is supported and will require mod_rewrite, other servers may work
PHP: PHP 7 is recommended, PHP 5.6 may be supported (currently in Security Support only.
PHP intl extension and ICU will be required, the APCu cache extension is strongly recommended
MySQL/MariaDB v5.5 or later (lowest supported MySQL) (5.6 for full-text index, 5.7.5 for spatial index)
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

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 (proposed)
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
Browser support restricted to those supported by Bootstrap 3
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

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:

Packagist, the Composer index
Symfony
PHP League
Zend
Sylius, components from an e-commerce platform based on Symfony
Aura
Silex providers

PHP Autoloading

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

Composer will be required for dependency management and PSR-4 auto-loading
All external libraries will be installed by Composer under vendor/
All OO classes will be namespaced under ARK\
All OO code will be under src/

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.

dev branch is the semi-stable development branch for the next release
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
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
Alpha and Beta testing releases will be tagged on dev 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
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
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)

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/
  |- console
|- build/
  |- <see Frontend>
|- sites/
|- src/
|- tests/
|- var/
  |- cache/
  |- logs/
|- vendor/

The 'bin' folder holds any executable binaries, primarily the admin 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 ARK source code
The 'tests' folder holds the ARK auto-tests
The 'var' folder holds transitory site files, such as caches and logs
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.

The ARK2 'src' folder is organised as follows:

/
|- src/
  |- ARK/
    |- frontend/
      |- api/
      |- admin/
      |- core/
    |- server/
      |- php/
      |- schema/
        |- database/
        |- json/
  |- <project>/
    |- frontend/
      |- <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 code, i.e. the backend code, API, database, 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 Frontend for more details

The ARK2 'sites' folder is organised as follows:

/
|- sites/
  |- <site>/
    |- config/
      |- database.json
      |- site.json
    |- files
      |- <see Files>
    |- schema/
    |- templates/
      |- <frontend>/
    |- translations/
      |- <frontend>/
    |- 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>/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 only 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.

Environment

To develop ARK requires the following tools to be installed:

Git
Composer
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 HomeBrew

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

If you need to do front end development you will also need
```
brew install node tidy-html5
```
(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:/usr/local/bin:/usr/local/sbin:$PATH

NOTE add Homebrew to path!!!

The easiest way to run a webserver and database server is using 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).

brew install homebrew/php/php70 homebrew/php/php70-tidy homebrew/php/php70-xdebug

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

Debian Jessie

curl -sL https://deb.nodesource.com/setup_6.x | sudo -E bash -
sudo apt-get install build-essential git nodejs php-codesniffer php-intl
curl -sS https://getcomposer.org/installer -o composer-setup.php
php composer-setup.php --install-dir=/usr/local/bin --filename=composer

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.

Install

cd <dev>
git clone git@github.com:lparchaeology/ark2.git
cd ark2/
composer install
<may need github token...>
cd build
./console build:install
<build frontend if needed>
cd ../bin
./console site:create <site>
<fix database load!>
ln -s <dev>/ark2/sites/<site>/web  /Applications/MAMP/htdocs/<site>
http://localhost:8888/<site>

Difference between revisions of "ARK2/Technical"

Revision as of 13:19, 9 January 2017

Contents

Technical Details

Supported Platforms

Standards

Framework and Components

PHP Autoloading

Git / Github

Folder Structure

Environment

macOS

Debian Jessie

IDE

Install

Navigation menu

Personal tools

Namespaces

Variants

Views

More

Search

Navigation

Tools