README

Create a component-based website

Install

Via Composer

composer require getpop/application

Development

The source code is hosted on the GatoGraphQL monorepo, under SiteBuilder/packages/application.

Usage

Initialize the component:

\PoP\Root\App::stockAndInitializeModuleClasses([([
    \PoP\Application\Module::class,
]);

Main Concepts

Multidomain

PoP has been built to support decentralization: modules can fetch their data from a different domain/subdomain from which the application is hosted. For instance, an application can have its components retrieved from subdomains:

A single component is also able to have many sources of data, each of them coming from a different domain/subdomain. For instance, the events calendar in SukiPoP.com displays events from several external sites in a unique calendar, painting events with a different color according to the source domain:

Architecture Design and Implementation

Dataloading

Lazy-Loading

We can instruct a dataloading module to be lazy-loaded (i.e. instead of fetching its database data immediately, it is fetched on a subsequent request from the client) simply by setting its prop "lazy-load" to true:

function initModelProps($component, &$props) 
{
  switch ($component->name) {
    case self::COMPONENT_AUTHORARTICLES:

      // Set the content lazy
      $this->setProp($component, $props, 'lazy-load', true);
      break;
  }

  parent::initModelProps($component, $props);
}

Being a prop, this value can be set either by the dataloading module itself, or by any of its ancestor modules:

function initModelProps($component, &$props) 
{
  switch ($component->name) {
    case self::COMPONENT_AUTHORARTICLESWRAPPER:

      // Set the content lazy
      $this->setProp([COMPONENT_AUTHORARTICLES], $props, 'lazy-load', true);
      break;
  }

  parent::initModelProps($component, $props);
}

Among others, the following are several uses cases for lazy-loading the data for a module:

• Modules which are displayed on several pages (eg: a "latest posts" widget on a sidebar) can have its data cached in the client (eg: through Service Workers, localStorage, etc) and, by lazy-loading, this data is not fetched again on the server on each request
• Fetching data from a different domain
• Improve apparent loading speed by lazy-loading data for below-the-fold modules (eg: a post's comments)
• Fetching data with user state on a page without user state (as outlined here)

Multidomain

By default, a module will fetch its data from the domain where the application is hosted. To change this to a different domain(s) or subdomain(s) is done by setting prop "dataload-multidomain-sources" on the module:

function initModelProps($component, &$props) {
    
  switch ($component->name) {
    case self::COMPONENT_SOMENAME:

      $this->setProp(
        $component, 
        $props, 
        'dataload-multidomain-sources', 
        'https://anotherdomain.com'
      );
      break;
  }

  parent::initModelProps($component, $props);
}

We can also pass an array of domains, in which case the module will fetch its data from all of them:

function initModelProps($component, &$props) {
    
  switch ($component->name) {
    case self::COMPONENT_SOMENAME:

      $this->setProp(
        $component, 
        $props, 
        'dataload-multidomain-sources', 
        array(
          'https://anotherdomain1.com',
          'https://subdomain.anotherdomain2.com',
          'https://www.anotherdomain3.com',
        );
      break;
  }

  parent::initModelProps($component, $props);
}

When fetching data from several sources, each source will keep its own state in the QueryInputOutputHandler. Then, it is able to query different amounts of data from different domains (eg: 3 results from domain1.com and 6 results from domain2.com), and stop querying from a particular domain when it has no more results.

Because the external application may have different components installed, it is not guaranteed that fetching data from the external application by simply adding ?output=json will bring the data required by the origin application. To solve this issue, when querying data from an external application, PoP will use the custom-querying API to fetch exactly the required data fields (this works for fetching database data, not configuration). If we have control on the external application and we can guarantee that both sites have the same components installed, then we can define constant EXTERNAL_SITES_RUN_SAME_SOFTWARE as true, which will allow to fetch database and configuration data through the regular ?output=json request.

PHP versions

Requirements:

• PHP 8.1+ for development
• PHP 7.2+ for production

Supported PHP features

Check the list of Supported PHP features in GatoGraphQL/GatoGraphQL

Preview downgrade to PHP 7.2

Via Rector (dry-run mode):

composer preview-code-downgrade

Standards

PSR-1, PSR-4 and PSR-12.

To check the coding standards via PHP CodeSniffer, run:

composer check-style

To automatically fix issues, run:

composer fix-style

Change log

Please see CHANGELOG for more information on what has changed recently.

Testing

To execute PHPUnit, run:

composer test

Static Analysis

To execute PHPStan, run:

composer analyse

Report issues

To report a bug or request a new feature please do it on the GatoGraphQL monorepo issue tracker.

Contributing

We welcome contributions for this package on the GatoGraphQL monorepo (where the source code for this package is hosted).

Please see CONTRIBUTING and CODE_OF_CONDUCT for details.

Security

If you discover any security related issues, please email leo@getpop.org instead of using the issue tracker.

Credits

• Leonardo Losoviz
• All Contributors

License

GNU General Public License v2 (or later). Please see License File for more information.