Play Framework

https://www.playframework.com/documentation/3.0.x/
Admin
Play Framework is a high-productivity Java and Scala web application framework designed for building...
Tokens:3,219,542
Snippets:31,140
Trust Score:9.7
Update:2 weeks ago
Show doc for...
Tokens:
Raw
### start(ClassLoader, Configuration, Setup): ActorSystem

Source: https://www.playframework.com/documentation/3.0.x/api/scala/play/api/libs/concurrent/ActorSystemProvider%24.html

Starts an ActorSystem using the given configuration, ClassLoader, and additional ActorSystem Setup. Deprecated since version 2.8.0; use start(ClassLoader, Configuration, Setup*) instead.

```APIDOC
## start(ClassLoader, Configuration, Setup): ActorSystem

### Description
Starts an ActorSystem using the given configuration, ClassLoader, and additional ActorSystem Setup. Deprecated since version 2.8.0; use start(ClassLoader, Configuration, Setup*) instead.

### Method
start

### Signature
start(classLoader: ClassLoader, config: Configuration, additionalSetup: Setup): ActorSystem

### Parameters
- **classLoader** (ClassLoader) - Required - The ClassLoader to use.
- **config** (Configuration) - Required - The configuration for the ActorSystem.
- **additionalSetup** (Setup) - Required - Additional ActorSystem Setup.

### Returns
The ActorSystem and a function that can be used to stop it.

### Deprecation
Deprecated since version 2.8.0. Use start(ClassLoader, Configuration, Setup*) instead.
```

--------------------------------

### start(classLoader: ClassLoader, config: Configuration, additionalSetups: Setup*): ActorSystem

Source: https://www.playframework.com/documentation/3.0.x/api/scala/play/api/libs/concurrent/ActorSystemProvider%24.html

Starts an ActorSystem with the given configuration, ClassLoader, and optional additional Setups.

```APIDOC
## start(classLoader: ClassLoader, config: Configuration, additionalSetups: Setup*): ActorSystem

### Description
Starts an ActorSystem using the given configuration, ClassLoader, and optional additional ActorSystem Setups.

### Method
start

### Signature
```scala
def start(classLoader: ClassLoader, config: Configuration, additionalSetups: Setup*): ActorSystem
```

### Parameters
- **classLoader** (ClassLoader) - Required - The ClassLoader to use for the ActorSystem.
- **config** (Configuration) - Required - The configuration for the ActorSystem.
- **additionalSetups** (Setup*) - Optional - Additional ActorSystem Setups.

### Returns
The ActorSystem and a function that can be used to stop it.
```

--------------------------------

### start(classLoader: ClassLoader, config: Configuration, additionalSetup: Setup): ActorSystem

Source: https://www.playframework.com/documentation/3.0.x/api/scala/play/api/libs/concurrent/ActorSystemProvider%24.html

Starts an ActorSystem with the given configuration, ClassLoader, and an additional Setup. Deprecated in favor of the varargs version.

```APIDOC
## start(classLoader: ClassLoader, config: Configuration, additionalSetup: Setup): ActorSystem

### Description
Starts an ActorSystem using the given configuration, ClassLoader, and an additional ActorSystem Setup. Deprecated since version 2.8.0; use start(ClassLoader, Configuration, Setup*) instead.

### Method
start

### Signature
```scala
protected def start(classLoader: ClassLoader, config: Configuration, additionalSetup: Setup): ActorSystem
```

### Parameters
- **classLoader** (ClassLoader) - Required - The ClassLoader to use for the ActorSystem.
- **config** (Configuration) - Required - The configuration for the ActorSystem.
- **additionalSetup** (Setup) - Required - An additional ActorSystem Setup.

### Returns
The ActorSystem and a function that can be used to stop it.

### Deprecated
Since version 2.8.0. Use start(ClassLoader, Configuration, Setup*) instead.
```

--------------------------------

### start(classLoader: ClassLoader, config: Configuration, additionalSetups: Setup*): ActorSystem

Source: https://www.playframework.com/documentation/3.0.x/api/scala/play/api/libs/concurrent/ActorSystemProvider%24.html

Starts an ActorSystem using the provided configuration, class loader, and optional additional ActorSystem Setups. Returns the ActorSystem and a function that can be used to stop it.

```APIDOC
## start(classLoader: ClassLoader, config: Configuration, additionalSetups: Setup*): ActorSystem

### Description
Starts an ActorSystem, using the given configuration, ClassLoader, and optional additional ActorSystem Setups.

### Method
start

### Signature
```scala
def start(classLoader: ClassLoader, config: Configuration, additionalSetups: Setup*): ActorSystem
```

### Parameters
- **classLoader** (ClassLoader) - Required - The class loader to use for the ActorSystem.
- **config** (Configuration) - Required - The configuration for the ActorSystem.
- **additionalSetups** (Setup*) - Optional - Additional ActorSystem Setups.

### Returns
The ActorSystem and a function that can be used to stop it.
```

