insalyon / acme
php framework developped by INSA Lyon
Requires
- php: >=8.2
- ext-curl: *
- ext-intl: *
- ext-ldap: *
- ext-mbstring: *
- ext-pgsql: *
- ext-xml: *
- ext-zip: *
- apereo/phpcas: ^1.4
- jumbojett/openid-connect-php: 0.9
- shuchkin/simplexlsx: 1.0.19
- dev-main
- v2.0.7-alpha
- v2.0.6-alpha
- v2.0.5-alpha
- v2.0.4-alpha
- v2.0.3-alpha
- v2.0.1-alpha
- v2.0.0-alpha
- v1.6.2.1-ALPHA
- v1.6.2.0a
- v1.6.1.9a
- v1.6.1.8a
- v1.6.1.7a
- v1.6.1.6a
- v1.6.1.5a
- v1.6.1.4a
- v1.6.1.3a
- v1.6.1.2a
- v1.6.1.1a
- v1.6.1.0a
- v1.6.0.8a
- v1.6.0.7a
- V1.6.0.6a
- 1.6.0.5a
- 1.6.0.4a
- dev-develop
- dev-cfourel-develop-patch-45161
- dev-dev_cfourel
- dev-35-add-semi-public-mode-for-front
- dev-develop_ldupuy
This package is auto-updated.
Last update: 2025-03-14 11:15:08 UTC
README
Automated and Customizable MicroFramework Engine
License
This project is licensed under the Creative Commons Attribution-NonCommercial 4.0 International License. See the LICENSE file for details.
Table of contents
Presentation
ACME Framework: Comprehensive Overview and Quality Analysis
The ACME framework is a PHP-based modular framework designed to streamline the development of web applications by providing robust tools and services for common tasks. It adheres to best practices in configuration management, logging, database interaction, LDAP management, CSV handling, Excel handling, UUID generation, CAS, OIDC integration, file validation, a web component library, and plugin extensibility. The framework’s key features are exposed through the central ACME.php
controller. Below is an exhaustive description of its key features along with a deep quality and reliability analysis.
Key Features
Configuration Management
- Centralized Configuration: Managed via
Configuration.php
andLogConfiguration.php
for consistent application settings. - Environment-Specific Settings: Supports configurations tailored for different environments (development, staging, production).
- cfg.ini File: Uses an
cfg.ini
file for configuration settings, which helps with maintainability. The configuration file is stored out of the web root for security purposes, preventing unauthorized access.
- Centralized Configuration: Managed via
Logging
- Robust Logging System: Handled by
LogConfiguration.php
, which manages log levels (MSG
,ERR
,WRN
,DBG
) and stores logs in a specified directory. - Custom Exceptions: Ensures that errors are logged and tracked using custom exceptions.
- Robust Logging System: Handled by
Database Interaction
- DBConnector.php: Provides a PDO-based implementation for database operations, supporting secure query execution and transaction management.
- SQL CRUD Operations: Facilitates create, read, update, and delete operations with parameter binding to prevent SQL injection.
LDAP Management
- LDAPConnector.php: Manages LDAP connections and operations, including search, add, delete, and modify entries.
- Secure LDAP Interactions: Ensures secure and efficient communication with LDAP servers.
CSV Handling
- CSVService.php: Offers methods to read from and write to CSV files, converting them to and from associative arrays.
Excel Handling
- ExcelService.php: Supports reading from and writing to Excel files in various formats, converting Excel data to arrays and vice versa.
UUID Generation
- UUIDv5Service.php: Generates version 5 UUIDs based on SHA-1 hashing, useful for creating deterministic unique identifiers.
CAS (Central Authentication Service) Integration
- CASService.php: Implements CAS for single sign-on (SSO) authentication, enhancing security and user convenience.
OIDC (OpenID Connect) Integration
- OIDCService.php: Provides OpenID Connect integration for authentication and authorization, allowing applications to verify user identities and obtain profile information.
File Validation
- FileValidationService.php: Validates file uploads by checking file types, sizes, and other criteria to ensure files meet application requirements.
Web Component Library
- WebComponents: Includes reusable components for building dynamic web interfaces, such as forms, fieldsets, and links.
- INSAForm.php: Manages HTML forms.
- INSAFieldSet.php: Handles HTML fieldsets.
- INSALink.php: Creates and manages HTML links with customizable attributes and styles.
Plugin Extensibility
- Plugins Directory: Allows the framework's functionalities to be extended through plugins. Plugins can be developed independently to add new features or enhance existing ones, providing a flexible and scalable architecture.
Modular Structure
- Mods Directory: Organizes the functional code for the specific application being developed using the framework, promoting code reuse and maintainability.
HTTP Requests
- CURLConnector.php: Manages HTTP requests using cURL, supporting various HTTP methods (GET, POST, PUT, DELETE, PATCH).
Quality and Reliability Analysis
Modularity and Scalability
Modular Design
- The framework’s modular design allows developers to extend functionality easily. Modules in the
mods
directory can be developed independently, promoting scalability. - Plugins can be added to extend the framework’s capabilities without modifying the core framework, ensuring that the system remains scalable and flexible.
- The framework’s modular design allows developers to extend functionality easily. Modules in the
Scalable Architecture
- The modular structure promotes scalability by enabling the addition of new features without impacting existing ones.
- Environment-specific configurations help scale applications across different stages of development, testing, and production.
Consistency
Centralized Configuration
- Centralized configuration ensures consistent application settings across different environments.
- Use of
Configuration.php
andLogConfiguration.php
for managing settings provides a unified approach to configuration management. - The
cfg.ini
file helps maintain configuration settings and is stored out of the web root for security purposes, ensuring unauthorized users cannot access it.
Uniform Logging Practices
- Consistent logging practices facilitated by
LogConfiguration.php
ensure that logs are stored in a standardized format, making it easier to monitor and debug applications.
- Consistent logging practices facilitated by
Robust Error Handling
Custom Exceptions
- Use of custom exceptions across various modules (e.g.,
AcmeSqlException
,AcmeLdapException
) ensures that errors are captured and handled in a controlled manner. - Detailed error messages and logging provide insights into issues, facilitating quick resolution.
- Use of custom exceptions across various modules (e.g.,
Error Logging
- Comprehensive error logging helps in tracking issues, understanding their root causes, and taking corrective actions.
- Errors are logged with contextual information, aiding in effective debugging.
Security
Secure Data Handling
- Parameter binding in SQL queries (via
DBConnector.php
) prevents SQL injection attacks. - Secure handling of LDAP operations (via
LDAPConnector.php
) ensures that interactions with LDAP servers are protected against common vulnerabilities.
- Parameter binding in SQL queries (via
Authentication and Authorization
- Integration with CAS (
CASService.php
) and OIDC (OIDCService.php
) provides robust mechanisms for authentication and authorization. - These integrations enhance security by leveraging established protocols for user verification and access control.
- Integration with CAS (
File Validation
FileValidationService.php
ensures that uploaded files meet specified criteria, preventing potential security risks associated with malicious files.
Configuration Security
- Storing the
cfg.ini
file out of the web root prevents unauthorized access to sensitive configuration settings, enhancing the overall security of the application.
- Storing the
Flexibility
Adaptability to Different Environments
- Environment-specific configurations allow the framework to adapt to different deployment scenarios (development, staging, production).
- Flexibility in configuration management enables customization based on application requirements.
Support for Various Data Formats
- The framework’s ability to handle different data formats (CSV, Excel) and HTTP methods makes it versatile and suitable for a wide range of applications.
Comprehensive Feature Set
Extensive Capabilities
- The framework’s extensive features, including UUID generation, CAS, and OIDC services, cater to a wide range of enterprise applications requiring secure authentication, unique identifier generation, and third-party identity provider integration.
- The web component library ensures consistent and efficient front-end development with reusable UI elements.
Unified Interface
ACME.php
provides a unified interface for accessing all key features, simplifying integration and usage.
Reliability
Error Handling and Logging
- The framework's robust error handling and logging mechanisms ensure that all critical issues are logged and can be traced back, which is crucial for debugging and maintaining application reliability.
- Custom exceptions provide detailed context about errors, making it easier to identify and fix issues.
Testability
- The modular structure of the framework promotes testability. Individual modules and components can be tested independently, ensuring that each part of the system works correctly.
- The use of consistent configuration and logging across the framework ensures that tests can be easily set up and monitored.
Maintainability
- The framework's modular design, centralized configuration, and consistent logging practices make it highly maintainable. Developers can easily update and extend the framework without affecting existing functionality.
- Documentation of configuration settings, logging practices, and module interfaces further enhances maintainability.
Scalability
- The framework is designed to scale with the application's needs. New modules can be added to the
mods
directory without disrupting existing functionality, and the framework's flexible configuration settings allow it to adapt to different environments and workloads.
- The framework is designed to scale with the application's needs. New modules can be added to the
Security Measures
- The use of secure coding practices, such as parameter binding in SQL queries and secure handling of LDAP operations, ensures that the framework is resistant to common security vulnerabilities.
- Integration with CAS and OIDC provides robust mechanisms for secure authentication and authorization.
- Storing configuration files like
cfg.ini
outside of the web root adds an extra layer of security by preventing unauthorized access to sensitive configuration data.
Conclusion
The ACME framework is a powerful and flexible PHP framework designed to streamline web application development. Its robust configuration management, comprehensive logging, secure database and LDAP interactions, flexible CSV and Excel handling, UUID generation, file validation, web component library, and integration with CAS and OIDC make it a solid choice for developers looking for a reliable and scalable solution. The centralized ACME.php
controller provides a unified interface to access all key features, enhancing ease of use and integration.
By providing robust tools and a modular architecture, the ACME framework ensures that developers can build secure, maintainable, and scalable web applications efficiently. Its comprehensive feature set, including configuration management, logging, database and LDAP interaction, CSV and Excel handling, UUID generation, file validation, web component library, plugin extensibility, and integration with CAS and OIDC, makes it a versatile and powerful solution for modern web development.
ACME Framework Documentation
Overview
The ACME Framework is designed to help developers build and manage applications efficiently. This document provides an overview of how to use the framework, including setup, configuration, key features, initialization, and module loading.
Directory Structure
- main/mods: Directory where the functional code of your application is stored.
- main/html: Directory where the HTML templates are stored.
- insalyon/dsi/src/.env: Directory where the configuration file
cfg.ini
should be created. - DEFAULT-cfg.ini: Sample configuration file to help you create your own
cfg.ini
.
Setup
To ensure the framework works properly, you need to run composer
to manage dependencies and handle autoloading.
Installing Dependencies
- Ensure you have Composer installed on your system. You can download it from getcomposer.org.
- Navigate to the root directory of your project where the
composer.json
file is located. - Run the following command to install the dependencies:
composer install
This command will install all the required dependencies and set up autoloading according to the configuration in the composer.json
file.
Configuration
Using cfg.ini
- Navigate to the
insalyon/dsi/src/.env
directory. - Create a new file named
cfg.ini
. - Use the
DEFAULT-cfg.ini
file as a template to create your owncfg.ini
.[section] key=value
- Populate
cfg.ini
with your configuration keys and values.
Using Environment Variables
Alternatively, you can store all the configuration keys and their values in environment variables. Ensure that your environment variables match the expected configuration keys in the framework.
Key Features
All the key features of the ACME Framework are accessed through the static functions of the ACME
class. Below is an overview of the available functions.
Accessing ACME.php
Class Functions
Include the
ACME
class in your script usinguse
:use insalyonController\ACME;
Call the desired static functions from the
ACME
class:ACME::functionName($parameters);
Function Descriptions
includeHTMLHeader
Includes the HTML header template from the main/html
directory.
public static function includeHTMLHeader()
includeHTMLBody
Includes the HTML body template from the main/html
directory.
public static function includeHTMLBody()
includeHTMLFooter
Includes the HTML footer template from the main/html
directory.
public static function includeHTMLFooter()
includeHTMLCustomTemplate
Includes a custom HTML template from the main/html
directory.
public static function includeHTMLCustomTemplate(string $fileName)
loadACMEMod
Loads an ACME module from the main/mods
directory.
public static function loadACMEMod(string $fileName)
validateFile
Validates a file.
public static function validateFile(string $fileError, string $fileSize, string $fileTmp)
generateXLSDataStructure
Generates an XLS data structure.
public static function generateXLSDataStructure(string $file)
sendHTTPRequest
Sends an HTTP request.
public static function sendHTTPRequest(string $url, string $method, string $body = "", array $params = [], array $header = [])
log
Logs a message with a specified level.
public static function log(string $level, string $message)
createCustomDAO
Creates a custom DAO.
public static function createCustomDAO(string $dbType, string $dbHost, string $dbName, string $dbUser, string $dbPassword)
selectSQL
Executes a SELECT SQL query.
public static function selectSQL(string $query, array $params = [])
insertSQL
Executes an INSERT SQL query.
public static function insertSQL(string $query, array $params = [])
updateSQL
Executes an UPDATE SQL query.
public static function updateSQL(string $query, array $params = [])
deleteSQL
Executes a DELETE SQL query.
public static function deleteSQL(string $query, array $params = [])
executeQueryBatch
Executes a batch of SQL queries.
public static function executeQueryBatch(array $queriesAndParams)
generateUUIDV5
Generates a UUID v5.
public static function generateUUIDV5(string $randomString)
ldapAddNode
Adds an LDAP node.
public static function ldapAddNode(string $dn, array $entry)
ldapSearch
Searches an LDAP directory.
public static function ldapSearch(string $dn, string $filter = "objectclass=*", array $attribs = [])
ldapDeleteNode
Deletes an LDAP node.
public static function ldapDeleteNode(string $dn)
ldapAddNodeAttributeAndValue
Adds an attribute and value to an LDAP node.
public static function ldapAddNodeAttributeAndValue(string $dn, array $modifs)
ldapRemoveNodeAttribute
Removes an attribute from an LDAP node.
public static function ldapRemoveNodeAttribute(string $dn, array $modifs)
ldapRemoveNodeAttributeValue
Removes an attribute value from an LDAP node.
public static function ldapRemoveNodeAttributeValue(string $dn, array $modifs)
ldapReplaceNodeAttributeValue
Replaces an attribute value of an LDAP node.
public static function ldapReplaceNodeAttributeValue(string $dn, array $modifs)
ldapBatchRequests
Executes a batch of LDAP requests.
public static function ldapBatchRequests(array $requests)
getCustomVariableValue
Gets the value of a custom variable.
public static function getCustomVariableValue(string $key)
getConfigurationKeys
Gets the configuration keys.
public static function getConfigurationKeys()
CSVToArray
Converts a CSV file to an array.
public static function CSVToArray(string $fileName, int $length = 1000, string $separator = ",", string $enclosure = "\"", string $escape = null)
arrayToCSV
Converts an array to a CSV file.
public static function arrayToCSV(string $fileName, array $datas, string $separator = ",", string $enclosure = "\"", string $escape = null)
httpErrorHandler
Handles HTTP errors.
public static function httpErrorHandler(string $logMsg, string $httpCode, mixed $jsonAnswer)
httpErrorHandler
Handles HTTP errors.
public static function httpErrorHandler(string $logMsg, string $httpCode, mixed $jsonAnswer)
getUserInfo
Main Handler to recover SSO user attribute(s).
public static function getUserInfo($attribute = "")
Initialization and Module Loading
Initialization
The initialization of the ACME Framework is handled in the index.php
file. This file sets up the necessary configurations and includes the required HTML templates.
<?php
use insalyonController\ACME;
require_once __DIR__ . "/php/config/Bootstrap.php";
ACME::includeHTMLHeader();
ACME::includeHTMLBody();
ACME::loadACMEMod("FormExample.php");
ACME::includeHTMLFooter();
?>
Namespace Usage: The
ACME
class is included using theuse
statement.Bootstrap Initialization: The
Bootstrap.php
file is included to initialize the framework.Including HTML Templates: The HTML header, body, and footer templates are included using the respective
ACME
functions. These templates are located in themain/html
directory.Loading Modules: The
loadACMEMod
function is used to load a specific module from themain/mods
directory. In this example, theFormExample.php
module is loaded.
Loading Modules
To load a module in the ACME Framework, use the ACME::loadACMEMod
function. This function includes the specified module file from the main/mods
directory and executes its functionality.
Example
use insalyonController\ACME;
ACME::loadACMEMod("FormExample.php");
In this example, the FormExample.php
module is loaded and executed.
Examples
Version 1: Example Module Using cfg.ini
Configuration File
Step 1: Create the Example Module Script
Place this file in the main/mods
directory.
File: main/mods/ExampleMod.php
<?php
use insalyonController\ACME;
// Display a greeting from the configuration file using ACME static functions
$greeting = ACME::getCustomVariableValue('example.greeting');
if ($greeting) {
echo $greeting;
} else {
echo 'Hello, World!';
}
// Display all configuration keys using ACME static functions
$configKeys = ACME::getConfigurationKeys();
echo '<pre>';
print_r($configKeys);
echo '</pre>';
?>
Step 2: Create the Configuration File
Place this file in the insalyon/dsi/src/.env
directory.
File: insalyon/dsi/src/.env/cfg.ini
[example]
greeting = "Welcome to the ACME Framework!"
Step 3: Ensure the Configuration File Is Loaded
The ACME framework should already be set up to load the configuration file. Ensure configuration.php
or logconfiguration.php
is properly set to use the cfg.ini
file.
Step 4: Update the index.php
to Load the Example Module Script
Assuming the index.php
file is located in the main
directory.
File: main/index.php
<?php
use insalyonController\ACME;
require_once __DIR__ . '/php/config/Bootstrap.php';
ACME::includeHTMLHeader();
ACME::loadACMEMod('ExampleMod.php');
ACME::includeHTMLFooter();
?>
Version 2: Example Module Using Only Environment Variables
Step 1: Create the Example Module Script
Place this file in the main/mods
directory.
File: main/mods/ExampleModEnv.php
<?php
use insalyonController\ACME;
// Display a greeting from the environment variables using ACME static functions
$greeting = ACME::getCustomVariableValue('EXAMPLE_GREETING');
if ($greeting) {
echo $greeting;
} else {
echo 'Hello, World!';
}
// Display all configuration keys using ACME static functions
$configKeys = ACME::getConfigurationKeys();
echo '<pre>';
print_r($configKeys);
echo '</pre>';
?>
Step 2: Set Up Environment Variables
Set up environment variables directly in your server or local environment.
In Linux or macOS:
export EXAMPLE_GREETING="Welcome to the ACME Framework using environment variables!"
In Windows Command Prompt:
set EXAMPLE_GREETING=Welcome to the ACME Framework using environment variables!
In Windows PowerShell:
$env:EXAMPLE_GREETING="Welcome to the ACME Framework using environment variables!"
Step 3: Ensure Environment Variables Are Loaded
Make sure your environment variables are set before running your PHP application.
Step 4: Update the index.php
to Load the Example Module Script
Assuming the index.php
file is located in the main
directory.
File: main/index.php
<?php
use insalyonController\ACME;
require_once __DIR__ . '/php/config/Bootstrap.php';
ACME::includeHTMLHeader();
ACME::loadACMEMod('ExampleModEnv.php');
ACME::includeHTMLFooter();
?>
Explanation
ExampleMod.php:
- Script: Uses ACME static functions to access configuration values from
cfg.ini
. - ACME Static Functions:
ACME::getCustomVariableValue('example.greeting')
andACME::getConfigurationKeys()
.
- Script: Uses ACME static functions to access configuration values from
cfg.ini:
- Contains a simple configuration with a section
[example]
and a key-value pair for the greeting message.
- Contains a simple configuration with a section
ExampleModEnv.php:
- Script: Uses
ACME::getCustomVariableValue('EXAMPLE_GREETING')
to access environment variables directly.
- Script: Uses
Environment Variables:
- Set directly in your server or local environment without using a
.env
file.
- Set directly in your server or local environment without using a
index.php:
- Includes the HTML templates using
ACME
static functions and loads the example module scripts usingACME::loadACMEMod
.
- Includes the HTML templates using
By following these steps, you have created two full examples of an example module for the ACME Framework: one using a cfg.ini
configuration file and another using only environment variables accessed via ACME::getCustomVariableValue
.