Skip to content
Snippets Groups Projects

DOC v1.0

Merged
Charbel Fourelrequested to merge
dev_cfourel into develop
1 file
+ 623
0
Compare changes
  • Side-by-side
  • Inline
+ 623
0
@@ -4,6 +4,629 @@ _**A**utomated and **C**ustomizable **M**icroFramework **E**ngine_
![screenshot](https://i.ebayimg.com/images/g/YyMAAOSw6YtZU~Hg/s-l500.jpg)
## 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](https://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:
```bash
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`.
```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`:
```php
use insalyonController\ACME;
```
2. Call the desired static functions from the `ACME` class:
```php
ACME::functionName($parameters);
```
#### Function Descriptions
##### `CASAuth`
Forces CAS authentication for a CAS client.
```php
public static function CASAuth(string $CASVersion, string $CASHost, int $CASPort, string $CASContext)
```
##### `CASLogout`
Logs out a CAS client.
```php
public static function CASLogout()
```
##### `includeHTMLHeader`
Includes the HTML header template from the `main/html` directory.
```php
public static function includeHTMLHeader()
```
##### `includeHTMLBody`
Includes the HTML body template from the `main/html` directory.
```php
public static function includeHTMLBody()
```
##### `includeHTMLFooter`
Includes the HTML footer template from the `main/html` directory.
```php
public static function includeHTMLFooter()
```
##### `includeHTMLCustomTemplate`
Includes a custom HTML template from the `main/html` directory.
```php
public static function includeHTMLCustomTemplate(string $fileName)
```
##### `loadACMEMod`
Loads an ACME module from the `main/mods` directory.
```php
public static function loadACMEMod(string $fileName)
```
##### `validateFile`
Validates a file.
```php
public static function validateFile(string $fileError, string $fileSize, string $fileTmp)
```
##### `generateXLSDataStructure`
Generates an XLS data structure.
```php
public static function generateXLSDataStructure(string $file)
```
##### `sendHTTPRequest`
Sends an HTTP request.
```php
public static function sendHTTPRequest(string $url, string $method, string $body = "", array $params = [], array $header = [])
```
##### `log`
Logs a message with a specified level.
```php
public static function log(string $level, string $message)
```
##### `createCustomDAO`
Creates a custom DAO.
```php
public static function createCustomDAO(string $dbType, string $dbHost, string $dbName, string $dbUser, string $dbPassword)
```
##### `selectSQL`
Executes a SELECT SQL query.
```php
public static function selectSQL(string $query, array $params = [])
```
##### `insertSQL`
Executes an INSERT SQL query.
```php
public static function insertSQL(string $query, array $params = [])
```
##### `updateSQL`
Executes an UPDATE SQL query.
```php
public static function updateSQL(string $query, array $params = [])
```
##### `deleteSQL`
Executes a DELETE SQL query.
```php
public static function deleteSQL(string $query, array $params = [])
```
##### `executeQueryBatch`
Executes a batch of SQL queries.
```php
public static function executeQueryBatch(array $queriesAndParams)
```
##### `generateUUIDV5`
Generates a UUID v5.
```php
public static function generateUUIDV5(string $randomString)
```
##### `ldapAddNode`
Adds an LDAP node.
```php
public static function ldapAddNode(string $dn, array $entry)
```
##### `ldapSearch`
Searches an LDAP directory.
```php
public static function ldapSearch(string $dn, string $filter = "objectclass=*", array $attribs = [])
```
##### `ldapDeleteNode`
Deletes an LDAP node.
```php
public static function ldapDeleteNode(string $dn)
```
##### `ldapAddNodeAttributeAndValue`
Adds an attribute and value to an LDAP node.
```php
public static function ldapAddNodeAttributeAndValue(string $dn, array $modifs)
```
##### `ldapRemoveNodeAttribute`
Removes an attribute from an LDAP node.
```php
public static function ldapRemoveNodeAttribute(string $dn, array $modifs)
```
##### `ldapRemoveNodeAttributeValue`
Removes an attribute value from an LDAP node.
```php
public static function ldapRemoveNodeAttributeValue(string $dn, array $modifs)
```
##### `ldapReplaceNodeAttributeValue`
Replaces an attribute value of an LDAP node.
```php
public static function ldapReplaceNodeAttributeValue(string $dn, array $modifs)
```
##### `ldapBatchRequests`
Executes a batch of LDAP requests.
```php
public static function ldapBatchRequests(array $requests)
```
##### `getCustomVariableValue`
Gets the value of a custom variable.
```php
public static function getCustomVariableValue(string $key)
```
##### `getConfigurationKeys`
Gets the configuration keys.
```php
public static function getConfigurationKeys()
```
##### `CSVToArray`
Converts a CSV file to an array.
```php
public static function CSVToArray(string $fileName, int $length = 1000, string $separator = ",", string $enclosure = "\"", string $escape = null)
```
##### `arrayToCSV`
Converts an array to a CSV file.
```php
public static function arrayToCSV(string $fileName, array $datas, string $separator = ",", string $enclosure = "\"", string $escape = null)
```
##### `httpErrorHandler`
Handles HTTP errors.
```php
public static function httpErrorHandler(string $logMsg, string $httpCode, mixed $jsonAnswer)
```
##### `OIDCAuth`
Performs OpenID Connect authentication.
```php
public static function OIDCAuth()
```
##### `OIDCSignOut`
Signs out from OpenID Connect.
```php
public static function OIDCSignOut()
```
##### `getUserInfo`
Gets user information.
```php
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
<?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
```php
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
<?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`
```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
<?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
<?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:
```bash
export EXAMPLE_GREETING="Welcome to the ACME Framework using environment variables!"
```
In Windows Command Prompt:
```cmd
set EXAMPLE_GREETING=Welcome to the ACME Framework using environment variables!
```
In Windows PowerShell:
```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
<?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`.
## [Changelog versions](changelog.md)
## How to use ACME?
Loading