insalyon/acme

php framework developped by INSA Lyon

v2.0.7-alpha 2025-03-14 11:14 UTC

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

CC-BY-NC-4.0

• Charbel FOUREL
• Johan MAURICE
• Lucas DUPUY
• Aurelien Leygues

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

1. Presentation
2. ACME Framework Documentation
3. Examples
4. Usefull links

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

1. Configuration Management

   • Centralized Configuration: Managed via Configuration.php and LogConfiguration.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.

2. 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.

3. 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.

4. 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.

5. CSV Handling

   • CSVService.php: Offers methods to read from and write to CSV files, converting them to and from associative arrays.

6. Excel Handling

   • ExcelService.php: Supports reading from and writing to Excel files in various formats, converting Excel data to arrays and vice versa.

7. UUID Generation

   • UUIDv5Service.php: Generates version 5 UUIDs based on SHA-1 hashing, useful for creating deterministic unique identifiers.

8. CAS (Central Authentication Service) Integration

   • CASService.php: Implements CAS for single sign-on (SSO) authentication, enhancing security and user convenience.

9. OIDC (OpenID Connect) Integration

   • OIDCService.php: Provides OpenID Connect integration for authentication and authorization, allowing applications to verify user identities and obtain profile information.

10. File Validation

    • FileValidationService.php: Validates file uploads by checking file types, sizes, and other criteria to ensure files meet application requirements.

11. 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.

12. 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.

13. Modular Structure

    • Mods Directory: Organizes the functional code for the specific application being developed using the framework, promoting code reuse and maintainability.

14. 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

1. 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.

2. 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

1. Centralized Configuration

   • Centralized configuration ensures consistent application settings across different environments.
   • Use of Configuration.php and LogConfiguration.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.

2. 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.

Robust Error Handling

1. 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.

2. 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

1. 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.

2. 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.

3. File Validation

   • FileValidationService.php ensures that uploaded files meet specified criteria, preventing potential security risks associated with malicious files.

4. 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.

Flexibility

1. 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.

2. 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

1. 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.

2. Unified Interface

   • ACME.php provides a unified interface for accessing all key features, simplifying integration and usage.

Reliability

1. 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.

2. 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.

3. 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.

4. 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.

5. 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

1. Ensure you have Composer installed on your system. You can download it from getcomposer.org.
2. Navigate to the root directory of your project where the composer.json file is located.
3. 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

1. Navigate to the insalyon/dsi/src/.env directory.
2. Create a new file named cfg.ini.
3. Use the DEFAULT-cfg.ini file as a template to create your own cfg.ini.

   [section]
   key=value
   

4. 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

1. Include the ACME class in your script using use:

   use insalyonController\ACME;
   

2. 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();
?>

1. Namespace Usage: The ACME class is included using the use statement.

2. Bootstrap Initialization: The Bootstrap.php file is included to initialize the framework.

3. Including HTML Templates: The HTML header, body, and footer templates are included using the respective ACME functions. These templates are located in the main/html directory.

4. Loading Modules: The loadACMEMod function is used to load a specific module from the main/mods directory. In this example, the FormExample.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

1. ExampleMod.php:

   • Script: Uses ACME static functions to access configuration values from cfg.ini.
   • ACME Static Functions: ACME::getCustomVariableValue('example.greeting') and ACME::getConfigurationKeys().

2. cfg.ini:

   • Contains a simple configuration with a section [example] and a key-value pair for the greeting message.

3. ExampleModEnv.php:

   • Script: Uses ACME::getCustomVariableValue('EXAMPLE_GREETING') to access environment variables directly.

4. Environment Variables:

   • Set directly in your server or local environment without using a .env file.

5. index.php:

   • Includes the HTML templates using ACME static functions and loads the example module scripts using ACME::loadACMEMod.

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.

Usefull links

Changelog versions

How to use ACME?

With Docker + Docker compose

1. Without Docker: prepare your development environement

2. Without Docker: execute your development environement