Firstly, an apology. AdamRMS was, in its early life, a 2-year personal labour of love of over 600 commits pursued more as a potential commercial project than the community developed open-source project it has become today. As a result, there are no tests and documentation is limited but improving. Migrations and seeds were written in one go and as such there is no history available of the database structure before v1.47.6. Similarly, code quality and style varies as the project grew alongside its creators skill set.
For performance reasons, AdamRMS does not use a router, and instead leaves routing to the webserver (Caddy). The project is structured around two directories within
admin- The AdamRMS dashboard
common- (not publicly accessible) A handful of Classes, Functions & Templates
Database migrations, written in Phinx, are provided in
To improve user performance & error handling this site is not based around a conventional laravel-esque form structure for user interaction. Instead, most data from the database is returned to the user through a normal dynamically loaded page, generating html from a twig template.
When a user interacts with the page, such as pressing a button, this triggers a JQuery function (all defined in that pages' twig template) which makes an "api call" to a php script within the
admin/api/ folder and executes the change (such as an insert/delete/update). Once this completes successfully two things can happen. The first, a legacy behaviour, is that the page reloads to reflect the changes in the page itself. The second option is that the page calls a function to update what's displayed, without needing a page re-load. There are quite a few endpoints in
admin/api that provide access to retrieving data as well, as this is how the mobile app downloads its data which it then displays.
Recommended: Docker Devcontainer
This repo has a configured devcontainer for use with GitHub Codespaces or VSCode. If you have a GitHub Codespaces subscription (paid), you can use this to get started with the project in the web, or if you have access to VSCode on your computer (free) you can get started by cloning the repo and opening it in VSCode, then opening the project in a devcontainer.
When creating the container, a database will be created but it will be empty.
To setup some test data, press
Ctrl+Shift+P then type
tasks: run task - then select the
Seed Database task which will be listed. If you already have a database container it will be truncated first - meaning all data will be lost. The database will be available on port 3306, and the webserver on port 8080. VSCode will automatically open the webserver in a browser window.
You can then press the debug menu on the left and select
Launch AdamRMS with debugger and the login screen will show. Default credentials are
Harder: Installing Locally
The following assumes you already have a local development environment setup and are familiar with deploying LAMP-style stacks locally. The deployment strategy is somewhat different, but this is covered in a separate repo.
.env, setting database credentials for your local MySQL server as you go
- Set the document root of your local web server to
php vendor/bin/phinx migrate(or
vendor\bin\phinx migrateon Windows) to set up the database
- If setting up for the first time run
php vendor/bin/phinx seed:run(or
vendor\bin\phinx seed:runon Windows) to seed some data to allow you to login. NB: This will delete all data in the database by running the seed command
- Browse to
- Default credentials are
Each time you pull new changes written by others you will likely need to update your local database by running the Phinx migrate command. Phinx migrations are automatically run on the production server in the dockerfile.
Tips & Tools
- Database library used: ThingEngineer/PHP-MySQLi-Database-Class