Setting Up a Development Environment

Get an installation you can break, turn the diagnostics on, and confirm the loop works before you write anything that matters.

Overview

Development happens against a real installation, not a mock. There is no separate developer build: the same code that serves customers is the code you extend. The only difference is which diagnostics are switched on, and whether you are allowed to break it.

So the first thing to set up is not a tool, it is a boundary. Use an installation nobody depends on, with its own database and its own domain. Every instruction below assumes that.

Prerequisites

• PHP 8.1 or newer with the extensions a normal web installation needs, and access to the same PHP from a shell.
• MySQL or MariaDB, with a database that is yours alone.
• A web server that can serve the installation directory, and the ability to run a scheduled command.
• An installation you are free to break. Never develop against one that has real customers in it.

Where Things Live

Walkthrough

Check the Runtime

1. Run php -v in a shell and confirm the version is 8.1 or newer.
2. Confirm the same binary is what the web server uses. A shell running one version while the site runs another is the source of failures that look impossible.
3. Confirm coremio/storage is writable by the user the web server runs as.

Turn the Diagnostics On

1. Open coremio/configuration/debug.php. It returns a plain array of switches, and startup turns five of them into constants the rest of the code tests.
2. Set error to true. That defines ERROR_DEBUG, which the error handler reads, so failures surface instead of turning into a generic page.
3. Set logging to true (it defines LOG_SAVE) so the error log records what happened.
4. Leave query-logging off unless you are hunting a specific query. It is loud, and it is restricted to the addresses listed next to it.
5. Reload any page. A deliberate mistake in your own code should now be visible instead of silent.

Verify the Loop

1. Run php coremio/errlog.php stats. It prints the totals from the error log, which proves both the shell PHP and the storage directory work.
2. Make a deliberate error somewhere harmless, load the page, and find it with php coremio/errlog.php list --limit=5.
3. Remove the deliberate error. You now have a working edit, reload and diagnose cycle.

Example

The switches, the constant each one defines, and the two commands you will use constantly.

return [
    'demo'                    => false,   // DEMO_MODE        every write is refused
    'error'                   => true,    // ERROR_DEBUG      surface errors, not a generic page
    'developer'               => true,    // DEVELOPMENT      developer affordances in the panel
    'logging'                 => true,    // LOG_SAVE         write failures to the error log
    'logging-module'          => true,    // LOG_SAVE_MODULE  log module traffic as well
    'query-logging'           => false,   // read directly; very loud, only when hunting a query
    'query-logging-valid-ips' => ['127.0.0.1', '::1', 'UNKNOWN'],
];

// Read back with the same slash path, at any point after startup:
$loud = Config::get('debug/query-logging');

# Is the installation healthy from the command line?
php coremio/errlog.php stats

# What failed most recently?
php coremio/errlog.php list --limit=5

Pitfalls

Related Articles

• Developing for WISECP
• Debugging and Logs
• Your First Change
• Bootstrap and Autoloading