--------------------------------

### start(ClassLoader, Configuration): ActorSystem

Source: https://www.playframework.com/documentation/3.0.x/api/scala/play/api/libs/concurrent/ActorSystemProvider%24.html

Starts an ActorSystem using the given configuration and ClassLoader. Deprecated since version 2.8.0; use start(ClassLoader, Configuration, Setup*) instead.

```APIDOC
## start(ClassLoader, Configuration): ActorSystem

### Description
Starts an ActorSystem using the given configuration and ClassLoader. Deprecated since version 2.8.0; use start(ClassLoader, Configuration, Setup*) instead.

### Method
start

### Signature
start(classLoader: ClassLoader, config: Configuration): ActorSystem

### Parameters
- **classLoader** (ClassLoader) - Required - The ClassLoader to use.
- **config** (Configuration) - Required - The configuration for the ActorSystem.

### Returns
The ActorSystem and a function that can be used to stop it.

### Deprecation
Deprecated since version 2.8.0. Use start(ClassLoader, Configuration, Setup*) instead.
```

--------------------------------

### JUnit test class with database setup

Source: https://www.playframework.com/documentation/3.0.x/JavaTestingWithDatabases

Starts a complete JUnit test class example that integrates database setup, evolutions, and teardown. The snippet is truncated in the source; the full test is not shown.

```java
import static org.junit.Assert.*;

import java.sql.Connection;
import org.junit.*;
import play.db.Database;
import play.db.Databases;
import play.db.evolutions.*;

public class DatabaseTest {

  Database database;

```

--------------------------------

### Start server with fromApplication and GuiceApplicationBuilder

Source: https://www.playframework.com/documentation/3.0.x/ScalaEmbeddingPlayPekkoHttp

Creates a Play Application via GuiceApplicationBuilder and starts the server with the fromApplication method. The example shows building components with BuiltInComponentsFromContext and HttpFiltersComponents.

```scala
import play.api.mvc._
import play.api.routing.sird._
import play.core.server.PekkoHttpServer
import play.core.server.ServerConfig
import play.filters.HttpFiltersComponents
import play.api.Environment
import play.api.ApplicationLoader
import play.api.BuiltInComponentsFromContext

val context    = ApplicationLoader.Context.create(Environment.simple())
val components = new BuiltInComponentsFromContext(context) with HttpFiltersComponents {
  override def router: Router = Router.from {
    case GET(p"/hello/$to") =>
      Action {
        Results.Ok(s"Hello $to")
      }
  }
}
```

--------------------------------

### Start sbt console

Source: https://www.playframework.com/documentation/3.0.x/BuildingFromSource

Starts the sbt console in the Play source directory. Requires sbt to be installed.

```shell
$ sbt
```

--------------------------------

### Get configuration values with get method

Source: https://www.playframework.com/documentation/3.0.x/ScalaConfig

Demonstrates retrieving values of different types (String, Int, Boolean, Seq[String]) using the get method. Comments show example configuration values.

```scala
  
// foo = bar
config.get[String]("foo")

// bar = 8
config.get[Int]("bar")

// baz = true
config.get[Boolean]("baz")

// listOfFoos = ["bar", "baz"]
config.get[Seq[String]]("listOfFoos")
```

--------------------------------

### Output of run command in development mode

Source: https://www.playframework.com/documentation/3.0.x/PlayConsole

Example output after running the `run` command in development mode. Shows the server starting and listening on port 9000.

```text
$ sbt
[info] Loading global plugins from /Users/play-developer/.sbt/1.0/plugins
[info] Loading project definition from /Users/play-developer/tmp/my-first-app/project
[info] Done updating.
[info] Loading settings for project root from build.sbt ...
[info] Set current project to my-first-app (in build file:/Users/play-developer/tmp/my-first-app/)
[info] sbt server started at local:///Users/play-developer/.sbt/1.0/server/c9c53f40a402da68f71a/sock
[my-first-app] $ run
[info] Updating ...
[info] Done updating.
[warn] There may be incompatibilities among your library dependencies; run 'evicted' to see detailed eviction warnings.

--- (Running the application, auto-reloading is enabled) ---

[info] p.c.s.PekkoHttpServer - Listening for HTTP on /0:0:0:0:0:0:0:0:9000

(Server started, use Enter to stop and go back to the console...)
```

--------------------------------

### Example output of java -version

Source: https://www.playframework.com/documentation/3.0.x/Requirements

