slimAdmin is a PHP web programming framework based on Slim Micro-Framework and the PostgreSQL database. It has a built-in administrative interface and other tools to allow rapid web app development.
INSTALLATION
clone this repo
run composer install
Set write permissions on /storage and its subdirectories (ie chmod -R 777 storage/)
Create your PostgreSQL database and restore /docs/slimAdminInit.sql to it (ie psql dbName < docs/slimAdminInit.sql)
Create a web server site with /public as the home directory
Copy/rename .env.example to .env then edit .env
Navigate to your site to see the default homepage. If there are no errors then you've succesfully connected to the database.
Edit with credentials, then run cliScripts/insertTopAdministrator.php
Navigate to your site /private (can be changed in /config/constants.php - ADMIN_DIR) and login!
FEATURES
PHP 8.1+
Built on Slim framework (v 4.10), a front-controller micro-framework for PHP
PostgreSQL Database Integration
Administrative User Interface and Navigation
Authentication (Log In/Out)
Authorization (Role Based Access Control for Resource and Functionality Access)
Built-in Database Logging/Reporting of system events, login attempts, and errors
Error Handling
Emailing with PHPMailer
CSRF Checking
Slim's PHP-View Templates
HTML Form Generation using FormFormer
Data Validation with Valitron (NOTE: If you are comparing floating-point numbers with min/max validators, you should install the PHP BCMath extension for greater accuracy and reliability. The extension is not required for Valitron to work, but Valitron will use it if available, and it is highly recommended.)
XSS Prevention
PHP dotenv for configuring server environments
PHP Error Logging with Stack Trace for debugging
CRUD ORM
CODING NEW FUNCTIONALITY
work in progress
Create a new directory under domain and create a Model/View/Controller (or whatever code structure you desire) as necessary. You can model these files after existing functionality such as SlimPostgres/Administrators/Roles (single database table model) or SlimPostgres/Administrators (joined database tables).
Add and configure your new route to the system by:
- Adding a new route name constant in config/constants.php
- Adding the new route in config/routes.php
- For new administrative resources, add AuthenticationMiddleware to the route (see existing examples in the routes file)
- For new administrative resources, if authorization is required at a resource or functionality level, add them to the resources / permissions section in config/constants.php, then add AuthorizationMiddleware to the route (see existing examples in the routes file)
- For new administrative resources, you can add a link in the administrative navigation menu by editing SlimPostgres/AdminNavigation.php, or config/settings.php ['adminNav'].
Administrative Interface and Navigation
Upon browsing to the administrative directory set in $config['adminPath'] authenticating, the appropriate resource is loaded based on $config['slim']['authentication']['administratorHomeRoutes'], if found for the administrator, otherwise from ROUTE_ADMIN_HOME_DEFAULT in constants.php.
The following administrative functionalities are already coded:
- View System Events
- View Login Attempts
- View, Create, Edit, Delete Administrators (with role assignment)
- View, Create, Edit, Delete Roles
- View, Create, Edit, Delete Permissions (with role assignment)
- View, Create, Edit, Delete Database Table Records (with role assignment)
- Logout
These options are found in the navigation menu at top left. Once other options are coded, they can be added to the menu by uncommenting/adding to $config['slim']['adminNav'].
Authentication
Administrative resources can require authentication (login) to access. See config/routes.php admin home for adding Authentication Middleware to a route.
Authorization
Administrative resources and functionality can be protected against unauthorized use based on role based administrative permissions. Permissions to access system resources/functionality can be inserted through the administrative interface, then assigned to one or more roles. Administrators are also assigned roles, which then grants them the permissions assigned to those roles. Authorization checks are done by a simple AuthorizationService::isAuthorized(string $resource): bool call, where the $resource string must match the permission title that has been inserted. Checks are also performed in AdminNavigation to determine whether or not to display navigation options. Authorization failures result in alerts being written to the SystemEvents table and the user redirected to the admin homepage with a red alert message displayed.
System Event Database Logging
Certain events such as logging in, logging out, inserting, updating, and deleting certain database records or business entities are automatically logged into the system_events table, which is viewable in the admin interface. You can choose other events to insert as you write your application. For usage examples and help, search "systemEvents->insert" and see SystemEventsTableMapper.php.
PHP errors are also logged to the system_events table by default (this can be turned off in $config['errors']['logToDatabase']). Note that php errors such as Notices and Warnings that occur during a transaction do not get logged to the database, as the transaction never gets commited, but Exceptions will be logged to the database, as they are caught inside the transaction, then the transaction is rolled back then the exception is re-thrown. Please search pg_query("BEGIN"); for examples.
Slim's built in error handling has been disabled, and custom error handling implemented, in order to handle any errors encountered prior to running the Slim application, as well as to be able to email an administrator that an error occured, and to log the error to the system_events database table, which is viewable in list form in the administrative interface.
Reporting Methods:
-
Database Log
If the database and system events services have been set as properties in the ErrorHandler class, all errors are logged to the SystemEvents table. The stack trace is not provided, instead, a reference is made to view the log file for complete details. See System Event Database Logging for more information. -
File Log
All error details are logged to $config['storage']['logs']['pathPhpErrors']. -
Echo
Live Sites* Error details are never echoed, rather, a generic error message is echoed. For fatal errors, this message is set in $config['errors']['fatalMessage'].Dev Sites* Error details are echoed unless the environmental variable ERRORS_ECHO_DEV is set to 0.
-
Email
For security, error details are never emailed.Live Sites* All errors cause generic error notifications to be emailed to $config['errors']['emailTo'].
Dev Sites* Generic error notifications are emailed to $config['errors']['emailTo'] if the environmental variable ERRORS_EMAIL_DEV is set to 1.
- The current site is considered a production (live) site unless the environmental variable IS_LIVE is set to 0.
See ErrorHandler.php for further info.
Emailing with phpMailer
Verify mailer service exists (it may not on dev servers, depending on $config['sendEmailsOnDevServer']).
// magic method to access mailer inside container
if ($this->mailer !== null) {
$this->mailer->send(...)
}
CSRF
The Slim Framework CSRF protection middleware is used to check CSRF form fields. The CSRF key/value generators are added to the container for form field creation. They are also made available to Twig. A failure is logged to SystemEvents as an error, the user's session is unset, and the user is redirected to the (frontend) homepage with an error message.
XSS Prevention
htmlentities() is used to escape output.
- this is a work in progress
PHP Error Log
PHP Errors with stack trace are logged to the file set in config['storage']['errors']['phpErrorLogPath']
Create PostgreSQL Database (One Method)
- $ psql -U postgres (note you may have to edit your pg_hba.conf file to allow local md5 or trust login https://stackoverflow.com/questions/45632463/peer-authentication-failed-for-user-in-postgresql)
- postgres=# create role myrolename with login; (creating the role with the same name as the database name allows easy psql access)
- postgres=# alter role myrolename with encrypted password 'mypassword';
- postgres=# create database mydbname with owner myrolename;
CODE DOCUMENTATION
Entities
Entities are like business objects at the core of the system. The current entities are Administrators, Roles, Permissions, and Events. Domain business object, i.e. Orders in an ecommerce system, will go in the domain directory.
Database Mappers
Mappers are where all PostgreSQL database queries should occur. In fact, where all database function calls (pg_*) should occur. There are two types of mappers: table mappers and entity mappers.
Table Mappers
Table mappers consist mainly of select, insert, update and delete functions for a single database table. Select functions return an array of record arrays (using pg_fetch_all) or a single record array, or null if no records match the query. Insert functions return the primary key value inserted. Update and delete functions have no return value. All failed queries result in an exception being thrown.
Entity Mappers
Entity mappers are like table mappers for more complex entities requiring two or more database tables. For example, every administrator must have one or more assigned roles, so inserting an administrator is done using an entity mapper rather than a table mapper. The entity mapper will be responsible for inserting both the administrator roles and the administrator, using a transaction. It can call table mappers to perform the single table queries. Entity mappers can also return entity objects, i.e. an Administrator or an array of Administrators.
===========================================================>Thank you.