README

PHPStan extensions and rules for Silverstripe CMS.

Features ✨

Here are some of the nice features this extension provides:

• Recognition that configuration properties are always read and written.
• Correct return type for SilverStripe\Config\Collections\ConfigCollectionInterface::get().
• Correct return type for SilverStripe\Core\Config\Config_ForClass::get().
• Resolution of SilverStripe\Core\Extensible magic methods and properties.
• Type specification for SilverStripe\Core\Extensible::hasExtension() and SilverStripe\Core\Extensible::hasMethod() methods.
• Correct return types for SilverStripe\Core\Extension::$owner and SilverStripe\Core\Extension::getOwner().
• Correct return types for SilverStripe\Core\Injector\Injector::get() and SilverStripe\Core\Injector\Injector::create().
• Correct return type for SilverStripe\ORM\DataObject::dbObject().
• Type specification for SilverStripe\Model\ModelData::hasField() method.
• Type specification for SilverStripe\View\ViewableData::hasField() method.
• Various correct return types for commonly used Silverstripe modules.
• Customisable rules to help make your application safer.

Installation 👷‍♀️

Install via composer.

composer require --dev cambis/silverstan

If you also install phpstan/extension-installer then you're all set!

includes:
    - vendor/cambis/silverstan/extension.neon

Silverstripe 5.2 or greater is recommended

While this extension is not tied to a specific Silverstripe version it is recommended that you are on at least Silverstripe 5.2.

Silverstripe 5.2 introduces generic typehints. These changes allow the module to infer the types of objects without relying on an extension.

To make the best use of this module, make sure that your classes are correctly annotated using a combination of generics, and property/method annotations.

Bleeding edge 🔪

New and experimental features are available via the bleeding edge config. You can opt in by including the relevant config file.

includes:
    - vendor/cambis/silverstan/bleedingEdge.neon

Rules 🚨

Silverstan provides a set of customisable rules that can help make your application safer.

Each rule can be enabled/disabled individually using the configuration options, please refer to the rules overview for the available options.

SilverStripe\Dev\TestOnly 👨‍🔬

Complex analysis of SilverStripe\Dev\TestOnly classes is disabled by default. This is because these classes often contain dependencies that aren't provided by Silverstripe.

To enable complex analysis of these classes, please check the following option in your configuration file:

parameters:
    silverstan:
        includeTestOnly: true

If PHPStan complains about missing classes, be sure to add the corresponding package to your dev dependencies.

SilverStripe\Core\Extensible 🧑‍🔬

Solving magic methods and properties

Silverstan provides support for magic SilverStripe\Core\Extensible methods and properties.

Silverstan will attempt to resolve magic methods/properties by searching for existing annotations in the class ancestry first. If no annotation is found it will access the configuration API in order to resolve the magic method/property.

Using annotations is preferred, as they can often provide more information, have stricter types, and reduce the number of calls to the configuration API.

You can use Silverstripe Rector to create the annotations for you.

Solving SilverStripe\Core\Extensible::hasExtension() and SilverStripe\Core\Extensible::hasMethod()

Silverstan provides type specifying extensions for these cases. However, these extensions can only be applied on a per class basis.

The default configuration applies these extensions to SilverStripe\View\ViewableData and SilverStripe\Model\ModelData only. If you wish to add them to other SilverStripe\Core\Extensible classes that aren't subclasses of the former you can use the following configuration:

services:
    -
        # Solves `Foo::hasExtension()`
        class: Cambis\Silverstan\Type\TypeSpecifyingExtension\ExtensibleHasExtensionTypeSpecifyingExtension
        tags: [phpstan.typeSpecifier.methodTypeSpecifyingExtension]
        arguments:
            className: 'Foo'
    -
        # Solves `Foo::hasMethod()`
        class: Cambis\Silverstan\Type\TypeSpecifyingExtension\ExtensibleHasMethodTypeSpecifyingExtension
        tags: [phpstan.typeSpecifier.methodTypeSpecifyingExtension]
        arguments:
            className: 'Foo'

Solving SilverStripe\Core\Extensible::has_extension()

Warning

Silverstan does not support type specification for SilverStripe\Core\Extensible::has_extension(). If you use this method in your codebase, consider using one of the following examples to help solve errors that may be reported by PHPStan.

In the example below, we are adding a typehint to inform PHPStan of the expected type.

if (\SilverStripe\View\ViewableData::has_extension(Foo::class, FooExtension::class)) {
+  /** @var Foo&FooExtension $foo */
  $foo = Foo::create();
}

In the example below, we are changing the calls to use the dynamic SilverStripe\Core\Extensible::hasExtension() method which is supported by Silverstan.

$foo = Foo::create();

- if ($foo->has_extension(FooExtension::class)) {
+ if ($foo->hasExtension(FooExtension::class)) {
  // ...
}

- if ($foo::has_extension(FooExtension::class)) {
+ if ($foo->hasExtension(FooExtension::class)) {
  // ...
}

SilverStripe\Core\Config\Configurable 🧑‍🏭

The missingType.iterableValue error on configuration properties is ignored by default. This is because adding iterable information isn't useful unless the property is modified or accessed inside the current scope.

You can disable this behaviour in your configuration file.

parameters:
    silverstan:
        ignoreConfigurationPropertyTypeIterableValue: false

SilverStripe\Core\Config\Config_ForClass 👩‍🔬

Warning

Silverstan cannot resolve the type of a property fetch on SilverStripe\Core\Config\Config_ForClass, use SilverStripe\Core\Config\Config_ForClass::get() instead. See the rules overview.