Helper Functions
================

LacePHP provides a set of global helpers to simplify everyday tasks, from reading config, handling requests and responses, logging, dispatching events, working with dates, rendering views and more. They let you write concise, readable code without boilerplate.

Why Helpers Matter
------------------

- **Convenience**: call `config('database.mysql.host')` instead of writing your own loader.  
- **Consistency**: everyone uses the same functions, so your team adopts a uniform style.  
- **Clarity**: helper names reveal intent at a glance (e.g. `sole_request()->input('id')` vs `$_GET['id']`).  

Configuration & Environment
~~~~~~~~~~~~~~~~~~~~~~~~~~~~

- **config(string $path = null, $default = null)**  
  Fetch the merged configuration array or a single value via dot-notation.  
  .. code-block:: php

     // entire config
     $all = config();

     // specific value, with default
     $host = config('database.mysql.host', '127.0.0.1');

- **config_get(string $path, $default = null)**  
  Alias of `config()`.  

- **env(string $key, $default = null)**  
  Read an environment variable from your `.env` file.  
  .. code-block:: php

     $debug = env('APP_DEBUG', false);

Request & Response
~~~~~~~~~~~~~~~~~~

- **sole_request(): ShoeRequest**  
  Access the singleton request wrapper (sanitised GET/POST/JSON, headers, method, URI).  
  .. code-block:: php

     $id    = sole_request()->input('id');
     $route = sole_request()->uri();

- **kickback(): ShoeResponder**  
  Access the singleton response helper for JSON, HTML or error responses.  
  .. code-block:: php

     return kickback()->json(['success'=>true], 201);

- **response(array $data = [], int $code = 200): void**  
  Shortcut to send a JSON response and status code.  
  .. code-block:: php

     response(['message'=>'OK'], 200);

URL & Assets
~~~~~~~~~~~~

- **shoe_base_url(string $path = ''): string**  
  Build an absolute URL based on `config('base_url')` or auto-detect host/scheme.  
  .. code-block:: php

     $apiRoot = shoe_base_url('api/v1/users');

- **shoe_asset(string $publicPath): string**  
  Generate a URL to a file under `public/`, e.g. CSS or JS.  
  .. code-block:: php

     <link href="<?= shoe_asset('css/app.css') ?>" rel="stylesheet">

Logging & Errors
~~~~~~~~~~~~~~~~

- **log_error(string $type, string $message): void**  
  Append error entries (404, 500, etc.) to your log file when enabled in `config('logging')`.  
  .. code-block:: php

     log_error('500', "Database connection failed");

Events & Scheduling
~~~~~~~~~~~~~~~~~~~

- **fire(string $eventName, $payload = null): void**  
  Dispatch a named event.  
- **on(string $eventName, callable $listener): void**  
  Register a listener for an event.  
  .. code-block:: php

     on('user.registered', fn($user)=>sendWelcomeEmail($user));
     fire('user.registered', $newUser);

- **schedule(): AgletKernel**  
  Get the scheduler to register code-based cron tasks (via `schedule()->everyMinute(...);`).  

Date, Time & Version
~~~~~~~~~~~~~~~~~~~~

- **lace_now(): \DateTime**  
  Current DateTime in your app’s timezone (`config('boot.timezone')`).  
- **lace_now_str(string $format = 'Y-m-d H:i:s'): string**  
  Formatted timestamp string.  
  .. code-block:: php

     echo lace_now_str('Y-m-d');

- **lace_version(): string**  
  Returns the framework version constant.  

Autoloading
~~~~~~~~~~~

- **enable_lace_autoloading(): void**  
  Register the PSR-4 autoloader for `Lacebox\`, `Weave\`, `Shoebox\`, and `weave/Plugins`.  
  Call this at bootstrap to avoid manual `require` calls.

Views & Templating
~~~~~~~~~~~~~~~~~~

- **view(string $template, array $data = []): string**  
  Render a PHP template under `weave/Views/` (fallback to `shoebox/views/`) into HTML.  
  .. code-block:: php

     echo view('emails.welcome', ['user'=>$user]);

Best Practices
--------------
- **Group usage**: import multiple helpers at top of your file to keep code DRY.  
- **Sanitise inputs**: use `sole_request()`’s methods instead of raw `$_GET` / `$_POST`.  
- **Centralise config**: always use `config()` so defaults and environment overrides are applied.  
- **Avoid global state**: prefer returning from `kickback()` rather than echoing directly where possible.

.. warning::

   - Overusing helpers can hide logic—name your helpers clearly and document them.  
   - `log_error()` will create directories if missing—ensure correct permissions on production.  
   - `view()` will throw if template is missing—catch exceptions or verify file existence in advance.  
   - `enable_lace_autoloading()` must run before any class resolution—call it at the very start of your bootstrap.

|
|