HOME | DOCUMENTATION

📕 The Basics

Introduction
Controlers
Rooting
CSRF Protection
Layouts
Paths
Heredia

Commande list
Generate chatbot
Generate APIs

Mail
Excel files

# Introduction

This is a set of functions, deemed simple and basic, that are essential for successfully carrying out your projects. They are included in the Epaphrodites framework. These functionalities provide a solid and efficient foundation, facilitating the execution of crucial tasks in the development process.
Mastering these functions will enable you to expedite creation and enhance the quality of your projects. Their modular nature ensures easy integration across various components. Whether you're building a lightweight tool or a complex system, these functions adapt seamlessly to your needs.

# Controlers

Epaphrodites offers two distinct types of controllers: controllerMaps, which centralizes and organizes all the application's controllers, and controllers, which handle specific pages and actions. This clear separation simplifies maintenance, improves code readability, and allows for better application structure.
Each controller comes with a predefined structure, allowing you to focus directly on your application's logic. You can customize the generated files to suit your architectural needs. This streamlined process significantly reduces boilerplate code and accelerates development.

This is the command to generate a controller. You can use your terminal or PowerShell for those using Windows OS. The generated controller will be located in the bin/controllers/controllers directory. You can then customize it according to your project.
For example, if you want to create a controller named testController in the bin/controllers/controllers directory, you can use the following command:

php heredia create:controller testController

Here is an example of a controller generated from the previous command :

                        
                        
                            <?php
namespace Epaphrodites\controllers\controllers;
use Epaphrodites\controllers\switchers\MainSwitchers;
final class testController extends MainSwitchers
{
private object $msg;
                            /**
 * Initialize object properties when an instance is created
 * @return void
*/
public final function __construct() 
{
  $this->initializeObjects();
}
                            /**
 * Start exemple page
 * @param string $html
 * @return void
*/
public final function exemplePages(string $html): void
{
   $this->views($html, [], false);
}
                            /**
 * Initialize object properties when an instance is created
 * @return void
*/
 private function initializeObjects(): void
{
  $this->msg = $this->getFunctionObject(static::initNamespace(), 'msg'); 
}
}

The controllerMap() function defines a mapping between a URL key and a specific controller. For each key, it associates a controller instance, the method to execute, a flag indicating whether authentication is required, the name of the folder containing the corresponding HTML views, and the root path to the public directory. This centralized approach simplifies page routing and access management within the application. It also allows the code to be structured in a modular and scalable way by clearly separating business logic, views, and access rules.

You must then verify that your controller is correctly defined in the controller mapping file: bin/controllers/controllerMap/controllerMap.php.
This will ensure that your application uses the correct controller to handle incoming requests.

                        
                        
                            <?php
namespace Epaphrodites\controllers\controllerMap;
use Epaphrodites\controllers\controllers\api;
use Epaphrodites\controllers\controllers\testController;
trait controllerMap
{
/**
 * Returns an array mapping controllers to their respective instances and methods.
 * 'SwitchControllers' Regular switch
 * 'SwitchApiControllers' Dedicated API switch 
 * @return array
*/
private function controllerMap(): array
{
  return [ 
    "api" => [ new api, 'SwitchApiControllers' , false ],
    'test' => [ new testController, 'SwitchControllers' , true, 'testFolder', _DIR_ADMIN_TEMP_ ]
  ];
     }}

Key	Controller Instance	Method	Auth Required	HTML Folder	Public Root Path
`"api"`	`new api`	`SwitchApiControllers`	false	—	—
`"test"`	`new testController`	`SwitchControllers`	true	`"testFolder"`	`_DIR_ADMIN_TEMP_`

# Rooting

View functions are used to display HTML pages. They serve as the link between your application's logic and the user interface, ensuring that dynamic content is properly rendered on the frontend.

To quickly generate a view function within a controller, run the command heredia add:view from the terminal or PowerShell. By default, views are stored in the directory of the controller you selected during the generation phase. This ensures a clear organization of your project's structure, keeping related components grouped together. You can easily modify the generated view to fit your application's specific needs.

For example, if you want to create a view function named exemplePages in the main controller, you can use the following command :

php heredia add:view main exemple_pages

After generating the view function, insert this : $this->views( $html , []); it into your function like this :

                    
                    
                        /**
 * Start exemplePages
 * @param string $html
 * @return void
*/
public final function exemplePages(string $html): void
{
    $this->views( $html , [], false);
}