Example output from running java -version when Java 17 is installed. The exact version string may vary depending on your Java distribution.

```text
openjdk version "17.0.8" 2023-07-18
OpenJDK Runtime Environment Temurin-17.0.8+7 (build 17.0.8+7)
OpenJDK 64-Bit Server VM Temurin-17.0.8+7 (build 17.0.8+7, mixed mode)
```

--------------------------------

### createExample

Source: https://www.playframework.com/documentation/3.0.x/api/scala/play/api/test/PlaySpecification.html

Method to create an example fragment in a specification.

```APIDOC
## createExample[T](expression: String, code: => T, asResult: AsResult[T]): Fragments

### Description
Creates an example fragment for a specification.

### Method
createExample

### Parameters
- **expression** (String) - Required - The expression describing the example.
- **code** (=> T) - Required - The code to execute for the example.
- **asResult** (AsResult[T]) - Required - The result conversion.

### Returns
- **Fragments** - The created fragments.
```

--------------------------------

### Output of sbt run

Source: https://www.playframework.com/documentation/3.0.x/PlayConsole

Example output from running `sbt run`. Shows the application starting and listening on HTTP port 9000. Use Ctrl+D or Enter to stop the server and return to the console.

```text
[info] Loading project definition from /Users/play-developer/my-first-app/project
[info] Set current project to my-first-app (in build file:/Users/play-developer/my-first-app/)

--- (Running the application from sbt, auto-reloading is enabled) ---

[info] play - Listening for HTTP on /0:0:0:0:0:0:0:0:9000

(Server started, use Enter to stop and go back to the console...)
```

--------------------------------

### ExampleComponentsSpec using OneServerPerSuiteWithComponents

Source: https://www.playframework.com/documentation/3.0.x/api/scala/org/scalatestplus/play/components/OneAppPerSuiteWithComponents.html

Example test suite that mixes in OneServerPerSuiteWithComponents to get an Application with compile-time DI. It defines a router and overrides configuration, then verifies the application and configuration.

```scala
import org.scalatestplus.play.PlaySpec
import org.scalatestplus.play.components.OneServerPerSuiteWithComponents
import play.api._
import play.api.mvc.Result
import play.api.test.Helpers._
import play.api.test.{FakeRequest, Helpers}

import scala.concurrent.Future

class ExampleComponentsSpec extends PlaySpec with OneServerPerSuiteWithComponents {

  override def components: BuiltInComponents = new BuiltInComponentsFromContext(context) with NoHttpFiltersComponents {

    import play.api.mvc.Results
    import play.api.routing.Router
    import play.api.routing.sird._

    lazy val router: Router = Router.from({
      case GET(p"/") => defaultActionBuilder {
        Results.Ok("success!")
      }
    })

    override lazy val configuration: Configuration = Configuration("foo" -> "bar", "ehcacheplugin" -> "disabled").withFallback(context.initialConfiguration)
  }

  "The OneServerPerSuiteWithComponents trait" must {
    "provide an Application" in {
      import play.api.test.Helpers.{GET, route}
      val Some(result: Future[Result]) = route(app, FakeRequest(GET, "/"))
      Helpers.contentAsString(result) must be("success!")
    }
    "override the configuration" in {
      app.configuration.getOptional[String]("foo") mustBe Some("bar")
    }
  }
}

```

--------------------------------

### Start documentation server with sbt run

Source: https://www.playframework.com/documentation/3.0.x/Translations

Starts the documentation server. The output shows the server listening on port 9000 and the URL to view the docs.

```bash
$ sbt run
[info] Set current project to root (in build file:/Users/jroper/tmp/foo-translation/)
[info] play - Application started (Dev)
[info] play - Listening for HTTP on /0:0:0:0:0:0:0:0:9000

Documentation server started, you can now view the docs by going to http://0:0:0:0:0:0:0:0:9000
```

--------------------------------

### DefaultNettyServerComponents example

Source: https://www.playframework.com/documentation/3.0.x/api/scala/play/core/server/index.html

Example of constructing a Netty server using DefaultNettyServerComponents. Override the router to define routes and access the server via components.server.

```scala
val components = new DefaultNettyServerComponents {
  override lazy val router = {
    case GET(p"/") => Action(parse.json) { body =>
      Ok("Hello")
    }
  }
}
val server = components.server
```

--------------------------------

### CORSConfig.fromConfiguration example configuration

Source: https://www.playframework.com/documentation/3.0.x/api/scala/play/filters/cors/CORSConfig%24.html

Example configuration for building a CORSConfig from a play.api.Configuration instance. Shows the available keys and their default values, including pathPrefixes, allowedOrigins, allowedHttpMethods, allowedHttpHeaders, exposedHeaders, supportsCredentials, preflightMaxAge, and serveForOrigins.

