From 4256b125555e0e2896c1ad22db66d53f9c6da6d8 Mon Sep 17 00:00:00 2001
From: skycel <cece.burst@gmail.com>
Date: Wed, 5 Feb 2025 01:07:25 +0100
Subject: [PATCH] =?UTF-8?q?=F0=9F=93=9D=20-=20Ajout=20de=20commentaires=20?=
 =?UTF-8?q?PHPDoc=20pour=20am=C3=A9liorer=20la=20documentation=20du=20code?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 CustomThemeTree.php   |  43 ++++++++++++---
 TemplateLoader.php    | 123 ++++++++++++++++++++++++++++++++++++++++++
 custom-theme-tree.php |   5 ++
 3 files changed, 165 insertions(+), 6 deletions(-)

diff --git a/CustomThemeTree.php b/CustomThemeTree.php
index b2a8b4c..5b7e464 100644
--- a/CustomThemeTree.php
+++ b/CustomThemeTree.php
@@ -5,6 +5,11 @@ namespace Skycel\CustomTree;
 use WP_Theme;
 use Error;
 
+/**
+ * Class for managing custom theme directory structures and settings.
+ * Provides functionality for initializing themes, creating custom directories,
+ * handling templates and stylesheets, and loading configurations.
+ */
 class CustomThemeTree extends TemplateLoader {
     public WP_Theme $theme;
 
@@ -35,11 +40,14 @@ class CustomThemeTree extends TemplateLoader {
 
     public function __construct($dirs = null, $config_file = "theme.php") {
 
-        wp_set_template_globals();
-
-        if ($dirs) {
-            $this->default = array_merge_recursive_distinct($this->default, $dirs);
-        }
+    /**
+     * Constructor method to initialize theme settings and configuration.
+     * Handles the creation of a configuration directory and file if they do not exist,
+     * and merges custom configurations if enabled.
+     *
+     * @return void
+     */
+    public function __construct() {
 
         $this->theme = wp_get_theme();
         $this->theme_directory = $this->theme->get_theme_root() . "/" . get_template();
@@ -56,6 +64,11 @@ class CustomThemeTree extends TemplateLoader {
         $this->init();
     }
 
+    /**
+     * Initializes custom directories, required files, and sets up template and component loaders.
+     *
+     * @return void
+     */
     protected function init(): void
     {
         $this->create_custom_directories();
@@ -69,7 +82,7 @@ class CustomThemeTree extends TemplateLoader {
             add_filter("{$type}_template", [TemplateLoader::class, 'getTemplates'], 10, 3);
         }
 
-        // Built-in Wordpress component loader
+        // Component loader
         $default_components = [
             "header", "footer",
             "sidebar", "search_form"
@@ -79,6 +92,11 @@ class CustomThemeTree extends TemplateLoader {
         }
     }
 
+    /**
+     * Creates custom directories for templates and stylesheets, including handling subdirectories and optional .gitkeep files.
+     *
+     * @return void
+     */
     private function create_custom_directories(): void {
         // Make all directories for templates
 
@@ -108,6 +126,13 @@ class CustomThemeTree extends TemplateLoader {
         }
     }
 
+    /**
+     * Creates a specified directory within the theme directory. If the directory does
+     * not exist, it creates it and optionally adds a .gitkeep file if enabled.
+     *
+     * @param string $dir_name The name of the directory to be created.
+     * @return string|Error The path to the created directory or an error object if the creation fails.
+     */
     private function create_directory($dir_name): string|Error {
         if (!file_exists($this->theme_directory . "/" . $dir_name)) {
             $success = mkdir($this->theme_directory . "/" . $dir_name);
@@ -125,7 +150,13 @@ class CustomThemeTree extends TemplateLoader {
         return $this->theme_directory . "/" . $dir_name;
     }
 
+    /**
+     * Creates required template and stylesheet files if they do not already exist.
+     *
+     * @return void
+     */
     private function create_required_files(): void {
+        // Create CustomThemeTree required files
         if (!file_exists($this->theme_directory . "/" . TEMPLATES_DIR . "/index.php")) file_put_contents($this->theme_directory . "/" . TEMPLATES_DIR . "/index.php", "<?php\n\necho '<h1 style=\'text-align:center;\'>New Files tree is operational !</h1>';");
         if (!file_exists($this->theme_directory . "/" . TEMPLATES_DIR . "/components/header.php")) file_put_contents($this->theme_directory . "/" . TEMPLATES_DIR . "/components/header.php", "<?php\n\n");
         if (!file_exists($this->theme_directory . "/" . TEMPLATES_DIR . "/components/footer.php")) file_put_contents($this->theme_directory . "/" . TEMPLATES_DIR . "/components/footer.php", "<?php\n\n");
diff --git a/TemplateLoader.php b/TemplateLoader.php
index 040b79e..66e287f 100644
--- a/TemplateLoader.php
+++ b/TemplateLoader.php
@@ -5,10 +5,20 @@ namespace Skycel\CustomTree;
 use Error;
 use WP_Error;
 
+/**
+ * Handles loading and rendering of WordPress templates based on their type
+ * and subdirectories. Supports various template types, such as pages, archives,
+ * taxonomies, components, and more.
+ */
 class TemplateLoader {
 
     static array $templates_parts;
 
+    /**
+     * Initializes the template rendering process.
+     *
+     * @return void
+     */
     protected function init() {
         add_filter("template_render", function ($templates_path, $type) {
             foreach ($templates_path as $path) {
@@ -22,6 +32,15 @@ class TemplateLoader {
         }, 10, 2);
     }
 
+    /**
+     * Retrieves and processes templates based on the specified type and template data.
+     *
+     * @param string $template The primary template name or path.
+     * @param string $type The type of template being requested (e.g., "home", "frontpage").
+     * @param array $templates A list of additional template names or paths.
+     *
+     * @return void
+     */
     public static function getTemplates($template, $type, $templates) {
         if ($type === "home" || $type === "frontpage") $type = "page";
         $key = (int)$type !== 0 ? "errors" : preg_replace("/y$/m", "ie", $type)."s";
@@ -36,6 +55,14 @@ class TemplateLoader {
         do_action("template_render", self::$templates_parts, $type);
     }
 
+    /**
+     * Processes templates and builds template parts based on the given type and path.
+     *
+     * @param string $template_path The base path for the templates.
+     * @param string $type The type prefix to be removed from template names.
+     * @param array $templates List of templates to process.
+     * @return void
+     */
     public static function getDefault($template_path, $type, $templates): void {
         foreach ($templates as $t) {
             $t = preg_replace("/^$type-/m", "", $t);
@@ -44,26 +71,74 @@ class TemplateLoader {
     }
 
 
+    /**
+     * Retrieves pages based on the provided template path, type, and templates.
+     *
+     * @param string $template_path The path to the template.
+     * @param string $type The type of the template.
+     * @param array $templates The list of templates.
+     * @return void
+     */
     public static function getPages($template_path, $type, $templates): void {
         self::getDefault($template_path, $type, $templates);
     }
 
+    /**
+     * Retrieves and processes archive templates.
+     *
+     * @param string $template_path Path to the template.
+     * @param string $type Type of template.
+     * @param array $templates List of templates.
+     * @return void
+     */
     public static function getArchives($template_path, $type, $templates): void {
         self::getDefault($template_path, $type, $templates);
     }
 
+    /**
+     * Retrieves authors based on the provided parameters.
+     *
+     * @param string $template_path The path of the template.
+     * @param string $type The type of the template.
+     * @param array $templates The list of templates.
+     * @return void
+     */
     public static function getAuthors($template_path, $type, $templates): void {
         self::getDefault($template_path, $type, $templates);
     }
 
+    /**
+     * Retrieves errors by processing templates with a default method.
+     *
+     * @param string $template_path Path to the template directory.
+     * @param string $type Type of templates being processed.
+     * @param array $templates List of template files.
+     * @return void
+     */
     public static function getErrors($template_path, $type, $templates): void {
         self::getDefault($template_path, $type, $templates);
     }
 
+    /**
+     * Retrieves and processes category templates.
+     *
+     * @param string $template_path Path to the template directory.
+     * @param string $type Type of the template.
+     * @param array $templates List of templates to process.
+     * @return void
+     */
     public static function getCategories($template_path, $type, $templates): void {
         self::getDefault($template_path, $type, $templates);
     }
 
+    /**
+     * Generates an array of single templates with processed paths and stores them in the template parts.
+     *
+     * @param string $template_path The base path to the templates.
+     * @param string $type The type of template being processed.
+     * @param array $templates A list of template names to process.
+     * @return void
+     */
     public static function getSingles($template_path, $type, $templates): void {
         $tmpl = [];
 
@@ -83,6 +158,14 @@ class TemplateLoader {
         self::$templates_parts = $tmpl;
     }
 
+    /**
+     * Generates and sets attachment file paths based on provided templates.
+     *
+     * @param string $template_path Base path for the templates.
+     * @param string $type Type of attachment (not explicitly used in method logic).
+     * @param array $templates List of template filenames.
+     * @return void
+     */
     public static function getAttachments($template_path, $type, $templates): void {
         foreach($templates as $i => $t) {
             $folder = "";
@@ -94,6 +177,15 @@ class TemplateLoader {
         }
     }
 
+    /**
+     * Updates the list of templates with taxonomy-specific paths based on the provided data.
+     *
+     * @param string $template_path The base path to the templates.
+     * @param string $type The type of taxonomy being processed.
+     * @param array $templates An array of template file names to process.
+     *
+     * @return void
+     */
     public static function getTaxonomies($template_path, $type, $templates): void {
         $tmpl = [];
 
@@ -112,19 +204,50 @@ class TemplateLoader {
         self::$templates_parts = $tmpl;
     }
 
+    /**
+     * Retrieves tags based on the provided parameters.
+     *
+     * @param string $template_path The path to the template.
+     * @param string $type The type of the template.
+     * @param array $templates The list of templates.
+     * @return void
+     */
     public static function getTags($template_path, $type, $templates): void {
         self::getDefault($template_path, $type, $templates);
     }
 
+    /**
+     * Generates date-based template paths and appends them to the templates parts list.
+     *
+     * @param string $template_path The base path for the templates.
+     * @param string $type The type of template to append.
+     * @param array $templates Not used in this method.
+     * @return void
+     */
     public static function getDates($template_path, $type, $templates): void {
         self::$templates_parts[] = is_year() ?  $template_path . "/year.php" : (is_month() ? $template_path ."/month.php" : $template_path . "/day.php");
         self::$templates_parts[] = $template_path . "/$type.php";
     }
 
+    /**
+     * Appends a search template path to the templates array.
+     *
+     * @param string $template_path The base path to the templates.
+     * @param string $type The type of the search template.
+     * @param array $templates The list of existing templates.
+     * @return void
+     */
     public static function getSearchs($template_path, $type, $templates): void {
         self::$templates_parts[] = $template_path . "/$type.php";
     }
 
+    /**
+     * Retrieves and processes the components associated with the current filter hook.
+     *
+     * @param string $name The name of the component being retrieved.
+     * @param mixed|null $args Optional. Additional arguments passed to the component.
+     * @return void
+     */
     public static function getComponents($name, $args = null) {
         $hook_name = current_filter();
 
diff --git a/custom-theme-tree.php b/custom-theme-tree.php
index a9f935a..f27fbf7 100644
--- a/custom-theme-tree.php
+++ b/custom-theme-tree.php
@@ -23,6 +23,11 @@ function test_plugin(): void {
         new CustomThemeTree(\CUSTOMTREE);
     }
 
+/**
+ * Loads the custom tree plugin if enabled and properly configured.
+ *
+ * @return void
+ */
 }
 add_action("after_setup_theme", "test_plugin");