Please note that:
DIR_MAIN_TEMP refers to the public/views/main directory,
DIR_ADMIN_TEMP refers to public/views/admin.
Additionally, you also have the option to modify the various paths or even define your own constant within the bin\config\SetDirectory.php file and then use it

# CSRF Protection

Epaphrodite-framework automatically generates a CSRF token for every active user session within the application. This token, crucial for security purposes, acts as an authentication key, verifying the user's identity during their interactions. It is securely integrated into the user's session and refreshes with each new session, providing heightened protection against any fraudulent access attempts by malicious applications.

                    
                    
                        <form method="POST" action="{{ __path('login') }}">
  {{ __csrf() }} 
                        <!-- Equivalent to... -->
   <input type="hidden" name="token_csrf" value="n1k5AUnW8hcDVTtqVTNU97bkywg1wJx2rIIW9zJKaO4N2qHgHryfR4y2UXMA0BM8hQKjsy" required />
</form>

# Layouts

Epaphrodites offers several simple and dynamic methods to efficiently manage front-end layouts. Among these methods are template management, widget management, and display management. These various arrangements are handled by specific functions located in configuration files, situated in bin/epaphrodites/EpaphMozart/templatesConfig/LayoutsConfig.php. Each function is adapted according to the layout used, providing precise customization for each layout configuration. Moreover, you have the freedom to personalize these functions and add new layouts based on your project's specific requirements, thereby offering considerable flexibility.

                    
                    
                        /**
 * Get login template
 * @return string
*/
public function login():string
{
    return "layouts/template/__default_login.html.twig";
}

                    
                    
                        /**
 * Get default template ( when user are connected )
 * @return string
*/
public function admin(?int $key = null):string
{
    return 
        [
          1 => "layouts/template/__default.super.admin.html.twig",
          2 => "layouts/template/__default.all.centraladmin.html.twig",
          3 => "layouts/template/__default.all.users.html.twig"
        ];
}

                    
                    
                        /**
 * Get default template ( forms template )
 * @return string
*/
public function forms():string
{
    return "layouts/widgets/__widgets.forms.html.twig";
}

# Heredia

The Epaphrodites framework provides a variety of executable commands through the terminal or PowerShell (for Windows users). Each of these commands plays a crucial role in managing, creating files, as well as in developing both simple and complex classes and functions. They form the fundamental pillars for a smooth and sophisticated manipulation of this framework.

Heredia command list

The following command allows you to display all commands related to Heredia. Use your terminal or PowerShell for those with Windows OS :

php heredia list

Command	Description
`list`	List all commands.
`migrate`	Run the database migrations.
`add:Right`	Add a new user right.
`add:c`	Add your own C native extensions.
`add:python`	Add Python files.
`add:cmd`	Add a new command.
`add:module`	Add a new module for users rights
`add:sql`	Add an SQL request.
`add:view`	Add a view function in controler.
`copy:table`	Copy database tables for other database.
`create:chatbot`	Add a new chatbot.
`create:controller`	Create a new controller.
`create:db`	Add a new database.
`create:front`	Create front views (html file).
`create:requestfile`	Create a new request file.
`create:users`	Update user password and type.
`drop:db`	Command to drop a database.
`make:api`	Make a new API.
`make:schema`	Command to make schema.
`make:seeder`	Command to make a new seeding.
`pip:component`	Install Python components.
`run:server`	Run the server.
`update:driver`	Create the first driver.

Generate chatbot

A chatbot is a computer program designed to simulate conversations with human users on the internet. Its main goal is to provide assistance or information in an automated and interactive manner. These tools can be deployed across various fields such as customer service, task automation, user engagement, information gathering, education, and transaction facilitation. By providing instant responses at any time, chatbots help improve user experience, reduce operational costs, and increase the efficiency of services.

Epaphrodites has two chatbot models. The first model was entirely designed in PHP, while the second model was developed in Python. Each model operates differently, based on distinct algorithms and training modes. These two models complement each other, providing a wide range of responses to users' questions and needs. You have the option to customize and adapt them according to the specific requirements of your projects.

chatbot model one

The following command allows you to generate a chatbot and integrate it into the chats controller. Use your terminal or PowerShell for those using Windows OS. Afterwards, you can customize it according to your project. :

