Using ShoeResponder

When your application handles a request, you need to send back a response: HTML pages, JSON data, plain text, or error messages. LacePHP gives you a simple, consistent response API via ShoeResponder.

Use the helper function kickback() to get the shared instance:

use function kickback;

$responder = kickback();

// same as \Lacebox\Sole\Http\ShoeResponder::getInstance()

Tip: We have one responder instance which means all headers, status codes, and payload data go through the same object. This keeps your output predictable and easy to test.

HTML and Plain Text

  • HTML: for rendering full pages or snippets

  • Text: for simple plain-text responses (debug, CLI output, etc.)

// In a controller or route closure
return kickback()->html('<h1>Welcome to LacePHP</h1>');

// Return plain text
return kickback()->text('Operation completed successfully.');

Internally, these methods:

  1. Set the Content-Type header

  2. Send the HTTP status code if headers aren’t already sent

  3. Return your string directly

JSON Responses

Use json() to return data as JSON. LacePHP will set the correct header and encode your payload:

$data = ['user' => ['id'=>1, 'name'=>'Alice']];
return kickback()->json($data, 200, ['X-Custom' => 'Value']);

  • 200 is the status code

  • The third parameter lets you add extra headers

Error Responses

For common HTTP errors, ShoeResponder chooses HTML or JSON based on the client’s Accept header:

// 404 Not Found
return kickback()->notFound('Page not found.');

// 401 Unauthorized
return kickback()->unauthorized('Please log in.');

// 500 Server Error
return kickback()->serverError('Unexpected error occurred.');

Behind the scenes, these methods call wantsHtml() to detect if the client prefers HTML. If so, they render an error template; otherwise they return JSON.

Custom Error Pages

You can supply your own HTML templates in weave/Views/errors/404.html and 500.html. ShoeResponder’s renderErrorPage() will:

  1. Look up your path in config(‘errors.templates’)

  2. Fallback to shoebox/views/errors/{code}.html.php

  3. If missing, simply output the error message

Headers & Status Codes

ShoeResponder tracks headers internally, so you can inspect or modify them before sending:

$responder = kickback();
$responder->setHeader('X-Trace-ID', session_id());
$current = $responder->getHeaders();
// e.g. ['Content-Type'=>'application/json', 'X-Trace-ID'=>'abc123']

Payload Data & Recording

If you integrate LacePHP’s Recorder, you can capture full request/response cycles. ShoeResponder provides:

  • withData(array $data) to store a payload for later recording

  • toArray() to export status, headers, and data

Use it like this:

// Prepare payload and record it later
return kickback()
    ->withData(['result'=>'ok', 'time'=>microtime(true)])
    ->json(['result'=>'ok']);

Putting It All Together

Example in a controller method:

class ArticleController
{
    public function show($id)
    {
        $article = Article::find($id);

        if (! $article) {
            // Record 404 page view then send response
            return kickback()->notFound("Article {$id} not found.");
        }

        // Safe to render HTML or JSON
        if (sole_request()->header('Accept') === 'application/json') {
            return kickback()->json(['article' => $article]);
        }

        $html = view('article/show', ['article' => $article]);
        return kickback()->html($html);
    }
}