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:

.. code-block:: php

   use function kickback;

   $responder = kickback();  
   
   // same as \Lacebox\Sole\Http\ShoeResponder::getInstance()


.. container:: note
    
    **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.)

.. code-block:: php

   // 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:

.. code-block:: php

   $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:

.. code-block:: php

   // 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:

.. code-block:: php

   $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:

.. code-block:: php

   // 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:

.. code-block:: php

   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);
       }
   }