php heredia create:chatbot chatbot_name

Here is an example of the chatbot view generated from the previous command. Additionally, two other files named after your chatbot have also been generated (bin/database/datas/json/modelOne/chatbot_name.json and bin/database/datas/json/modelOne/userchatbot_name.json). It's up to you to customize them according to your project :

                    
                    
                        /**
 * start chatbot_name chatBot
 * @param string $html
 * @return void
*/
public final function chatbotNameStarted(string $html): void
{
    
    if (static::isValidMethod()){

      $send = static::isAjax('__send__') ? static::isAjax('__send__') : '';

      $result = $this->initNamespace()['bot']->herediaBotModeleOne($send , $chatBotName);

      echo $this->initNamespace()['ajax']->chatMessageContent($result , $send , $chatBotName);

      return;
    }

    $this->views( $html, [], false);
}

It's in the bin/database/datas/json/modelOne/chatbot_name.json file where you can define the questions asked by the chatbot along with their responses. This configuration is crucial in defining the behavior and interactions of the chatbot with users.

chatbot model two

The following code demonstrates the use of chatbot model two. We emphasize that this model has been entirely designed in Python, so its usage requires prior installation of Python in the environment variables. Otherwise, this could result in errors. Make sure you have also properly configured the required dependencies for it to function correctly.

                    
                    
                        /**
 * start chatbot model two
 * @param string $html
 * @return void
*/
public final function chatbotModelTwoStarted(string $html): void
{
    
    if (static::isValidMethod()){

      $send = static::isAjax('__send__') ? static::isAjax('__send__') : '';

      $result = $this->initNamespace()['bot']->chatBotModeleTwoProcess( $send );

      echo $this->initNamespace()['ajax']->chatMessageContent($result , $send );

      return;
    }

    $this->views( $html, [], false);
}

Make APIs

The creation of an API is of paramount importance for standardizing data exchanges, thus promoting seamless integration across various computing platforms. Additionally, it provides an abstraction layer that simplifies the underlying complexity of systems, thereby facilitating their maintenance and scalability. A well-designed API enables developers to focus on the core business logic of their applications, without having to worry about the implementation details of external systems. Through the heredia make:api command, Epaphrodites now offers the ability to simply generate robust and flexible APIs, streamlining the development process.

php heredia make:api your_api_name

After executing the previous command, the code will be immediately generated in this controller bin/controllers/controllers/api.php. You can then customize this code according to the specific needs of your application. Below is the code that will be generated.

                        
                        
                            /**
 * make your api
 * @return void
*/
public final function yourApiName(): void
{

         $Result = [];
         $code = 400;

    if(static::isValidApiMethod()){

         $code = 200;
         $Result = ['this' , 'is' , 'api' , 'result' , 'test'];
    }

    return $this->Response->JsonResponse($code, $Result);
}

# Paths

Epaphrodites-framework manages URL construction in a simple and efficient manner. This method allows for easy generation of URL paths using a user-friendly and optimized approach. It streamlines URL creation by providing effective tools, thereby facilitating the manipulation and dynamic generation of links. This approach contributes to smooth URL management, offering an intuitive way to create and handle pathways, crucial for navigation and link structuring within an application or website.

Standard front URL link

                    
                    
                        <a href = "{{ __path('login') }}">
I'm a new link
</a>

Generate front URL link

                    
                    
                        <a href = "{{ __pathId('login' , { 'key': value } ) }}">
I'm a new link
</a>

When the file you're targeting is within a subdirectory named users using the @ symbol to differentiate between the folder name and the file name proves to be convenient. For instance: users@login. This method simplifies navigation within nested folder structures, especially for specifying a precise path to a file.

                    
                    
                        <a href = "{{ __path('users@login') }}">
I'm a new link
</a>

# Sending Email

Efficiently managing email dispatch is a crucial element in any web project. Epaphrodites provides a range of robust, flexible, and specifically optimized functions and libraries for this purpose. Additionally, to simplify configuration, we offer a bin/config/email.ini file allowing easy customization of these functionalities according to your specific needs.

Mail email.ini config

                    
                
                    
                             [email]

# SMTP server address
     SERVER = "smtp-fr.securemail.pro"

# User for SMTP authentication
     USER = "email_address"

