Documentation

You are viewing the documentation for the 2.5.x release series. The latest stable release series is 3.0.x.

§Writing Play Modules

Note: This page covers the new module system to add new functionality to Play.

The deprecated play.Plugin system is removed as of 2.5.x.

A module can be written using any dependency injection framework. However, when you want to extend Play, you need to avoid dependencies on a specific framework so that your extension can work independently of the dependency injection. Play previously used the play.Plugin system for this purpose, but in 2.5.x, Plugins have been replaced with Play modules.

A Play module is a class that extends play.api.inject.Module and can be registered with Play without relying explicitly on a particular dependency injection framework. This allows everyone to use Play modules.

A list of Play modules are available in the module directory.

In addition, because Play uses Play modules for built-in functionality, a Play module must be used to replace or augment built-in functionality.

§Creating and migrating Play modules

Creating a Play module is simple:

public class MyApi {

}
public class MyModule extends play.api.inject.Module {
    public Seq<Binding<?>> bindings(Environment environment, Configuration configuration) {
        return seq(
                bind(MyApi.class).toSelf()
        );
    }
}

For more information, see the “Create a Module class” section of Plugins to Modules.

§Module registration

By default, Play will load any class called Module that is defined in the root package (the “app” directory) or
you can define them explicitly inside the reference.conf or the application.conf:

play.modules.enabled += "modules.MyModule"

Please see migration page and the dependency injection documentation for more details.

§Application lifecycle

A module can detect when Play shutdown occurs by injecting the play.inject.ApplicationLifecycle interface into the singleton instance and adding a shutdown hook.

Please see the `ApplicationLifecycle` example and ApplicationLifecycle reference for more details.

§Testing Play modules

Play Modules can be tested using Play’s built in test functionality, by using the GuiceApplicationBuilder and adding a binding to the module. 

Application application = new GuiceApplicationBuilder()
        .bindings(new MyModule())
        .build();

Please see Testing with Guice for more details.

§Listing existing Play modules

The Modules.locate(env, conf) method will display a list of all available Play modules in an application. There is no corresponding Java class.

§Overriding built-in modules

There are some cases where Play provides a built-in module that must be overridden. In these cases, the Java implementation is a wrapper over the Scala one, and so it’s usually more convenient to override the Scala implementation directly.

Next: Migrating from Plugins API

Found an error in this documentation? The source code for this page can be found here. After reading the documentation guidelines, please feel free to contribute a pull request. Have questions or advice to share? Go to our community forums to start a conversation with the community.