Discovery: Architectural design v2

[schlessera]

The organically grown architecture of the plugin currently has a few limitations within its WordPress application, and more-so renders most of the code useless outside of the WordPress context.

Given the long-term goal of providing official AMP support (through libraries or extensions) to more frameworks/applications than just WordPress (#2315), it makes sense to rethink the current architecture and overhaul it to better fit the goals of this long-term plan.

First of all, there should be a clear separation between:
a.) Server-side PHP code to deal with AMP (validation, sanitization, embed handling, ...)
b.) WordPress server-side integration (hooking up to WP routing, integrating into WP admin interface, ...)
c.) WordPress client-side integration (AMP Stories, ...)

The code for a.) should be generic PHP code (not using any WP functionality) pulled in as a Composer package.

The code for b.) and c.) should be a WordPress plugin. While they can certainly be housed within the same plugin, it might at one point make sense to separate them for diverging release cycles.

Some requirements we need to keep in mind:

• The code needs to stay either fully backwards compatible, or provide a sane migration path with ample time for the ecosystem to adapt. The specifics of this depend on the subsystem in question, as not all of them are equally used by third-party code.
• The strategy should not rely on an "all-or-nothing" approach, as we still need to focus on providing regular improvements to maintain the momentum.
• The focus should not be 100% on creating a pure abstraction, but rather progressing towards a clean separation of concerns that is easy to maintain and adapt. The abstraction itself should only be finalized with more targets (like Drupal or Joomla) actively involved. Starting too soon with finalizing the abstraction could still yield an unusable end result for other CMSes.
• A proper OOP approach should be used, to allow for easy changes down the road that can be completely transparent in terms of BC.

Considering the above, I suggest progressing in the following way:
1.) Reserve the PHP namespace AMP as the target for housing the refactored code. This gives us a clean slate in terms of naming.
2.) Start the redesign & refactoring process with a single subsystem at a time. Use the "Strangler Pattern" to move more and more subsystems over from the old codebase to the new codebase.
3.) Use an "anticorruption layer" between the old code and the new code, so that we don't need to compromise the new code to interact with old subsystems, but rather have a translation layer in-between. Otherwise, the new code would immediately start off on the wrong foot just to interoperate with the old one.
4.) Subsystems should slowly move from "old code as source of truth <=> new code as stubs executing old code" to "old code as stubs executing new code <=> new code as source of truth". So while we start with the new code getting a performance hit for overhead, we will at one point reverse this and have the performance hit in the old code.
5.) The old subsystem will receive deprecation notices as soon as the new subsystem is ready for prime time.

This approach lets us move the code over to a new design one subsystem at a time, while keeping things running smoothly and without (unmanaged) breaks in compatibility.

[schlessera]

Quick note regarding the generic PHP library:

At its most basic, the sanitization subsystem of the library should accept a string of HTML and return a string of valid AMP-HTML.

Due to the way most modern PHP frameworks are currently designed, we can then build a bridge package to provide a PSR-15 middleware that can be hooked up to most recent frameworks' controllers without additional code. So, providing an AMP endpoint in Laravel, for example, would just be a matter of pulling in said package and mapping an endpoint URL to use the provided middleware.

[schlessera]

Related:

• Extract post-processor logic into CMS-agnostic PHP library #2315 - Extract post-processor logic into CMS-agnostic PHP library
• Build abstraction layer #3077 - Build abstraction layer
• Refactor content transformation engine into a middleware stack #3662 - Refactor content transformation engine into a middleware stack

[amedina]

@schlessera can we start by creating an Architecture/Design PRD doc to move towards the making the changes in a concerted way?

[amedina]

Related to: #3077

[westonruter]

Also related #1478, a PR which I just closed that addresses a need for plugins to be able to filter default args that are passed into the sanitizers. Either that PR should be resurrected, or it should be addressed as part of the re-architecture of the sanitizers.