# Password associated with the email address for SMTP authentication
     PASSWORD = "password"

# Port used for SMTP connection
     PORT = 587

# Return email address, typically used as the default sender
     HIDE_EMAIL = "do-not-reply@epaphrodite.org"

# Title used in emails, can be the sender's name or a specific indication
     TITLE = "EPAPHRODITE"

Parameter	Example Value	Description
`SERVER`	"smtp-fr.securemail.pro"	SMTP server address for sending emails
`USER`	"email_address"	Identifier for SMTP authentication (full email address)
`PASSWORD`	"password"	Password associated with the email address for authentication
`PORT`	587	SMTP connection port (typically 587 for TLS or 465 for SSL)
`HIDE_EMAIL`	"do-not-reply@epaphrodite.org"	Sender email address displayed (can differ from the authentication email)
`TITLE`	"EPAPHRODITE"	Name displayed as the sender in email clients

Using exemples

The Epaphrodites framework supports multiple programming languages. It offers two types of functions for sending emails: one entirely written in Python and the other in PHP. By default, the PHP function is used. This flexibility allows developers to choose the method best suited to their needs. To use the Python function instead, simply specify __EMAIL_METHOD__ as python in the configuration file located at bin\config\SetDirectory.php

🛠️ Default email configuration

define( '__EMAIL_METHOD__', 'php' );

📝 Sending email function exemple

                    
                    
                        /**
 * Send Email
 * @param array $contacts [ 'test@gmail.com','test2@gmail.com']
 * @param string $msgHeader "New email"
 * @param string $msgContent "I'am a new email"
 * @param string $file "test.png"
 * @return bool
*/
$send = $this->initNamespace()['mail']->sendEmail($contacts, $msgHeader, $msgContent, $file)

Parameter	Type	Description	Example
`$contacts`	array[string]	Array of recipient email addresses	['test@gmail.com', 'test2@gmail.com']
`$msgHeader`	string	Email subject line	`"New email notification"`
`$msgContent`	string	HTML or plain text content of the email	`"Hello, this is a test message."`
`$file`	string	[Optional] Path to file attachment	`"/uploads/test.png"`
`@return`	bool	Returns `true` on successful send, `false` on failure

ℹ️ Best Practices

Validate all email addresses before sending
Use HTML content for rich formatting when needed
For large attachments (>5MB), consider cloud storage links instead
Implement error logging for failed sends
Set appropriate Content-Type headers for HTML emails

# Excel Files

Epaphrodites offers a range of features specifically designed to simplify the management of importing and exporting Excel files.
Our solution allows you to easily handle these files, perform advanced operations, and ensure smooth data integration. Furthermore, our tools provide optimal adaptability, ensuring an efficient and intuitive experience in processing these documents.

Import excel files

For managing Excel file imports, Epaphrodites provides you with two types of functions: one entirely developed in PHP, and the other in Python. This dual approach allows you to choose the most suitable solution based on your project's requirements and server environment. The PHP version is lightweight and easy to integrate into existing workflows. The Python version offers enhanced performance for processing large datasets and supports more advanced manipulation features.

This is an exemple of function that allows you to import an Excel file. The function is designed to handle the importation of Excel files, making it easier to work with data stored in this format. The function takes a file name as a parameter and returns an array or boolean value based on the success of the import operation. This flexibility allows you to easily integrate Excel data into your application, whether for analysis, reporting, or other purposes.

For PHP exemple :

                    
                    
                        /**
 * Import excel file (for php)
 * @param string $ExcelFiles
 * @param string $keyName
 * @return array
*/
$importArray = $this->initNamespace()['import']->importExcelFiles( static::getFileName('__file__'), '__file__')

For PYTHON exemple :

                    
                    
                        /**
 * Import excel file (for python)
 * @param string $ExcelFiles
 * @param string $keyName
 * @return array
*/
$importArray = $this->initNamespace()['import']->importLargeExcelFiles( static::getFileName('__file__'), '__file__')

Export excel files

                    
                    
                        /**
 * Export excel file
 * @param array $header ['NAME' , 'SURNAME' , 'AGE']
 * @param array $content ['name' , 'surname' , 'age']
 * @param string $title "user_list"
 * @param string $type "xlsx"
 * @return void
*/
$this->initNamespace()['export']->exportExcelFiles( $header, $content, $title , $type )

Previous Next