Shoebox
=======

The **shoebox/** directory is your application’s writable “output box.” It holds runtime data, generated files, and system assets; separating them from your source code so you never accidentally commit cache, logs or migrations to version control.

Directory Structure
-------------------

.. code-block:: text

    ├── shoebox/              
    │   ├── cache/         # Cached responses, compiled templates, etc.
    │   ├── logs/          # Framework-level logs (errors, access, metrics)
    │   ├── metrics/       # Request counts, timing data for each route
    │   ├── migrations/    # Generated migrations + JSON tracker file
    │   ├── outsole/       # Static assets: API docs, Swagger UI, CSS/JS
    │   └── views/         # Default error pages and fallback templates

cache/
^^^^^^^

Stores on-disk cache of GET responses (used by **ShoeCacheKnots**).

- Speeds up repeat requests in development or low-traffic production.  
- You can clear it with `php lace cache:clear` or delete the folder.

logs/  
^^^^^^

Appends timestamped entries (404, 500, custom errors) via `log_error()`.

- Inspect `shoebox/logs/lace.log` when something goes wrong.  
- Rotate or archive periodically in production.

metrics/  
^^^^^^^^^^

Accumulates per-route hit counts, total duration, averages.  

- View via `lace/metrics` endpoint (see below).  
- Helps you spot slow or popular endpoints.

migrations/
^^^^^^^^^^^^

Holds your migration PHP files plus `migrations.json` tracker.

- Run `php lace cobble create AddUsersTable`.  
- Run `php lace cobble run`, it applies new migrations and updates the JSON file.

outsole/  
^^^^^^^^^

Public-facing assets for documentation and UI:

- **docs/**: Swagger UI JavaScript/CSS  
- **openapi.json**: generated OpenAPI spec (`php lace route docs`)  
- You link to them via `shoe_asset('outsole/swagger-ui/swagger-ui.css')`.

views/
^^^^^^^

Default HTML templates for errors (404, 500) and any core-provided pages. 

- You can override by placing `weave/Views/errors/404.php` in your app.

Out-of-the-Box Service Endpoints
---------------------------------

LacePHP ships four convenient URL shortcuts under `lace.json`:

.. code-block:: json

    "endpoints": {
      "docs":      "lace/docs",
      "health":    "lace/health",
      "dashboard": "lace/dashboard",
      "metrics":   "lace/metrics",
      "guarded":   false
    }

- **lace/docs**  
  Interactive API documentation (Swagger UI) powered by `shoebox/outsole`.  
- **lace/health**  
  Quick health check—verifies database, cache connectivity, required services.  
- **lace/dashboard**  
  Displays PHP version, LacePHP version, links to user guide and settings.  
- **lace/metrics**  
  Shows per-route hit counts, total and average durations from `shoebox/metrics/`.

.. note::

   You should **rename** or **guard** these endpoints in production to avoid exposing internal info:
   1. Change the paths in `lace.json`  
   2. Or wrap them in IP restrictions (see next section).

IP Restrictions (Whitelist / Blacklist)
---------------------------------------

LacePHP can automatically block or allow requests by IP, both globally and per-route. Configure in `lace.json`:

.. code-block:: json

    "ip": {
      "whitelist": ["127.0.0.1","::1"],
      "blacklist": [],
      "routes": {
        "/admin":  { "whitelist": ["10.0.0.0/24"] },
        "/public": { "blacklist": ["0.0.0.0/0"] }
      }
    }

- **Global**  
  - `whitelist`: only these IPs may access the app.  
  - `blacklist`: these IPs are blocked outright.  

- **Per-route overrides**  
  - Under `"routes"`, specify a sub-object keyed by path.  
  - That path’s whitelist or blacklist takes precedence for matching IPs.

.. warning::

   - IP restrictions help secure admin or internal endpoints (e.g. `lace/dashboard`).  
   - Always test CIDR ranges and localhost entries (`127.0.0.1`, `::1`) before deploying.

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

1. **Generate migrations** → `php lace cobble create CreatePostsTable`  
2. **Run migrations** → `php lace cobble run`  
3. **Serve docs** → browse to `/lace/docs` (or your custom path)  
4. **Check health** → GET `/lace/health`  
5. **Monitor metrics** → GET `/lace/metrics`  
6. **Secure**  
   - Change `lace.json` endpoints to non-default values  
   - Add IP whitelist for production  

By leveraging the **shoebox/** directory and built-in endpoints, you get a complete feedback loop—migrations, logging, performance metrics and docs—without extra setup.

|
|