|
|
| (269 intermediate revisions by the same user not shown) |
| Line 4: |
Line 4: |
| | | | |
| | The primary aims of ARK2 are: | | The primary aims of ARK2 are: |
| | + | * Full code re-write to modern standards using modern components |
| | * Separate the ARK Database backend from the ARK Web frontend | | * Separate the ARK Database backend from the ARK Web frontend |
| − | * Implement a modern Restful API to allow other frontends and apps to access the ARK Database | + | * Implement a modern REST API to allow other frontends and apps to access and update the ARK Database |
| − | * Simplify the setup and configuration of ARK by moving the config into the database | + | * Simplify the setup and configuration of ARK by moving the config into the database and providing online config tools |
| − | * Improve the overall performance and data integrity or ARK | + | * Improve the overall performance and data integrity of ARK |
| | + | * Make it possible to provide an ARK hosting service |
| | | | |
| − | == Design ==
| + | Modern frontend |
| | + | * HTML5 |
| | + | * Bootstrap based |
| | + | * Twig templates |
| | + | * Front Controller model |
| | + | * Config driven pages views |
| | | | |
| − | High level design decisions for ARK2.
| + | Modern backend |
| | + | * Full REST API to access and update all ARK data |
| | + | * Database abstraction and Object Relational Mapping |
| | + | * Config driven data schema |
| | + | * Controlled Vocabularies and Linked Open Data |
| | + | * User Authentication via internal user/password and external OAuth2 providers (Facebook, Google, etc) |
| | + | * User Authorisation via Role Based Access Control (RBAC) using hierarchical Roles and Permissions structure |
| | + | * Field-level data access control |
| | + | * Data Workflows in conjunction with User Authorisation control |
| | | | |
| − | === Supported Platforms === | + | == Documentation == |
| | | | |
| − | ARK will only actively support platforms that are actively supported by their maintainers. ARK may work on earlier versions but this is not guaranteed.
| + | Details of ARK2 can be found in the following sections: |
| | | | |
| − | * HTML5 will be used | + | * [[ARK2/Design|Design]] - High Level Design Decisions |
| − | * 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.
| + | * [[ARK2/Technical|Technical]] - Technical details, Development tools and procedures |
| − | * MySQL/MariaDB v5.5 (lowest supported MySQL) | + | * [[ARK2/The_ARK_Way|The ARK Way]] - Web Development - The ARK2 Way |
| − | * PostgreSQL and SQLite will be provided for using a database abstraction layer, but not initially not offically supported
| + | * [[ARK2/Install|Install]] - Installation Instructions |
| − | * mod_rewrite will be required
| + | * [[ARK2/Architecture|Architecture]] - System Architecture |
| − | | + | * [[ARK2/Database|Database]] - Database / ORM details |
| − | === Development Standards ===
| + | * [[ARK2/Cache|Cache]] - Cache details |
| − | | + | * [[ARK2/Model|Model]] - Data model / Schema |
| − | The [http://www.php-fig.org/psr/ PHP-FIG standards] will be applied where-ever possible.
| + | * [[ARK2/View|View]] - Views on the Data Model |
| − | * PSR-1 and PSR-2 Coding Standards
| + | * [[ARK2/Spatial|Spatial]] - Spatial data |
| − | * PSR-3 Logging Interface for interchangeable logging objects
| + | * [[ARK2/Vocabulary|Vocabulary]] - Controlled Vocabularies |
| − | * PSR-4 Auto-Loading Standard
| + | * [[ARK2/Files|File Management]] - File, Image, and other Media Management |
| − | * PSR-7 HTTP Message Interface for interchangeable Request/Response objects
| + | * [[ARK2/Localization|Localization]] - Internationalization, Localization, and Translation |
| − | | + | * [[ARK2/Security|Security]] - Security, Authentication, Authorisation, User Management |
| − | 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.
| + | * [[ARK2/API|API]] - REST API implementation |
| − | | + | * [[ARK2/Frontend|Frontend]] - Web Frontend |
| − | 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:
| + | * [[ARK2/Templates|Templates]] - Using Twig for the Web Frontend |
| − | * http://culttt.com/2013/01/07/what-is-php-composer/ | + | * [[ARK2/Console|Console]] - Admin Consoles |
| − | * http://culttt.com/2014/03/12/build-php-package/ | + | * [[ARK2/Admin|Admin]] - Admin Frontend |
| − | * http://culttt.com/2014/05/07/create-psr-4-php-package/ | + | * [[ARK2/Branding|Branding]] - Branding of the ARK Project, Products, and Service |
| − | | |
| − | In consequence:
| |
| − | * [https://getcomposer.org/ 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 ===
| |
| − | | |
| − | It is proposed to implement a new RESTful Request/Response framework using a Front Controller model and token-based security, based on external components adhering to the [http://www.php-fig.org/psr/ 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 using PSR-compliant components we can migrate the model and view later. Once all parts are migrated, a full framework could be considered if required.
| |
| − | | |
| − | * [http://symfony.com/ Symphony] components will be used to build the framework (alternative [http://www.slimframework.com/ 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. It is a security risk, and also lacks many features like federated login. The ARK API currently uses plain text user and password in the request URL which is insecure. ARK2 will require a new security solution, especially for the API calls from client apps.
| |
| − | | |
| − | Requirements
| |
| − | * User Authentication
| |
| − | ** Token-based
| |
| − | ** Local user database for stand-alone/internal use
| |
| − | ** Via OAuth and OpenID authentication services (Google, Facebook, etc)
| |
| − | * User Authorisation
| |
| − | ** Role-Based Access Control (RBAC) model based on Users/Roles/Permissions
| |
| − | * API authentication via token and secure login
| |
| − | * Anonymous/Unauthenticated User access as optional Role for both Web and API
| |
| − | * A migration path from LiveUser must be provided.
| |
| − | | |
| − | Any solution chosen will work best when integrated with the other framework components chosen and should be implemented in parallel as it is highly dependent on the Request/Response/Routing/Session components used.
| |
| − | | |
| − | The Symfony Framework provides a very powerful Security component, but not a simple all-in-one solution meeting our requirements. Combining a number of external components may be able to meet our requirements, at the cost of more custom code required.
| |
| − | * Use Symfony\Security\Guard to manage the Authentication process | |
| − | * Use League\OAuth2-Client or Opauth or HWIOAuthBundle for external OAuth2 authentication
| |
| − | * Use League\OAuth2-Server or FOSOAuthServerBundle for OAuth2 server for API
| |
| − | * Use Sylius\RBAC or FOSUserBundle for User/Role management
| |
| − | | |
| − | The combination of HWIOAuthBundle / FOSOAuthServerBundle / FOSUserBundle is widely supported and more 'native' to Symfony, but requires the use of the full framework, bundles, Doctrine ORM, and YAML-based config. The alternatives are built as stand-alone interoperable PSR components and will provide greater future flexibility and a gentler migration path, but will require more work to integrate.
| |
| − | | |
| − | Alternatives such as Sentinal which provides all the required features in a single integrated component would require choosing a different component ecosystem, such as Laravel.
| |
| − | | |
| − | === Database Abstraction ===
| |
| − | | |
| − | Currently, PDO is used to directly access only MySQL databases, and DB access statements are widely spread and manually assembled. Adding support for other databases such as Postgres or SQLite would require considerable work (while PDO abstracts the connection, it doesn't abstract the SQL dialect). Longer term, full OO code and framework use will require the use of an ORM layer to map relational data to objects, but this would make for a longer migration process.
| |
| − | | |
| − | An interim step would be to make use of a Database Abstraction Layer that would abstract away the differences in SQL. These libraries usually also provide Query Builders, Data Seeding, and Schema Creation and Migration tools. Most are built on PDO and can seamlessly integrate with legacy code to make for an easier migration path.
| |
| − | | |
| − | Most frameworks implement a DAL, or use one of the major ORM's that also implement a DAL. The choice will largely be dictated by the framework components chosen, if Symfony is used then Doctrine DBAL would be the best choice.
| |
| − | | |
| − | Migration process:
| |
| − | * Move all PDO / SQL type calls into a set of common utilities in db_functions, i.e. insert, update, etc, that take arrays of fields and values, etc | |
| − | * Change all db functions to use new common utilities
| |
| − | * Move all db functions into db_functions
| |
| − | * Migrate new common utilities to chosen DAL
| |
| − | * All new table creation and data seeding to use DAL
| |
| − | | |
| − | === API ===
| |
| − | | |
| − | A RESTful API will be implemented using best practices which are outlined in the following articles:
| |
| − | * http://www.vinaysahni.com/best-practices-for-a-pragmatic-restful-api
| |
| − | * http://www.drdobbs.com/web-development/restful-web-services-a-tutorial/ | |
| − | * https://github.com/WhiteHouse/api-standards
| |
| − | | |
| − | In particular, the following rules will be applied:
| |
| − | * JSON will be the only format supported
| |
| − | * All JSON will be defined using the JSON Schema standard, which can be requested using the API and used to parse/format the JSON
| |
| − | * API versioning will be used to version the resource path structure, error messaging, and other API infrastructure. The actual data formats will be controlled by the JSON schema.
| |
| − | * Authenticated access will only be available using HTTPS, API tokens, and OAuth2 | |
| − | * Read-only unauthenticated unencrypted access will be supported only if explicitly enabled | |
| − | * Use module name or module code, i.e. contexts vs cxt?
| |
| − | | |
| − | Two options for paths:
| |
| − | * api/<version>/<module>/<site>/<item> - embeds site into api, makes some browsing/queries easier but what about non-site ARKs?
| |
| − | * api/<version>/<module>/<item> - makes site just an attribute, keeps item completely agnostic, but makes browsing/search harder?
| |
| − | * Maybe both? Use cxt/MNO12_1000 for pure ARK api, contexts/MNO12/1000 for more semantic version? | |
| − | | |
| − | The following HTTP verbs will be supported:
| |
| − | * GET - fetch resource
| |
| − | * POST - insert new resource with next id, i.e. insert a new item with next item_no
| |
| − | * PUT - insert or update resource with a specified id, i.e. insert a new item or update an existing item with a set item_no
| |
| − | * PATCH - update part of a resource, i.e. update a single field or group
| |
| − | * DELETE - delete a resource
| |
| − | * OPTIONS - What HTTP verbs the current authenticated API user can perform on a resource
| |
| − | | |
| − | Examples:
| |
| − | * api/<version>/<module>/<item> | |
| − | * api/v2/cxt/MNO12_1000 - fetch/update/delete item MNO12_1000
| |
| − | * api/v2/contexts?field=value&field2=value2 - returns the search results inside contexts | |
| − | * api/v2/contexts?sort=field1,field2 - returns the contexts sorted by | |
| − | * api/v2/contexts?q=text - returns the free-text search results inside contexts | |
| − | * api/v2/contexts/schema - returns the contexts json schema | |
| − | * api/v2/schema - returns the full json schema
| |
| − | * api/v2/filters - returns the list of global saved filters
| |
| − | * api/v2/filters/123 - returns the saved filter definition
| |
| − | * api/v2/users/jlayt/filters - returns the the list of user filters
| |
| − | | |
| − | Notes:
| |
| − | *Updating a resource will require some kind of timestamp or last update key to prevent overwriting subsequent changes
| |
| − | * All security / OPTIONS / anon access will be controlled by user roles
| |
| − | | |
| − | == Changes ==
| |
| − | | |
| − | Details of changes made in ARK2.
| |
| − | | |
| − | === Code Repository ===
| |
| − | | |
| − | Development of ARK 2.0 is occurring in the open on GitHub https://github.com/lparchaeology/ark2
| |
| − | | |
| − | === 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
| |
| − | | |
| − | === Globals ===
| |
| − | | |
| − | Globals are being progressively removed and replaced where possible by access to config objects.
| |
| − | | |
| − | 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
| |
| − | | |
| − | A number of globls have been replaced by PHP5 constants
| |
| − | * $fs_path_sep has been replaced with PATH_SEPARATOR
| |
| − | * $fs_slash has been replaced with DIRECTORY_SEPARATOR
| |