```scala
play.filters.cors {
    pathPrefixes = ["/myresource", ...]  # ["/"] by default
    allowedOrigins = ["http://...", ...]  # If null, all origins are allowed
    allowedHttpMethods = ["PATCH", ...]  # If null, all methods are allowed
    allowedHttpHeaders = ["Custom-Header", ...]  # If null, all headers are allowed
    exposedHeaders = [...]  # empty by default
    supportsCredentials = true  # true by default
    preflightMaxAge = 1 hour  # 1 hour by default
    serveForbiddenOrigins = false  # false by default
}
```

--------------------------------

### createExample[T](expression: String, code: => T, asResult: AsResult[T]): Fragments

Source: https://www.playframework.com/documentation/3.0.x/api/scala/play/api/test/PlaySpecification.html

Creates an example fragment from an expression and code.

```APIDOC
## createExample[T](expression: String, code: => T, asResult: AsResult[T]): Fragments

### Description
Creates an example fragment from an expression and code.

### Method
def createExample[T](expression: String, code: => T, asResult: AsResult[T]): Fragments

### Parameters
- **expression** (String) - Required - The expression string.
- **code** (=> T) - Required - The code to execute.
- **asResult** (AsResult[T]) - Required - The result converter.

### Returns
Fragments.
```

--------------------------------

### PlaySpecification Example Methods

Source: https://www.playframework.com/documentation/3.0.x/api/scala/play/api/test/PlaySpecification.html

Methods for defining examples in PlaySpecification.

```APIDOC
## eg[T](code: => T)(implicit arg0: AsResult[T]): Fragments

### Description
Implicit macro that converts a code block into Fragments for use in examples within a PlaySpecification.

### Method
implicit macro def

### Signature
`def eg[T](code: => T)(implicit arg0: AsResult[T]): Fragments`

### Parameters
- **code** (by-name T) - Required - The code block to be converted into an example.
- **arg0** (AsResult[T]) - Required (implicit) - Provides the result conversion for the example.

### Returns
- **Fragments** - The resulting fragments representing the example.
```

```APIDOC
## makeExample[T](expression: String, code: => T, asResult: AsResult[T]): Fragment

### Description
Protected method that creates a Fragment from an expression string and code block, using the provided AsResult for result conversion.

### Method
def

### Signature
`protected def makeExample[T](expression: String, code: => T, asResult: AsResult[T]): Fragment`

### Parameters
- **expression** (String) - Required - The expression string for the example.
- **code** (by-name T) - Required - The code block to be executed.
- **asResult** (AsResult[T]) - Required - Provides the result conversion for the example.

### Returns
- **Fragment** - The created fragment.
```

--------------------------------

### Parse rows using get[String] and get[Int]

Source: https://www.playframework.com/documentation/3.0.x/ScalaAnorm

Equivalent to the previous example but uses get[String] and get[Int] instead of str and int.

```scala
val result: List[String ~ Int] = SQL("SELECT * FROM Country").
  as((get[String]("name") ~ get[Int]("population")).*)
```

--------------------------------

### GET /xxx

Source: https://www.playframework.com/documentation/3.0.x/api/scala/controllers/Default.html

Returns a 500 InternalServerError response. Example route: GET /xxx controllers.Default.error

```APIDOC
## [GET] /xxx

### Description
Returns a 500 InternalServerError response.

### Method
GET

### Endpoint
/xxx

### Parameters
#### Path Parameters
- **xxx** (string) - Required - The path parameter for the route.

### Response
#### Success Response (500)
- **status** (int) - The HTTP status code 500.

#### Response Example
{
  "status": 500
}
```

--------------------------------

### ExampleSpec using GuiceOneServerPerSuite

Source: https://www.playframework.com/documentation/3.0.x/api/scala/org/scalatestplus/play/ConfiguredServer.html

Example from GuiceOneAppPerSuite's documentation showing how to use GuiceOneServerPerSuite to provide an Application and running server. It overrides fakeApplication() to configure the application and demonstrates accessing the app, implicit Application, and running server endpoint.

```scala
package org.scalatestplus.play.examples.oneserverpersuite

import play.api.test._
import org.scalatestplus.play._
import play.api.{Play, Application}
import play.api.inject.guice._

class ExampleSpec extends PlaySpec with GuiceOneServerPerSuite {

  // Override fakeApplication() if you need a Application with other than non-default parameters.
  def fakeApplication(): Application =
    new GuiceApplicationBuilder().configure("ehcacheplugin" -> "disabled").build()

  "The OneServerPerSuite trait" must {
    "provide an Application" in {
      app.configuration.getOptional[String]("ehcacheplugin") mustBe Some("disabled")
    }
    "make the Application available implicitly" in {
      def getConfig(key: String)(implicit app: Application) = app.configuration.getOptional[String](key)
      getConfig("ehcacheplugin") mustBe Some("disabled")
    }
    "provide an http endpoint" in {
      runningServer.endpoints.httpEndpoint must not be empty
    }
    "provide an actual running server" in {
      import Helpers._
      import java.net._
      val url = new URL("http://localhost:" + port + "/boum")
      val con = url.openConnection().asInstanceOf[HttpURLConnection]
      try con.getResponseCode mustBe 404
      finally con.disconnect()
    }
  }
}

```

