Downgrade codebase to 7.0 (to mirror WordPress' support range)

reimic commented 4 months ago

Since WordPress offers support for PHP >= 7.0 so should we.

Tasks:

[ ] choose and configure tools for static analysis,
[ ] choose and configure a compatible linter,
[ ] add an automated linting step to the CI pipeline.
[x] downgrade the codebase,
[x] sort out dependencies, replace or transpile if need be,
[x] add a blocking step to the CI pipeline detecting broken coding standards, (sorted out in PR #25)
[x] reimplement Json Mapper with less dependencies and PHP == 7.0 support (sorted out in PR #69)
[x] reimplement symfony/http-client (sorted out in https://github.com/WordPress/blueprints-library/commit/a9f10c13d27d92f9f343031c81486d7970f115b1)

adamziel commented 4 months ago

We'll need to:

Identify each used library that can't support PHP 7.0
Identify the task it performs in the project
If the task is simple, let's just reimplement it here. Perhaps even copy a part of that library and rewrite it to PHP 7.0.
If the task is complex, let's find an alternative library. If none exists, or if it would add many MBs of dependencies, then we may need to transpile the original library to PHP 7.0. One technique would be forking it, applying PHPCS auto-fixes, and ensuring its unit tests still run.

adamziel commented 4 months ago

All dependencies but three degrade gracefully to PHP 7.0. Here's the resulting composer.json:

{
  "prefer-stable": true,
  "require": {
    "symfony/event-dispatcher": "v3.4.47",
    "symfony/filesystem": "v3.4.47",
    "symfony/process": "v3.4.47",
    "symfony/http-kernel": "v3.4.49",
    "pimple/pimple": "v3.2.0",
    "psr/simple-cache": "1.0.1",
    "opis/json-schema": "1.1.0"
  },
  "require-dev": {
    "phpunit/phpunit": "6.5.14",
    "squizlabs/php_codesniffer": "3.9.0",
    "nette/php-generator": "v3.0.5",
    "bamarni/composer-bin-plugin": "v1.5.0",
    "wp-coding-standards/wpcs": "3.0"
  },
  "config": {
    "optimize-autoloader": true,
    "preferred-install": "dist",
    "allow-plugins": {
      "php-http/discovery": true,
      "bamarni/composer-bin-plugin": true,
      "dealerdirect/phpcodesniffer-composer-installer": true,
      "pestphp/pest-plugin": true
    },
    "platform": {
      "php": "7.0.8"
    }
  },
  "autoload": {
    "classmap": [
      "src/"
    ],
    "psr-4": {
      "WordPress\\": "src/WordPress",
      "Symfony\\Component\\Process\\": "vendor/symfony/process"
    },
    "files": [
      "src/WordPress/Blueprints/functions.php",
      "src/WordPress/Zip/functions.php",
      "src/WordPress/Streams/stream_str_replace.php"
    ]
  },
  "scripts": {
    "phpcs": "phpcs --standard=WordPress"
  }
}

adamziel commented 4 months ago

The three packages that don't play well with PHP 7.0:

symfony/http-client

The lowest version is 4.x and it requires PHP 7.1. We could fork and transpile it, but it also requires a ton of dependencies and the API wasn't that nice and reliable when I explored it for the URLSource. Let's see if the asynchronous HTTP streaming can be achieved with a custom implementation or another library. Guzzle 4.x seems to work with PHP 7.0 and support streams – perhaps it would do just fine? https://github.com/guzzle/guzzle/tree/4.x

json-mapper/json-mapper

The library is nice and useful but again it loads a bunch of dependencies. Let's try to reproduce its behavior using a small, custom, dependency-less implementation. Here's what it does in BlueprintMapper.php:

// In constructor
$this->mapper = JsonMapperBuilder::new()
    ->withPropertyMapper( new \JsonMapper\Handler\PropertyMapper( $classFactoryRegistry ) )
    ->withDocBlockAnnotationsMiddleware()
    ->withTypedPropertiesMiddleware()
    ->withNamespaceResolverMiddleware()
    ->build();

public function map( object $blueprint ): Blueprint {
    return $this->mapper->mapToClass( $blueprint, Blueprint::class );
}

tl;dr, it turns a raw json_decode() output into a Blueprint instance using the type information from PHP docblocks and custom data factories. See the details and related explorations in:

https://github.com/WordPress/blueprints/issues/13
Explorations in https://github.com/WordPress/blueprints/pull/17

jane-php/json-schema

This is a code generator for model classes originally explored in https://github.com/WordPress/blueprints/pull/19. It's a developer tool that doesn't need to work with PHP 7.0 at all, it can work in PHP >= 8.3 for all I care – it's merely a contributor tool not exposed to Blueprint library consumers. I'm not sure if there's a way of including it in composer.json but I wouldn't mind just shipping it as a .phar file directly in the repo.

adamziel commented 4 months ago

The above dependencies are no longer used in this repo. The only remaining part of this ticket are automated tools to ensure this library remains compatible with all PHP versions between 7.0 and 8.3

WordPress / blueprints-library