Getting Started with LacePHP

Follow these quick steps to set up your LacePHP project. We’ll explain why each piece matters and show you examples you can try right away.

Configuration via lace.json

Inside your project root you’ll find lace.json.example. Copy or rename it:

mv lace.json.example lace.json

Open lace.json, this file controls core framework settings:

Explanation of Key Settings in lace.json

Setting	Description
lace_env	The environment name (e.g., local, staging, or production).
lace_config	Which PHP config file under config/ to load (e.g., config_local).
brand_name	Display name for your application in default templates or emails.
lace_version	Your app’s version string.
routing.auto_discover	If true, LacePHP will scan the listed route_paths for route files automatically.
routing.route_paths	An array of folders where LacePHP looks for route definitions.
views_path	Path to your template files (default: shoebox/views).
errors.show_debug	If true, show detailed error messages and stack traces.
errors.templates.404	File to use for 404 “Not Found” error pages.
errors.templates.500	File to use for 500 “Server Error” pages.
metrics.enabled	If true, collect and expose request timing metrics.
paths.vendor	Location of the Composer vendor/ directory.
cli.allow_composer	If true, allow running Composer commands via the lace CLI.
cli.ai_enabled	Enable or disable the AI scaffolding and buddy features.
plugins.auto_discover_folder	Automatically load plugins from weave/Plugins.
plugins.auto_discover_composer	Also load plugins installed via Composer.
graphql.enabled	Enable built-in GraphQL support.
graphql.endpoint	URL path for the GraphQL endpoint.
graphql.schemaClass	Fully-qualified class name of your GraphQL schema.
cache.enabled	If true, enable response caching.
cache.ttl	Time-to-live (in seconds) for cached responses.
cache.path	Directory where cache files are stored.
ip.whitelist	List of client IPs always allowed to access the app.
ip.blacklist	List of client IPs always denied.
ip.routes	Per-route whitelist/blacklist overrides (by URL path).
endpoints.docs	Path to the built-in documentation UI.
endpoints.health	Path to the health check endpoint.
endpoints.dashboard	Path to the metrics dashboard.
endpoints.metrics	Path to the raw metrics JSON output.
endpoints.guarded	If true, built-in endpoints require authentication.

Environment Variables with .env

Sensitive values—database credentials, API keys, secret tokens—go into your .env file. Rename or copy from env.example:

cp env.example .env

Why use .env? - Keeps secrets out of version control. - Easily override settings per environment. - Loaded automatically at boot.

Application Settings in config/lace.php

Further customization lives in PHP config files under config/. Open config/lace.php for customisation.

config/lace.php Overview

Section	Description
boot.timezone	The default PHP timezone (e.g., Africa/Lagos).
boot.debug	If true, display debug information on errors.
boot.show_blisters	If true, show detailed error pages in development.
database.driver	Which database driver to use (sqlite, mysql or pgsql).
database.sqlite.database_file	Path to the SQLite database file.
database.mysql.host	MySQL server hostname.
database.mysql.port	MySQL server port (default 3306).
database.mysql.database	Name of the MySQL database.
database.mysql.username	Username for MySQL authentication.
database.mysql.password	Password for MySQL authentication.
database.mysql.charset	Character set for MySQL connections.
database.mysql.collation	Collation setting for MySQL.
logging.enabled	If true, write log entries to file.
logging.levels	HTTP status codes (e.g., 404, 500) that should be logged.
logging.path	File path where logs are written.
sole_version	Internal version number of the LacePHP core.
base_url	Base URL used when generating links.
grip_level	Verbosity level for internal error handling and messages.
paths.vendor	Location of the Composer vendor/ directory.
auth.guard	Authentication method (token, etc.).
auth.tokens	Array of secret keys used for token-based authentication.

Starting the Built-In Server for Development

You can spin up a development server in seconds. From your project root:

cd /path/to/LacePHP
php lace tread

You’ll see a message like:

Development Server (http://127.0.0.1:6916) started

Point your browser there and LacePHP is live!

Public Folder & Document Root

In LacePHP the public/ folder is where your web server should point if you are deploying your application to a host or using third-party web server on your local. By exposing only public/index.php to the internet, you keep the rest of your application code safe from direct access.

# Example Apache vhost
DocumentRoot "/path/to/LacePHP/public"

<Directory "/path/to/LacePHP/public">
    AllowOverride All
    Require all granted
</Directory>

Why this matters: Only files inside public/ (like CSS, JS, and index.php) are visible to users. All your core code in lacebox/, weave/, shoebox/, and config/ stays out of reach.

Enabling Friendly URLs with .htaccess

LacePHP includes a file named ht.access that contains URL‐rewriting rules. To enable “clean” URLs (so you can visit /hello instead of /index.php/hello), simply rename it:

mv public/ht.access public/.htaccess

Now your server will use Apache’s mod_rewrite rules and you’ll get human-friendly URLs everywhere.

Once you’ve completed these steps, your LacePHP application is configured, secure, and ready for your first feature. Happy coding!