--------------------------------

### provideApplication()

Source: https://www.playframework.com/documentation/3.0.x/api/java/play/test/WithApplication.html

Override this method to setup the application to use. Returns the application to use.

```APIDOC
## provideApplication()

### Description
Override this method to setup the application to use.

### Method
protected Application provideApplication()

### Returns
The application to use
```

--------------------------------

### start(): Unit

Source: https://www.playframework.com/documentation/3.0.x/api/scala/play/api/test/TestServer.html

Starts the test server. This method initiates the server so it can accept connections.

```APIDOC
## start(): Unit

### Description
Starts this server.

### Method
start

### Signature
`def start(): Unit`

### Parameters
None

### Return
Unit
```

--------------------------------

### Get lang from request

Source: https://www.playframework.com/documentation/3.0.x/api/scala/play/api/i18n/I18NSupportLowPriorityImplicits%24RequestWithMessagesApi.html

Example for the `lang` method of RequestWithMessagesApi, showing how to get the preferred language of a request.

```scala
implicit val messagesApi: MessagesApi = ...
val lang: Lang = request.lang
```

--------------------------------

### start(): Unit

Source: https://www.playframework.com/documentation/3.0.x/api/scala/play/api/test/TestServer.html

Starts the test server.

```APIDOC
## start(): Unit

### Description
Starts this server.

```

--------------------------------

### Get messages from request

Source: https://www.playframework.com/documentation/3.0.x/api/scala/play/api/i18n/I18NSupportLowPriorityImplicits%24RequestWithMessagesApi.html

Example for the `messages` method of RequestWithMessagesApi, showing how to get a Messages object in the preferred language of the request.

```scala
implicit val messagesApi: MessagesApi = ...
val messageFromRequest: Messages = request.messages("hello.world")
```

--------------------------------

### setupModule(context: SetupContext): Unit

Source: https://www.playframework.com/documentation/3.0.x/api/scala/play/api/libs/json/jackson/PlayJsonMapperModule.html

Sets up the module with the given context.

```APIDOC
## Method: setupModule(context: SetupContext): Unit

### Description
Sets up the module with the given context.

### Parameters
- **context** (SetupContext) - Required - The setup context.

### Returns
Unit - No return value.

### Example
```scala
module.setupModule(context)
```
```

--------------------------------

### Run server with application from context

Source: https://www.playframework.com/documentation/3.0.x/api/scala/play/core/server/Server%24.html

Use this snippet to start a Play server with an application built from a context, using BuiltInComponentsFromContext and additional components. The block receives the port, which defaults to a random ephemeral port unless configured otherwise.

```scala
Server.withApplicationFromContext(ServerConfig(mode = Mode.Prod, port = Some(0))) { context =>
  new BuiltInComponentsFromContext(context) with AssetsComponents with play.filters.HttpFiltersComponents {
    override def router: Router = Router.from {
      case req => assets.versioned("/testassets", req.path)
    }
  }.application
} { withClient(block)(_) }
```

--------------------------------

### Run the documentation server

Source: https://www.playframework.com/documentation/3.0.x/BuildingFromSource

Starts the documentation server locally. After running, browse to http://localhost:9000/@documentation.

```shell
$ cd playframework/documentation
$ sbt run
```

--------------------------------

### Run server with application from context using Server.withApplicationFromContext

Source: https://www.playframework.com/documentation/3.0.x/api/scala/play/core/server/Server%24.html

Use this to run a block of code with a server for an application built from an ApplicationLoader.Context. The block receives the port the application runs on, which defaults to a random ephemeral port unless overridden via the config parameter. This example uses play.api.BuiltInComponentsFromContext with extra components such as AssetsComponents and play.filters.HttpFiltersComponents.

```scala
 Server.withApplicationFromContext(ServerConfig(mode = Mode.Prod, port = Some(0))) { context =>
   new BuiltInComponentsFromContext(context) with AssetsComponents with play.filters.HttpFiltersComponents {
    override def router: Router = Router.from {
      case req => assets.versioned("/testassets", req.path)
    }
  }.application
} { withClient(block)(_) }

```

--------------------------------

### Example usage of RoutingDsl

