Migrate to new PHP Analysis¶

How to upgrade¶

Upgrading is quite easy, simply add the PHP Scrutinizer command (php-scrutinizer-run) to your configuration.

This automatically disables the old PHP engine and only runs the new engine. Should you run into trouble with the new engine, you can always remove the command again to switch back to the old engine.

The new PHP analysis runs in our regular build environment. This has some advantages over maintaining a separate environment. First, we do not have to maintain a separate environment giving us more resources to focus on feature requests and bug reports. Second, it also gives you a lot more flexibility. For example, you can choose how to install your dependencies whether it is via composer, with custom composer installers, or custom shell scripts, or git submodules. You can also generate files that are necessary for the analysis, but not part of your repository.

If you do not yet have a build section in your configuration, simply add one with a single node to your configuration. As a convention, we recommend using the name analysis for the node that runs analysis related tasks, but it could be any other name:

build:
  nodes:
    analysis:
      tests:
        override:
          - php-scrutinizer-run

If you already have a build section, but do not yet use any nodes, make sure to move the existing configuration to a different node:

build:
  nodes:
    analysis:
      tests:
        override:
          - php-scrutinizer-run

    tests-and-coverage:
      # Everything that was previously under "build" directly goes here.

If some configuration is shared between nodes, you can also place it directly under build so that it will be inherited by all nodes. You can learn more about this in the multi-environment docs.

What changed?¶

The new PHP analysis was rewritten from the ground up in Scala and runs on the Java Virtual Machine (JVM) as a result, we can address some pain points which you were previously experiencing:

Cache building is not needed anymore¶

Previously, the analysis was building a cache for your dependencies which we had to clear from time to time or as your dependencies changed. This could add additional analysis time whenever it happened and make inspections less predictable.

Cache building is not needed anymore, the analysis will compute any information that it needs on-the-fly. This is possible due to better memory management of the JVM in particular when dealing with many objects and a lot better garbage collection system.

Better results, more precise¶

The new analysis engine is more precise in particular around overloaded methods. Previously, we cached a lot of analysis data. So, when building the cache, we had to guess which information might be relevant later for the analysis.

As that information is computed on-the-fly now, the analysis can compute more specific information that is relevant in the situation it is looking at and avoid computing information that is irrelevant. This allows us to make more informed decisions about the behavior of your code.

In particular, it improves handling of overloaded functions. You might say now that overloaded functions do not exist in PHP, and yes you are right. Let us have a look at a short example of the type of code we refer to:

/** @return string|resource */
function getContent($asResource = false) {
    if ($asResource) { return /* resource */; }

    return /* string */;
}

getContent(); // string
getContent(false); // string
getContent(true); // string

The new analysis can handle this perfectly fine without requiring any custom plugins or hard-coded behavior, but can infer this directly from your code.

Significantly faster¶

The new analysis is significantly faster. This is attributed first to on-the-fly computation of information. We do not spend time computing data that is irrelevant, and second due to the new platform (JVM vs. HHVM), the analysis is designed to compute data on multiple CPUs in parallel.

Code Intelligence ready¶

Code Intelligence data is automatically made available when switching to the new analysis.

Easier to run and debug¶

The old analysis ran in a separate environment. The new analysis runs in our regular build environment using multi-environment builds.

This in particular helps builds that are not using composer to install dependencies or require custom composer plugins. Also, since you have SSH access to the build environment, you can easily debug errors you might encounter.

Use annotations to ignore false-positives¶

The new analysis also supports inline annotations to suppress false-positives.