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: .. code-block:: bash mv lace.json.example lace.json Open **lace.json**, this file controls core framework settings: Explanation of Key Settings in `lace.json` ------------------------------------------ .. list-table:: :header-rows: 1 :widths: 20 80 * - 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`: .. code-block:: bash 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 ------------------------------------------------ .. list-table:: :header-rows: 1 :widths: 20 80 * - 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: .. code-block:: bash cd /path/to/LacePHP php lace tread You’ll see a message like: .. code-block:: text 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. .. code-block:: text # Example Apache vhost DocumentRoot "/path/to/LacePHP/public" AllowOverride All Require all granted 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: .. code-block:: bash mv public/ht.access public/.htaccess Now your server will use Apache’s mod_rewrite rules and you’ll get human-friendly URLs everywhere. .. * **boot** .. * ``timezone`` .. Your default PHP timezone. .. * ``debug`` .. Show debug output if ``true``. .. * ``show_blisters`` .. Show detailed error pages in development. .. * **database** .. * ``driver`` .. Choose ``sqlite`` or ``mysql``. .. * ``sqlite.database_file`` .. Path to the SQLite file. .. * **mysql** connection settings: .. * ``host`` .. MySQL server hostname. .. * ``port`` .. MySQL server port (default ``3306``). .. * ``database`` .. Name of the MySQL database. .. * ``username`` .. Username for MySQL authentication. .. * ``password`` .. Password for MySQL authentication. .. * ``charset`` .. Character set for MySQL connections. .. * ``collation`` .. Collation setting for MySQL. .. * **logging** .. * ``enabled`` .. Turn on file logging. .. * ``levels`` .. HTTP status codes to log. .. * ``path`` .. File path where log entries are written. .. * **sole_version** .. Internal framework version, used for upgrades. .. * **base_url** .. The root URL used when generating links. .. * **grip_level** .. Verbosity level for internal error handling (a little shoe pun). .. * **paths.vendor** .. Location of your Composer ``vendor/`` directory. .. * **auth** .. * ``guard`` .. Method of authentication (for example, ``token``). .. * ``tokens`` .. Array of secret keys used for token-based authentication. Once you’ve completed these steps, your LacePHP application is configured, secure, and ready for your first feature. Happy coding! | |