Source: https://www.playframework.com/documentation/3.0.x/api/java/play/routing/RoutingDsl.html

Example usage of RoutingDsl to build a router with GET and POST routes, including synchronous and asynchronous handlers. The GET route extracts a path parameter and the POST route uses a typed Integer parameter and JSON body.

```java
 import javax.inject.*;
 import play.mvc.*;
 import play.routing.*;
 import play.libs.json.*;
 import play.api.routing.Router;

 public class MyRouterBuilder extends Controller {

   private final RoutingDsl routingDsl;

   \@Inject
   public MyRouterBuilder(RoutingDsl routingDsl) {
     this.routingDsl = routingDsl;
   }

   public Router getRouter() {
     return this.routingDsl

       .GET("/hello/:to").routingTo((req, to) -> ok("Hello " + to))

       .POST("/api/items/:id").routingAsync((Http.Request req, Integer id) -> {
         return Items.save(id,
           Json.fromJson(req.body().asJson(), Item.class)
         ).map(result -> ok("Saved item with id " + id));
       })

       .build();
   }
 }
 
```

--------------------------------

### WithApplication.running

Source: https://www.playframework.com/documentation/3.0.x/api/scala/play/api/test/WithApplication.html

Starts the application and runs the test block.

```APIDOC
## WithApplication.running

### Description
Starts the application and runs the test block.

### Method
running

### Signature
`def running(): Unit`

### Parameters
None

### Returns
Unit
```

--------------------------------

### GET /google

Source: https://www.playframework.com/documentation/3.0.x/api/scala/controllers/Default.html

Returns a 303 SeeOther response. Example route: GET /google controllers.Default.redirect(to = "http://www.google.com")

```APIDOC
## [GET] /google

### Description
Returns a 303 SeeOther response.

### Method
GET

### Endpoint
/google

### Parameters
#### Path Parameters
- **google** (string) - Required - The path parameter for the route.

#### Query Parameters
- **to** (string) - Required - The URL to redirect to.

### Response
#### Success Response (303)
- **status** (int) - The HTTP status code 303.

#### Response Example
{
  "status": 303
}
```

--------------------------------

### def newApplication: Application

Source: https://www.playframework.com/documentation/3.0.x/api/scala/org/scalatestplus/play/components/OneAppPerSuiteWithComponents.html

Creates a new application instance and sets the components. This must be called for components to be properly set up.

```APIDOC
## def newApplication: Application

### Description
Creates a new application instance and sets the components. This must be called for components to be properly set up.

### Returns
- **Application** - New application instance.

### Definition Classes
WithApplicationComponents
```

--------------------------------

### blockExample(d: String): BlockExample

Source: https://www.playframework.com/documentation/3.0.x/api/scala/play/api/test/PlaySpecification.html

Implicitly converts a string to a BlockExample for defining block examples.

```APIDOC
## blockExample(d: String): BlockExample

### Description
Implicitly converts a string to a BlockExample for defining block examples.

### Method
implicit def blockExample(d: String): BlockExample

### Parameters
- **d** (String) - Required - The example description.

### Returns
BlockExample instance.
```

--------------------------------

### Set a basic sbt setting with :=

Source: https://www.playframework.com/documentation/3.0.x/sbtSettings

Use the := operator in build.sbt to assign a value to a setting. This example sets the confDirectory setting to "myConfFolder".

```sbt
confDirectory := "myConfFolder"
```

--------------------------------

### Define a PlayRunHook to run grunt dist before startup (Grunt.scala)

Source: https://www.playframework.com/documentation/3.0.x/sbtCookbook

Create a Scala object in the project/ directory that extends PlayRunHook. The beforeStarted method runs 'grunt dist' in the base directory before the Play application starts. This is the initial version without watch support.

```scala
import play.sbt.PlayRunHook
import sbt._
import scala.sys.process.Process

object Grunt {
  def apply(base: File): PlayRunHook = {

    object GruntProcess extends PlayRunHook {

      override def beforeStarted(): Unit = {
        Process("grunt dist", base).run
      }
    }

    GruntProcess
  }
}
```

--------------------------------

### ConfiguredApp example with GuiceOneAppPerSuite

Source: https://www.playframework.com/documentation/3.0.x/api/scala/org/scalatestplus/play/ConfiguredApp.html

Example from GuiceOneAppPerSuite's documentation showing how to use ConfiguredApp with a configured Application. It overrides fakeApplication to provide a custom Application and verifies configuration values both directly and implicitly.

