eelKit is a small PHP application framework for building authenticated internal tools quickly. It currently ships with a working account area, role/card permissions, MFA setup, session/device checks, audit history, anti-fraud request metadata, and a lightweight card/page rendering model.
The project is deliberately simple: no package manager is required for the current codebase, the web entrypoint is plain PHP, and the included test runner can be executed directly with PHP.
Applications may also be hosted beneath a configured URL path such as /reports/.
The default remains /; no directory moves are required. See
application path configuration and Apache deployment.
Regression tests for root and subpath installations use the existing PHP test
runner; no additional package manager or browser dependency is required.
- Secure account bootstrap flow for the first user.
- Password hashing with Argon2id and a server-side pepper.
- Time-based one-time password MFA setup and verification (supports FreeOTP).
- Session regeneration, CSRF protection, AJAX nonce protection, and device-bound session checks.
- Role based access to page cards, including a built-in Admin role.
- User login history and account audit tables.
- Centralised request, response, page, card, action, configuration, and database helper classes.
- Lightweight AJAX refresh model for cards and flash messages.
- Built-in SVG chart rendering for common dashboard and reporting graphs, without external chart libraries.
- Built-in developer test runner with broad class coverage.
eelKit supports administrator-created pending accounts, allowing a delegated user manager to invite someone by email, SMS, or a copied signup link. Invitees complete their own account setup through the public signup flow, where token checks, identity verification, session-bound completion state, expiry, revocation, and rate limits protect the process before the account becomes active.
The settings area includes cards for invitation templates, external base URL and trusted reverse proxy handling, SMS gateway delivery, and SMTP or PHP mail() delivery. SMS and SMTP can be tested from the UI, secrets are preserved when left blank, and signup token or verification lockouts can be reviewed and reset from the logs page.
- PHP 8.4 or newer is recommended.
- PHP extensions:
pdo,pdo_odbcor another PDO driver that matches your DSN,mbstring,json, andsession. - MariaDB 10.11 or compatible MySQL/MariaDB server.
- A web server that can serve
web_rootas the document root.
web_root/index.php- main web entrypoint.web_root/classes- framework, service (including user services), store, repository, and database classes.web_root/content/pages- page definitions.web_root/content/cards- card definitions rendered inside pages.web_root/content/actions- shared card action handlers.web_root/classes/service/ChartService.php- internal chart renderer.secure/app.php- application configuration, hydrated automatically on first run.db_schema/eelKit.schema.sql- full database schema for a new install.tools/php/reset_password.php- A CLI password reset helper.tools/php/setupDb.php- A CLI helper for setup, database configuration, migrations, and external IP refresh.tools/php/setExternalIP.php- A CLI helper for storing external IP configuration.web_root/tests- project test runner and test cases.secure- local secrets such as generated security keys and bootstrap code.file_logs- local log output.
-
Clone or copy the project to the server.
-
Configure the web server so
web_rootis the public document root. Do not exposesecure,db_schema,tools, orfile_logsas web-accessible directories. -
Create the database:
CREATE DATABASE eelKit CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;
-
Configure a PDO DSN through the setup tool. If
secure/app.phpdoes not exist yet, visiting the app or running a tool will create it from the built-in defaults:'db' => [ 'dsn' => 'odbc:eelkit', 'user' => '', 'pass' => '', 'logfile' => '', ],
The setup tool asks for database settings if
db.dsnis empty. You can also pass settings directly, for examplephp tools/php/setupDb.php --driver=mysql --host=127.0.0.1 --database=eelkit --user=root.For MariaDB through ODBC, configure the named DSN itself with
CHARSET=utf8mb4on both Windows and FreeBSD. After setup, runtools/bin/dbUnicodeDiagnostic.sh(ortools\bat\dbUnicodeDiagnostic.baton Windows) to verify parameterised Unicode and JSON values round-trip byte-for-byte. A successful round trip is the authoritative check for named DSNs because PDO cannot read their ODBCCHARSETsetting directly. -
Run the database setup tool. It makes sure
secure/app.phpexists, configures the database if needed, runs migrations, loads the baseline schema first if the configured database has no eelKit application tables, and then refreshes the external IP setting:php tools/php/setupDb.php
-
Make sure the PHP process can write to:
securefile_logs, if SQL logging is enabled- any configured upload directory
-
Visit the application in a browser. If no users exist, eelKit creates a bootstrap code file at:
secure/bootstrap_code.txtUse that code on the first-account setup screen. The file is removed after the first user is created.
-
Set
developer_optionstofalseinsecure/app.phpfor production use once setup and diagnostics are complete.
Keep MariaDB databases and text columns on utf8mb4. Legacy latin1 auditing and data repair are application-specific, evidence-led work and are not performed automatically by eelKit.
The schema uses InnoDB foreign keys for user-owned records:
role_card_permissions.role_idreferencesroles.id.user_account_audit.affected_user_idandactor_user_idreferenceusers.id.user_login_rate_limits.user_idreferencesusers.idand is set toNULLif the user is deleted.user_logon_history.user_idreferencesusers.idand is set toNULLif the user is deleted.user_totp.user_idreferencesusers.idand cascades on user deletion.
users.role_id intentionally allows the reserved value -1, which represents the built-in Admin role in PHP. Positive values represent rows in roles. The schema includes a check constraint for that convention, but it does not add a foreign key for users.role_id because a normal foreign key cannot express "either the built-in sentinel or a valid role row" without changing the current application contract.
db_schema/eelKit.schema.sql is the baseline schema for a new database. The migration tool loads it automatically only when none of the eelKit application tables exist.
Incremental upgrades live in db_schema/migrations and are applied in filename order by:
php tools/php/setupDb.php --migrate-onlyFor first-time setup, prefer:
php tools/php/setupDb.phpThe migration runner creates a schema_migrations table and records each applied SQL file. Keep migration filenames ordered with the date and a sequence number, for example:
2026_05_08_001_schema_integrity.sql
2026_05_08_002_add_upload_metadata.sql
For existing databases that already match the original baseline, insert the baseline marker into schema_migrations once, then run the migration tool:
INSERT INTO schema_migrations (migration)
VALUES ('2026_05_07_001_initial_schema.sql');eelKit includes an internal chart service, ChartService, for rendering graphs directly from PHP card output without external JavaScript charting libraries.
Current graph types:
- Bar graph.
- Stacked bar graph with multiple series.
- Line graph with support for up to five series.
- Pie chart.
- Donut chart.
- Gauge.
- Sankey diagram for value flows, such as income sources flowing into total value and then into allocations.
- Calendar heat map.
- Monthly heat map.
The Example Graphs page demonstrates the available graph cards and can be used as a reference for adding chart output to application-specific cards.
Run the full local suite with:
php web_root/tests/index.phpThe runner returns JSON and exits with a non-zero code if any test fails.
Skipped tests are reported separately and are never counted as passed. Test code can attach a machine-readable category when skipping:
$harness->skip('MariaDB-specific assertion running under SQLite.', 'database-engine');Normal runs remain healthy when tests are skipped. For readiness checks, enable strict skip handling and explicitly allow only expected environmental categories:
php web_root/tests/index.php \
--strict-skips \
--allow-skip-category=database-engine \
--allow-skip-category=external-serviceIn strict mode, any skipped test whose category is not listed makes the run unhealthy and produces a non-zero exit code. Legacy one-argument skip() calls use the unclassified category.
Reset a user's password from the command line:
php tools/php/reset_password.phpSet or refresh external IP related configuration:
php tools/php/setExternalIP.phpHydrate secure/app.php and initialise or migrate the configured database:
php tools/php/setupDb.php- Serve only
web_rootpublicly. - Set
developer_optionstofalse. - Disable SQL logging unless actively diagnosing an issue.
- Keep
secure/*.keysout of version control and backed up securely. - Use HTTPS so secure cookies can be enabled automatically.
- Restrict file permissions on
secureand configuration files. - Run the test suite after schema or framework changes.
eelKit is licensed under the BSD 3-Clause License. See LICENSE for details.