plugin_platform_interface

This package provides a base class for platform interfaces of federated flutter plugins.

Platform implementations should extends their platform interface class rather than implements it, as newly added methods to platform interfaces are not considered breaking changes. Extending a platform interface ensures that subclasses will get the default implementations from the base class, while platform implementations that implements their platform interface will be broken by newly added methods.

This class package provides common functionality for platform interface to enforce that they are extended and not implemented.

Sample usage:

abstract class SamplePluginPlatform extends PlatformInterface {
                  SamplePluginPlatform() : super(token: _token);
                
                  static final Object _token = Object();
                
                  // A plugin can have a default implementation, as shown here, or `instance`
                  // can be nullable, and the default instance can be null.
                  static SamplePluginPlatform _instance = SamplePluginDefault();
                
                  static SamplePluginPlatform get instance => _instance;
                
                  /// Platform-specific implementations should set this to their own
                  /// platform-specific class that extends [SamplePluginPlatform] when they
                  /// register themselves.
                  static set instance(SamplePluginPlatform instance) {
                    PlatformInterface.verify(instance, _token);
                    _instance = instance;
                  }
                
                  // Methods for the plugin's platform interface would go here, often with
                  // implementations that throw UnimplementedError.
                }
                
                class SamplePluginDefault extends SamplePluginPlatform {
                  // A default real implementation of the platform interface would go here.
                }
                

This guarantees that UrlLauncherPlatform.instance cannot be set to an object that implements UrlLauncherPlatform (it can only be set to an object that extends UrlLauncherPlatform).

Mocking or faking platform interfaces

Test implementations of platform interfaces, such as those using mockito's Mock or test's Fake, will fail the verification done by verify. This package provides a MockPlatformInterfaceMixin which can be used in test code only to disable the extends enforcement.

For example, a Mockito mock of a platform interface can be created with:

class SamplePluginPlatformMock extends Mock
                    with MockPlatformInterfaceMixin
                    implements SamplePluginPlatform {}
                

A note about base

In Dart 3, the base keyword was introduced to the language, which enforces that subclasses use extends rather than implements at compile time. The Flutter team is considering deprecating this package in favor of using base for platfom interfaces, but no decision has been made yet since it removes the ability to do mocking/faking as shown above.

Plugin authors may want to consider using base instead of this package when creating new plugins.

https://github.com/flutter/flutter/issues/127396

2.1.8

• Fixes new lint warnings.

2.1.7

• Changes MockPlatformInterfaceMixin to a mixin class for better compatibility with projects that have a minumum Dart SDK version of 3.0.
• Updates minimum supported SDK version to Dart 3.0.

2.1.6

• Adds pub topics to package metadata.
• Updates minimum supported SDK version to Flutter 3.7/Dart 2.19.

2.1.5

• Updates README to improve example and discuss base.
• Updates minimum Flutter version to 3.3.

2.1.4

• Updates links for the merge of flutter/plugins into flutter/packages.
• Updates minimum supported Dart version.

2.1.3

• Minor fixes for new analysis options.
• Adds additional tests for PlatformInterface and MockPlatformInterfaceMixin.
• Modifies PlatformInterface to use an expando for detecting if a customer tries to implement PlatformInterface using implements rather than extends. This ensures that verify will continue to work as advertized after https://github.com/dart-lang/language/issues/2020 is implemented.

2.1.2

• Updates README to demonstrate verify rather than verifyToken, and to note that the test mixin applies to fakes as well as mocks.
• Adds an additional test for verifyToken.

2.1.1

• Fixes verify to work with fake objects, not just mocks.

2.1.0

• Introduce verify, which prevents use of const Object() as instance token.
• Add a comment indicating that verifyToken will be deprecated in a future release.

2.0.2

• Update package description.

2.0.1

• Fix federated flutter plugins link in the README.md.

2.0.0

• Migrate to null safety.

1.0.3

• Fix homepage in pubspec.yaml.

1.0.2

• Make the pedantic dev_dependency explicit.

1.0.1

• Fixed a bug that made all platform interfaces appear as mocks in release builds (https://github.com/flutter/flutter/issues/46941).

1.0.0 - Initial release.

• Provides PlatformInterface with common mechanism for enforcing that a platform interface is not implemented with implements.
• Provides test only MockPlatformInterface to enable using Mockito to mock platform interfaces.