```scala
package org.scalatestplus.play.examples.oneapppersuite

import org.scalatestplus.play._
import play.api.{Play, Application}
import play.api.inject.guice._

class ExampleSpec extends PlaySpec with GuiceOneAppPerSuite {

  // Override app if you need an Application with other than non-default parameters.
  def fakeApplication(): Application =
    new GuiceApplicationBuilder().configure(Map("ehcacheplugin" -> "disabled")).build()

  "The GuiceOneAppPerSuite trait" must {
    "provide a FakeApplication" in {
      app.configuration.getOptional[String]("ehcacheplugin") mustBe Some("disabled")
    }
    "make the FakeApplication available implicitly" in {
      def getConfig(key: String)(implicit app: Application) = app.configuration.getOptional[String](key)
      getConfig("ehcacheplugin") mustBe Some("disabled")
    }
  }
}

```

--------------------------------

### sird DSL usage example

Source: https://www.playframework.com/documentation/3.0.x/api/scala/play/api/routing/sird/index.html

Example of using the sird DSL to define routes for GET and PUT requests with path extraction and type binding.

```APIDOC
## sird DSL usage example

### Description
Example of using the sird DSL to define routes for GET and PUT requests with path extraction and type binding.

### Code Example
```scala
import play.api.routing.sird._
import play.api.routing._
import play.api.mvc._

Router.from {
  case GET(p"/hello/$to") => Action {
    Results.Ok(s"Hello $to")
  }
  case PUT(p"/api/items/${int(id)}") => Action.async { req =>
    Items.save(id, req.body.json.as[Item]).map { _ =>
      Results.Ok(s"Saved item $id")
    }
  }
}
```
```

--------------------------------

### Explicitly start application in JUnit setUp

Source: https://www.playframework.com/documentation/3.0.x/Migration23

Previously required to explicitly start an application in JUnit tests. With the new @Before method in superclasses, this is no longer needed.

```java
@Before
public void setUp() {
    start();
}
```

--------------------------------

### Example usage of sird

Source: https://www.playframework.com/documentation/3.0.x/api/scala/play/api/routing/JavaScriptReverseRoute.html

Example usage of the Play String Interpolating Routing DSL (sird) with Router.from, showing GET and PUT routes with path extractors.

```scala
import play.api.routing.sird._
import play.api.routing._
import play.api.mvc._

Router.from {
  case GET(p"/hello/$to") => Action {
    Results.Ok(s"Hello $to")
  }
  case PUT(p"/api/items/${int(id)}") => Action.async { req =>
    Items.save(id, req.body.json.as[Item]).map { _ =>
      Results.Ok(s"Saved item $id")
    }
  }
}
```

--------------------------------

### Routes file example

Source: https://www.playframework.com/documentation/3.0.x/ScalaCompileTimeDependencyInjection

Example routes file that generates a router with constructor parameters for each controller and included router.

```routes
GET        /                    controllers.Application.index
GET        /foo                 controllers.Application.foo
->         /bar                 bar.Routes
GET        /assets/*file        _root_.controllers.Assets.at(path = "/public", file)
```

--------------------------------

### wsCall example

Source: https://www.playframework.com/documentation/3.0.x/api/scala/org/scalatestplus/play/WsScalaTestClient.html

Constructs a WS request for the given reverse route and returns a WSRequest. The example shows calling the route and then invoking get() to perform the request.

```scala
wsCall(controllers.routes.Application.index()).get()
```

--------------------------------

### keys example

Source: https://www.playframework.com/documentation/3.0.x/api/scala/play/api/Configuration.html

Shows how to retrieve the available keys from a configuration using the keys method.

```scala
val configuration = Configuration.load()
val keys = configuration.keys
```

--------------------------------

### Start Play with config.file

Source: https://www.playframework.com/documentation/3.0.x/ApplicationSecret

Command to start a Play application with a specific configuration file, typically used in production.

```bash
/path/to/yourapp/bin/yourapp -Dconfig.file=/path/to/production.conf
```

--------------------------------

### Using AsyncCacheApi

Source: https://www.playframework.com/documentation/3.0.x/JavaCache

Example of using AsyncCacheApi to set and get a value asynchronously.

```java
public CompletionStage<Result> get(String key) {
    return asyncCache.get(key).thenCompose(value -> {
        if (value == null) {
            return computeValueAsync(key).thenCompose(newValue -> {
                return asyncCache.set(key, newValue).thenApply(v -> ok(newValue));
            });
        } else {
            return CompletableFuture.completedFuture(ok(value));
        }
    });
}
```

--------------------------------

### start(Application)

Source: https://www.playframework.com/documentation/3.0.x/api/java/play/test/Helpers.html

Starts a new application.

```APIDOC
## start(Application)

### Description
Starts a new application.

### Method
start

### Parameters
- `application` (Application) - Required - the application to start.
```

--------------------------------

### Using SyncCacheApi

