When you first start with Play, it’s incredibly tempting to treat your controllers like a dumping ground. You have a request coming in, you need to do some work, and you need to send a response back. It feels natural to just write a big method that does everything from validating a session token to calling the database and formatting the JSON. I've seen this happen in countless codebases, and it always leads to the same place: the "Fat Controller."

The temptation of the monolithic handler

Let's say we're building a system to manage a library's book inventory. You might write a controller method to handle updating a book's status like this:

class BookController @Inject()(cc: ControllerComponents, bookRepo: BookRepository) extends AbstractController(cc) {
  def updateStatus(bookId: Long) = Action { implicit request =>
    // 1. Manual Authentication
    val user = request.session.get("user_id")
    if (user.isEmpty) {
      BadRequest("You must be logged in")
    } else {
      // 2. Manual Authorization
      val isAdmin = bookRepo.checkAdminStatus(user.get)
      if (!isAdmin) {
        Forbidden("Only admins can change book status")
      } else {
        // 3. Business Logic
        bookRepo.markAsAvailable(bookId)
        Ok("Book updated successfully")
      }
    }
  }
}

On the surface, this works. It's explicit. But as soon as you add a deleteBook or addBook method, you'll realize you're copy-pasting those first ten lines of authentication and authorization logic everywhere. You've coupled your HTTP handling (the session) with your business rules (admin status) and your response logic. If the way we handle sessions changes, you're hunting through twenty different methods to update the logic.

Decoupling with Action Composition

The "Play way" to solve this is to stop thinking of the controller method as the starting point and start thinking about Actions as a pipeline. In Play, an Action isn't just the block of code that runs; it's a wrapper that can be composed. I prefer to move the cross-cutting concerns—like "Is this person an admin?"—into a custom ActionBuilder.

By creating a specialized Action, we can extract the user and the permission check before the controller method is even invoked. This lets the controller focus on exactly one thing: coordinating the request to the service layer.

// An ActionBuilder that ensures the user is an Admin
class AdminAction @Inject()(val parser: BodyParsers.Default, bookRepo: BookRepository) 
  extends ActionBuilder[AdminRequest, AnyContent] {
  
  override def invokeBlock[A](request: Request[A], block: (AdminRequest, A) => Future[Result]) = {
    request.session.get("user_id") match {
      case Some(userId) if bookRepo.checkAdminStatus(userId) => 
        block(new AdminRequest(request, userId), request.body)
      case Some(_) => 
        Future.successful(Forbidden("Admin access required"))
      case None => 
        Future.successful(Unauthorized("Please log in")))
    }
  }
}

case class AdminRequest(request: Request[_], userId: String) extends WrappedRequest[AnyContent]

Now, look at how the controller transforms. We inject our AdminAction and use it instead of the generic Action:

class BookController @Inject()(cc: ControllerComponents, bookRepo: BookRepository, adminAction: AdminAction) 
  extends AbstractController(cc) {
  
  def updateStatus(bookId: Long) = adminAction { implicit request =>
    bookRepo.markAsAvailable(bookId)
    Ok("Book updated successfully")
  }
}

Trading simplicity for scalability

You might look at this and think, "I just wrote a whole new class and a case class just to save five lines of code in my controller." And for a tiny prototype, you're right—it's overkill. But the trade-off here is about the cognitive load of the developer. When I open BookController now, I don't have to parse the authentication logic to understand what updateStatus actually does. I see adminAction and I know exactly who is allowed in.

Furthermore, this makes testing significantly easier. You can test the AdminAction in isolation to ensure your security logic is bulletproof, and then you can test your controller methods by mocking the action or providing a dummy AdminRequest. You've moved from a world where your security is a series of if/else blocks scattered across your app to a world where security is a declarative part of your route handling.

📋 Practical Task

Build a Permission-Based Action for a "Premium" Content Gate

You are building a digital magazine. Some articles are free, but others are restricted to "Premium" subscribers. Currently, the check is being done manually inside every single controller method.

Your Task: Create a custom PremiumAction (extending ActionBuilder) that:

1. Checks the request session for a "subscription_level" key.
2. If the value is "premium", it allows the request to proceed to the controller block.
3. If the value is "basic" or missing, it returns a PaymentRequired (402) result with the body "Please upgrade your account to view this content."

Once the Action is built, implement a MagazineController with a method readPremiumArticle(id: String) that uses this PremiumAction to protect the content. The method itself should simply return an Ok result with the text "Welcome to the inner circle!".