Pre8

From PeopleAggregator

PeopleAggregator 2.0 - Draft Documentation

• Version 2.0 embodies a new architecture, as well as many new features and fixes.

• different projects can share code with a common Core
• any module can appear on any page
• site admins can dynamically create new pages and reconfigure them
• front controller architecture - a dispatcher and support for simple redirect rules

New Project Architecture for People Aggregator Projects

• Earlier revisions of People Aggregator could be customized by developers in ways that could make it costly to customize code and still benefit from improvements to the People Aggregator core.

Requirements

This People Aggregator code design update lets developers and resellers:

• manage multiple projects to benefit from bug fixes and upward compatible changes to a common PA core
• avoid maintaining multiple copies of code in different repositories -- a source of outdated code, bugs and merge errors
• define a Project -- a custom PA instance -- with a directory/repository that embodies its custom differences from core
• keep the custom project separate from core, both as SVN repositories and separate, clearly defined directories
• allow projects to support object oriented specialization of classes defined in pacore
• allow projects to customize via shadowing to replace any core file in any project when necessary

Project Directory Overview

The project contains:

• server configuration: local_config.php
• project configuration
• optional project custom DB update and API files
• sparse directory of custom files "shadowing" core files in a parallel structure
• link to pacore code repository

Details below:

Server

local_config.php -- settings specific to this running PA instance (e.g. ro1.dev.broadbandmechanics.com)

 outside of code repository, constructed and copied by admin during install, 

Project

Configuration Constants:

project_config.php -- settings specific to this project (e.g. all RadioOne including dev, staging, production)

 includes PA:: flag settings, including enabling of specific features -- copied from core and modified
 Examples: $pa_polls_enabled, $pa_celebrities_enabled
 these determine whether feature controls are enabled and will appear in admin panel
 the file LeftHandAdminModule/side_inner_private.tpl refers to these

project_constants.php -- additions/replacements to constants.php

project_page_defaults.php -- default module layout settings for pages in this project defaults are is defined in pacore's constants.php.

Code should merge any non-empty $project_settings_new elements into the standard $settings_new.

project.css -- style sheet adding and cascading or shadowing settings of network.css

Custom DB and API:

project_db_update.php -- custom database changes and updates defined for this project run after db_update

project.api (custom WSAPI definitions adding to or shadowing definitions in peepagg.api in core)

project_api_impl.php -- WSAPI implementation -- can this live up here in the project directory too?

In core /tools/build.sh should be modified to look up into project directory if it exists to include project.api into the API that is built.

Custom Pages/Modules:

paproject/ subdirectory

sparse (very few files compared to pacore) -- depends on amount of customization
file of same name and tree location here will replace/override/shadow corresponding file in pacore
additional files for custom added pages, modules, functionality also added here

Core the following pacore/ subdirectory is also contained and can be referred to by this project: pacore is a SVN External reference to current paalpha repository, named /pacore in the project

 contains the defaults for all PA behavior specialized or shadowed at the project level

 Our standard Admin page (currently named network_statistics.php) contains a left hand module:
 NetworkLeftLinksModules/center_inner_private.tpl will refer to variables in PA:: that have been
 set by the project's project_config.php (or left at their default values from default_config.php in core).
 These determine which Admin features will be rendered/available on the Network Settings page.
 Features, global flags like $simple, etc. can be turned on and off using those switches.

Parallel Structure

The /pacore and /paproject directories have parallel structure, except that if a file has not been customized in the project, it is absent from /paproject. In effect, to turn a current PA instance into a Project, organize the directory as above, set the configuration constant files, and create paproject/ by removing any files that are identical to their counterpart in pacore/. Then this project can benefit from bug fixes and upward compatible upgrades in core through a simple svn update.

Using PATH defaults to Implement Shadowing

To keep the system as transparent as possible, we expect to simply use the PATH variables in PHP, etc. to implement shadowing. By including the /paproject/ directory followed by the /pacore/ directory in the PATH search list, and referring to files using relative pathnames, we intend to keep shadowing clear and simple. This has been proposed for PHP references to / includes of .php and .tpl files, as well as JS and CSS references. The aim is to keep the logic and structure simple, so the engineering team can see clearly whether pacore or paproject code will be used simply through the presence/absence of files in /paproject, without having to review condition tables or code as well.

If we discover cases of limitations or special restrictions that interfere with this solution (e.g. restrictions on the use of relative pathnames in CSS files to ensure cross-browser compatibility), we will indicated through updates to this design document, perhaps using one of the approaches below.

Two proposed approaches we currently we do NOT think we will need for shadowing if we take the approach above:

 1) Computing file paths dynamically in PHP, for example in the PA class, when including files:
 require_once PA::include("api/Foo/Foo.php");
 2) Using the Front Controller (see below) to shadow /paproject when present in preference to /pacore files

Provide Flexibilty and Allow Object Oriented Design

Where possible, rather than shadowing (replacing) files in Core, we encourage a more object oriented approach to specialize PA code: specializing core classes in /api/ and /ext/ directories rather than rewriting and replacing them. This can simplify code updates and make complex merging unnecessary during code updates and maintenance. The flexibility of the shadowing system lets our current architecture and specialization style (file replacement) work when necessary.

Front Controller Algorithm

In the pre8 time frame, we will also be adding Front Controller code for prototyped by Zoran Hron, for general dispatch, security and site management functions. However, as indicated above, we don't expect pacore/paproject shadowing to be one of its functions.

TO DO

As we firm up details, subsequent drafts should include:

• Rules for updating files: repository upgrades, backmerge and file copying/maintenance rules.
• Specific scenarios, including specific plans to upgrade sites like Giant, RadioOne and Cyama