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

├── 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:

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

"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.