Using ShoeRequest
=================

LacePHP provides a single, sanitized HTTP request object called **ShoeRequest**. It wraps PHP superglobals, strips out unsafe data, and gives you easy methods to read GET, POST, JSON and file inputs—all in one place.

Helper Function
---------------

To access the request anywhere in your app, use the `sole_request()` helper:

.. code-block:: php

   use function sole_request;

   $req = sole_request(); 
   
   // same as \Lacebox\Sole\Http\ShoeRequest::grab()


.. container:: note
    
    **Tip:** We keep one immutable instance of ShoeRequest to ensure that every part of your code sees the *same* cleaned-up inputs and that session/CSRF state is initialized just once.

Reading Input Values
--------------------

Use `input()` to fetch a parameter from JSON body, POST or GET (in that order):

.. code-block:: php

   // URL: /search?q=lacephp
   // JSON body: { "q": "php" }
   $term = sole_request()->input('q', 'default');
   
   // → returns "php" if JSON present, otherwise GET “lacephp”, or “default”

To get *all* sanitized inputs at once:

.. code-block:: php

   $all = sole_request()->all();  
   // e.g. ['q'=>'lacephp', 'page'=>2, ...]

And to restrict to only certain keys:

.. code-block:: php

   $data = sole_request()->only(['email', 'name']);

Or to drop sensitive keys before logging:

.. code-block:: php

   $safe = sole_request()->except(['password', 'credit_card']);

Headers, Server Data & Files
----------------------------

Read HTTP headers with `header()` and raw server values with `server()`:

.. code-block:: php

   $userAgent = sole_request()->header('User-Agent');
   $uri       = sole_request()->server('REQUEST_URI');

Uploaded files are available via:

.. code-block:: php

   $files = sole_request()->files();
   
   // each entry sanitized to include name, type, tmp_name, error, size

Cross-Site Request Forgery (CSRF)
---------------------------------

ShoeRequest automatically generates a secure token stored in `$_SESSION['_csrf_token']`.  

- To add the hidden field in an HTML form:

  .. code-block:: html

     <form method="POST" action="/submit">
       <?= sole_request()->csrfField() ?>
       <input name="email" />
       <button>Send</button>
     </form>

- To validate the token in your controller or route:

  .. code-block:: php

     sole_request()->validateCsrf();
     // throws RuntimeException on mismatch

.. warning::

   Always call `validateCsrf()` before processing any POST, PUT, PATCH or DELETE action.  
   This ensures attackers cannot forge requests on behalf of your users.

Why Sanitization Matters
------------------------

- **strip_tags** removes any HTML or script tags to prevent XSS.  
- **trim** and **null-byte stripping** avoid hidden characters and malformed inputs.  
- **Key sanitization** restricts keys to letters, numbers and underscores, preventing header injection.

Putting It All Together
-----------------------

Example in a controller:

.. code-block:: php

   class UserController
   {
       public function store()
       {
           $req = sole_request();
           $req->validateCsrf();

           // Only allow these fields
           $data = $req->only(['name', 'email', 'password']);

           // Now safe to pass $data to your model or validator
           User::create($data);

           return 'User created!';
       }
   }

That’s it! With ShoeRequest you get a clean, consistent interface to every part of the HTTP request—making your code safer, clearer and easier to test.

|
|