The Response Object

All controller methods in Rhapsody must return an instance of the Rhapsody\Core\Response object (or a class that extends it, like RedirectResponse). This object represents the complete HTTP response that will be sent back to the browser, including the content, status code, and headers.

---

Creating Responses

While you can create a Response object manually, it's usually more convenient to use the helper methods provided by the BaseController.

Returning a View

The view() helper creates a Response object, sets its content to the rendered Twig template, and sets the status code to 200 (OK).

// In a controller
public function home(): Response
{
    return $this->view('home/welcome.twig', ['name' => 'John']);
}

Returning JSON

The json() helper creates a Response object, JSON-encodes your data, and automatically sets the Content-Type header to application/json.

// In an API controller
public function getUser(string $id): Response
{
    $user = $this->userModel->findById($id);
    
    if (!$user) {
        return $this->json(['error' => 'User not found'], 404);
    }

    return $this->json($user);
}

Pair this with Request::wantsJson() to let a single route serve both a full page and an AJAX response — see AJAX Pagination.

Redirecting Users

To redirect a user to another page, Rhapsody uses the Rhapsody\Core\RedirectResponse class. The easiest way to create one is with the global redirect() helper function.

Basic Redirects

public function store(Request $request): Response
{
    // ... save data ...
    return redirect('/users');
}

Redirects with Flash Messages

Chain the with() method to send a flash message for the next request.

return redirect('/users/' . $id)
    ->with('success', 'Profile updated!');

This message can be displayed in Twig using the global flash variable.

---

Manually Building a Response

If you need full control, you can create a Response instance and set its properties directly:

public function custom(): Response
{
    $response = new Response();
    $response->setStatusCode(201);
    $response->setHeader('X-Custom', 'Hello');
    $response->setContent('
Created
');
    return $response;
}

Redirect Responses

Rhapsody provides a RedirectResponse class for handling HTTP redirects. The easiest way to create one is with the global redirect() helper function.

Basic Redirects

public function store(Request $request): Response
    {
        // ... save data to the database ...
        return redirect('/users');
    }

Redirects with Flash Messages

Chain the with() method to send a flash message for the next request:

return redirect('/users/' . $id)
        ->with('success', 'Profile updated successfully!');

The RedirectResponse::send() method automatically saves the session before redirecting, ensuring flash messages are preserved.

Retrieving Response Data (for Testing or Debugging)

The Response object provides getter methods to inspect the response:

• getContent() – returns the response body as a string.
• getStatusCode() – returns the HTTP status code.
• getHeaders() – returns an associative array of headers.

These are especially useful when writing unit tests with PHPUnit.

$response = $this->call('GET', '/about');
$this->assertEquals(200, $response->getStatusCode());
$this->assertStringContainsString('About Us', $response->getContent());

---

Sending the Response

The send() method is called automatically by the framework to output the response. You rarely need to call it yourself, but it’s available if you need to manually flush the response.

It sets the status code, sends all headers, and prints the content.