Source: https://www.playframework.com/documentation/3.0.x/JavaCache

Example of using SyncCacheApi to set and get a value synchronously.

```java
public Result get(String key) {
    String value = cache.get(key);
    if (value == null) {
        value = computeValue(key);
        cache.set(key, value);
    }
    return ok(value);
}
```

--------------------------------

### Start Netty server with custom ServerConfig

Source: https://www.playframework.com/documentation/3.0.x/ScalaEmbeddingPlayNetty

Start a Netty server with a custom `ServerConfig` to set the port and address. This example configures the server to listen on port 19000 at 127.0.0.1.

```scala
import play.api.mvc._
import play.api.routing.sird._
import play.core.server._

val server = NettyServer.fromRouterWithComponents(
  ServerConfig(
    port = Some(19000),
    address = "127.0.0.1"
  )
) { components =>
  import components.{ defaultActionBuilder => Action }
  {
    case GET(p"/hello/$to") =>
      Action {
        Results.Ok(s"Hello $to")
      }
  }
}
```

--------------------------------

### Extracting Mock Client Setup

Source: https://www.playframework.com/documentation/3.0.x/ScalaTestingWebServiceClients

Shows the initial imports for creating a helper method to encapsulate mock client setup.

```scala
import play.api.mvc._
import play.api.routing.sird._
import play.core.server.Server
import play.api.test._
```

--------------------------------

### GET /databases/{name}/connection

Source: https://www.playframework.com/documentation/3.0.x/api/scala/play/api/db/index.html

Example of retrieving a JDBC connection from the 'customers' datasource.

```APIDOC
## [GET] /databases/{name}/connection

### Description
Retrieves a JDBC connection from the specified datasource.

### Method
GET

### Endpoint
/databases/{name}/connection

### Parameters
#### Path Parameters
- **name** (string) - Required - The name of the datasource.

### Response
#### Success Response (200)
- **connection** (Connection) - The JDBC connection.

#### Response Example
```
val conn = db.getConnection("customers")
```
```

--------------------------------

### fromApplication

Source: https://www.playframework.com/documentation/3.0.x/api/scala/play/core/server/NettyServer%24.html

Creates a Netty server from the given application and server configuration.

```APIDOC
## fromApplication(application: api.Application, config: ServerConfig = ServerConfig()): NettyServer

### Description
Create a Netty server from the given application and server configuration.

### Method
fromApplication

### Parameters
- **application** (api.Application) - Required - The application.
- **config** (ServerConfig) - Optional - The server configuration. Defaults to ServerConfig().

### Returns
A started Netty server, serving the application.
```

--------------------------------

### Start embedded Pekko HTTP server

Source: https://www.playframework.com/documentation/3.0.x/ScalaEmbeddingPlayPekkoHttp

Starts an embedded Pekko HTTP server on port 19000 at 127.0.0.1 using the application built from components. This is the minimal setup without logging dependencies.

```scala
val server = PekkoHttpServer.fromApplication(
  components.application,
  ServerConfig(
    port = Some(19000),
    address = "127.0.0.1"
  )
)
```

--------------------------------

### sbt new - Interactive project creation

Source: https://www.playframework.com/documentation/3.0.x/NewApplication

Run this command to start the interactive sbt new process. Then choose playframework/play-scala-seed.g8 for Scala or playframework/play-java-seed.g8 for Java, and respond to prompts. After creation, run sbt run and visit http://localhost:9000/.

```bash
sbt new
```

--------------------------------

### Action.async example with ws.url

Source: https://www.playframework.com/documentation/3.0.x/api/scala/play/api/mvc/ActionBuilder%24%24IgnoringBody.html

Example of using Action.async to construct an action that returns a Future[Result]. It performs an HTTP GET request to 'http://www.playframework.com' and returns Ok if the status is 200, otherwise NotFound.

```scala
val hello = Action.async {
  ws.url("http://www.playframework.com").get().map { r =>
    if (r.status == 200) Ok("The website is up") else NotFound("The website is down")
  }
}
```

--------------------------------

### Constructor: Context(Environment environment, Map<String,Object> initialSettings)

Source: https://www.playframework.com/documentation/3.0.x/api/java/play/ApplicationLoader.Context.html

Creates a new Context with the given environment and initial settings.

```APIDOC
## Constructor: Context(Environment environment, Map<String,Object> initialSettings)

### Description
Creates a new Context with the given environment and initial settings.

### Parameters
- `environment` (Environment) - Required - The application environment.
- `initialSettings` (Map<String,Object>) - Required - The initial settings. These settings are merged with the settings from the loaded configuration files, and together form the initialConfiguration provided by the context. It is intended for use in dev mode, to allow the build system to pass additional configuration into the application.

```
Tokens:
Raw