diff --git a/src/Controllers/sLangController.php b/src/Controllers/sLangController.php index 0c9fc13..31c0f4e 100644 --- a/src/Controllers/sLangController.php +++ b/src/Controllers/sLangController.php @@ -29,9 +29,10 @@ public function index(): View } /** - * Show tabs resource + * Render tabs resource * - * @return View + * @param array $params Additional parameters for rendering the tabs view + * @return View The rendered tabs view */ public function tabs($params = []): View { @@ -54,10 +55,10 @@ public function tabs($params = []): View } /** - * Preparing Resource Fields + * Prepare fields for content * - * @param $content array - * @return array + * @param array $content Array containing the content data + * @return array Prepared array containing the content data with language-specific fields and menu values */ public function prepareFields(array $content): array { @@ -107,11 +108,11 @@ public function prepareFields(array $content): array } /** - * Recording resource translations + * Set language content for a resource * - * @param int $resourceId - * @param string $langKey - * @param array $fields + * @param int $resourceId The ID of the resource + * @param string $langKey The language key + * @param array $fields An associative array of fields and their values to update or create * @return void */ public function setLangContent(int $resourceId, string $langKey, array $fields): void @@ -120,9 +121,13 @@ public function setLangContent(int $resourceId, string $langKey, array $fields): } /** - * List of DB translations + * Retrieve translations from the database + * + * Returns a paginated collection of translations based on the provided search keyword, if present. + * If no search keyword is provided, all translations are retrieved. + * Translations are ordered by descending `tid` (translation ID). * - * @return array + * @return \Illuminate\Contracts\Pagination\Paginator */ public function dictionary() { @@ -142,10 +147,10 @@ public function dictionary() } /** - * Set default language + * Set the default language * - * @param $value string - * @return mixed + * @param string $value The value to set as the default language. + * @return bool Returns true if the default language was successfully set; otherwise, returns false. */ public function setLangDefault($value) { @@ -159,10 +164,10 @@ public function setLangDefault($value) } /** - * Set default language visibility + * Set the default language show value * - * @param $value string - * @return mixed + * @param int $value The new value for the default language show + * @return bool Returns true if the update of the table setting is successful, false otherwise */ public function setLangDefaultShow($value) { @@ -172,10 +177,10 @@ public function setLangDefaultShow($value) } /** - * Set site language list + * Set the language configuration * - * @param $value array - * @return mixed + * @param mixed $value The value to set for the language configuration + * @return bool Returns true if the language configuration was successfully set, otherwise false */ public function setLangConfig($value) { @@ -200,10 +205,10 @@ public function setLangConfig($value) } /** - * Set list of languages for frontend + * Set the frontend languages in the system configuration * - * @param $value array - * @return mixed + * @param mixed $value An array of language codes or a single language code + * @return bool True if the frontend languages were successfully updated, false otherwise */ public function setLangFront($value) { @@ -228,10 +233,10 @@ public function setLangFront($value) } /** - * Set on/off language module + * Set the status of the language module * - * @param $value string - * @return mixed + * @param int $value The value indicating the status of the language module (0 for off, 1 for on) + * @return bool Whether the update to the "s_lang_enable" field was successful */ public function setOnOffLangModule($value) { @@ -241,7 +246,13 @@ public function setOnOffLangModule($value) } /** - * Modifying table fields + * Modify translation tables and files + * + * This method modifies the translation tables and files based on the language configuration. + * It adds missing language columns to the translation table and creates empty JSON files for missing languages. + * After making the necessary modifications, it clears the cache. + * + * @return bool True if the tables and files were successfully modified, false otherwise. */ public function setModifyTables() { @@ -291,9 +302,9 @@ public function setModifyTables() } /** - * Parsing Translations in Blade Templates + * Parse blade views to extract translations and add them to the database if necessary * - * @return bool + * @return void */ public function parseBlade(): void { @@ -342,11 +353,11 @@ public function parseBlade(): void } /** - * Get automatic translation + * Set automatic translation for a phrase * - * @param $source - * @param $target - * @return string + * @param string $source The source phrase to translate + * @param string $target The target language to translate into + * @return string The translated phrase */ public function setAutomaticTranslate($source, $target): string { @@ -370,12 +381,13 @@ public function setAutomaticTranslate($source, $target): string } /** - * Update translation field + * Updates the translation for a specific phrase. + * + * @param string $source The source phrase to update. + * @param string $target The translation field to update. + * @param string $value The new translation value. * - * @param $source - * @param $target - * @param $value - * @return bool + * @return bool True if the translation was successfully updated, false otherwise. */ public function updateTranslate($source, $target, $value): bool { @@ -395,10 +407,21 @@ public function updateTranslate($source, $target, $value): bool } /** - * Save new translate and return HTML + * Saves the translation for a specific phrase. + * + * @param array $data An array containing the translation data. + * The array structure should be as follows: + * [ + * 'translate' => [ + * 'key' => 'the phrase key', + * 'field1' => 'the translation value for field1', + * 'field2' => 'the translation value for field2', + * ... + * ] + * ] * - * @param array $data - * @return string|void + * @return array|null The updated element row if the translation was successfully saved, + * null otherwise. */ public function saveTranslate(array $data) { @@ -416,11 +439,12 @@ public function saveTranslate(array $data) } /** - * Display render + * Renders a view with optional data. * - * @param string $tpl - * @param array $data - * @return bool + * @param string $tpl The name of the template to render. + * @param array $data Optional data to pass to the template. + * + * @return Illuminate\View\View The rendered view. */ public function view(string $tpl, array $data = []) { @@ -428,10 +452,11 @@ public function view(string $tpl, array $data = []) } /** - * Get html element for row table + * Generates the HTML table row for a data element. + * + * @param object $data The data element to generate the row for. * - * @param $data - * @return string + * @return string The HTML table row. */ protected function getElementRow($data) { @@ -461,7 +486,11 @@ protected function getElementRow($data) } /** - * Get html element for TV parameters for Resource in adminpanel + * Retrieves the HTML output of the template variables for a specific content. + * + * @param array $params The parameters for retrieving the template variables. + * + * @return string The HTML output of the template variables. */ protected function getTvsHtml($params) { @@ -755,11 +784,12 @@ protected function getTvsHtml($params) } /** - * Update data in system settings table + * Updates the value of a specific setting in the database table 'system_settings'. * - * @param $name string - * @param $value string - * @return mixed + * @param string $name The name of the setting to update. + * @param string $value The new value to be set for the setting. + * + * @return bool True if the setting was successfully updated, false otherwise. */ protected function updateTblSetting($name, $value) { @@ -769,7 +799,9 @@ protected function updateTblSetting($name, $value) } /** - * Update translation files + * Updates the language files based on the current translations. + * + * @return void */ protected function updateLangFiles(): void { diff --git a/src/Models/sLangContent.php b/src/Models/sLangContent.php index 848460c..29e64f2 100644 --- a/src/Models/sLangContent.php +++ b/src/Models/sLangContent.php @@ -11,12 +11,12 @@ class sLangContent extends Eloquent\Model protected $fillable = ['resource', 'lang', 'pagetitle', 'longtitle', 'description', 'introtext', 'content', 'menutitle', 'seotitle', 'seodescription']; /** - * Get the content item with lang and original fields + * Add the language and template variable fields to the query * - * @param Builder $query - * @param string $locale - * @param array $tvNames - * @return Builder + * @param Builder $query The query builder instance + * @param string $locale The language locale + * @param array $tvNames The array of template variable names + * @return Builder The modified query builder instance */ public function scopeLangAndTvs($query, $locale, $tvNames = []) { @@ -24,7 +24,24 @@ public function scopeLangAndTvs($query, $locale, $tvNames = []) $query->addSelect('s_lang_content.longtitle as longtitle', 's_lang_content.description as description'); $query->addSelect('s_lang_content.introtext as introtext', 's_lang_content.content as content'); $query->addSelect('s_lang_content.menutitle as menutitle'); + $query->selectTvs($tvNames); + return $query->addSelect('site_content.pagetitle as pagetitle_orig', 'site_content.longtitle as longtitle_orig') + ->addSelect('site_content.description as description_orig', 'site_content.introtext as introtext_orig') + ->addSelect('site_content.content as content_orig', 'site_content.menutitle as menutitle_orig') + ->leftJoin('site_content', 's_lang_content.resource', '=', 'site_content.id') + ->where('lang', '=', $locale); + } + + /** + * Adds TV selections to the query based on the given TV names. + * + * @param \Illuminate\Database\Query\Builder $query The database query builder instance + * @param array $tvNames The array of TV names to select + * @return \Illuminate\Database\Query\Builder The modified query builder instance + */ + public function scopeSelectTvs($query, $tvNames = []) + { if (count($tvNames)) { foreach ($tvNames as $tvName) { $query->addSelect( @@ -39,19 +56,14 @@ public function scopeLangAndTvs($query, $locale, $tvNames = []) ); } } - - return $query->addSelect('site_content.pagetitle as pagetitle_orig', 'site_content.longtitle as longtitle_orig') - ->addSelect('site_content.description as description_orig', 'site_content.introtext as introtext_orig') - ->addSelect('site_content.content as content_orig', 'site_content.menutitle as menutitle_orig') - ->leftJoin('site_content', 's_lang_content.resource', '=', 'site_content.id') - ->where('lang', '=', $locale); + return $query; } /** - * Only active resources + * Adds conditions to the query to filter for active items. * - * @param Builder $query - * @return Builder + * @param \Illuminate\Database\Query\Builder $query The database query builder instance + * @return \Illuminate\Database\Query\Builder The modified query builder instance */ public function scopeActive($query) { @@ -59,9 +71,9 @@ public function scopeActive($query) } /** - * Filter search + * Performs a search on the query based on the search term. * - * @return mixed + * @return \Illuminate\Database\Query\Builder|null The modified query builder instance or null if no search term is provided */ public function scopeSearch() { @@ -86,12 +98,12 @@ public function scopeSearch() } /** - * Filtering documents by TV parameter + * Adds a WHERE clause to the query that filters results based on the given TV and value. * - * @param Builder $query - * @param string $name - * @param string|int $value - * @return Builder + * @param \Illuminate\Database\Query\Builder $query The database query builder instance + * @param string $name The name of the TV to filter by + * @param mixed $value The value to filter by + * @return \Illuminate\Database\Query\Builder The modified query builder instance */ public function scopeWhereTv($query, $name, $value) { @@ -102,9 +114,16 @@ public function scopeWhereTv($query, $name, $value) } /** - * Get the menutitle attribute + * Retrieves the menu title attribute. + * + * This method returns the value of the menu title attribute for the current instance. + * If the menu title attribute is empty, it falls back to the original menu title value (menutitle_orig). + * If both the menu title attribute and the original menu title value are empty, it falls back to the + * current page title attribute (pagetitle), or the original page title value (pagetitle_orig) if empty. + * If both the menu title attribute, original menu title value, and the page title attribute are empty, it + * returns an empty string. * - * @return mixed + * @return string The menu title attribute value */ public function getMenutitleAttribute() { @@ -116,9 +135,9 @@ public function getMenutitleAttribute() } /** - * Get the resource full link + * Get the full link attribute for the resource. * - * @return string full_link + * @return string The full link attribute */ public function getFullLinkAttribute() { diff --git a/src/sLang.php b/src/sLang.php index 9cb193c..64d9007 100644 --- a/src/sLang.php +++ b/src/sLang.php @@ -28,7 +28,7 @@ public function __construct() } /** - * List of frontend document languages + * Returns an array of alternative site languages for the language switcher * * @return array */ @@ -57,9 +57,12 @@ public function langSwitcher(): array } /** - * List of alternative site languages + * Generates the HTML code for the hreflang tags. * - * @return string + * This method generates the HTML code for the hreflang tags based on the + * configuration settings and language switcher options. + * + * @return string The HTML code for the hreflang tags. */ public function hrefLang(): string { @@ -77,9 +80,12 @@ public function hrefLang(): string } /** - * List of languages + * Retrieves the list of languages. * - * @return array + * This method retrieves the list of languages from the "lang-list.php" configuration file + * and returns it as an array. + * + * @return array The list of languages. */ public function langList(): array { @@ -91,9 +97,13 @@ public function langList(): array } /** - * Default language + * Returns the default language code. * - * @return string + * This method retrieves the default language code from the configuration + * settings. If the default language code is not set in the configuration, it + * will default to 'uk'. + * + * @return string The default language code. */ public function langDefault(): string { @@ -101,9 +111,12 @@ public function langDefault(): string } /** - * List of site languages + * Retrieves the language configuration. * - * @return array + * This method retrieves the language configuration from the system settings + * or the custom configuration stored in the "s_lang_config" setting. + * + * @return array The array containing the language configuration. */ public function langConfig(): array { @@ -116,9 +129,13 @@ public function langConfig(): array } /** - * List of frontend languages + * Retrieves the languages used for the frontend. * - * @return array + * This method retrieves the languages used for the frontend based on the configuration + * settings and the additional language options specified in "s_lang_front" configuration + * variable. The languages are returned as an array. + * + * @return array The languages used for the frontend. */ public function langFront(): array { @@ -131,11 +148,17 @@ public function langFront(): array } /** - * Getting a translation of a resource + * Retrieves the language content for a specific resource in a given language. * - * @param int $resourceId - * @param string $langKey - * @return array + * This method retrieves the language content for a specific resource identified + * by the `$resourceId` and the language specified by the `$langKey`. It queries + * the `sLangContent` table and returns the result as an associative array. + * If no matching record is found, an empty array is returned. + * + * @param int $resourceId The ID of the resource. + * @param string $langKey The language key. + * @return array The language content as an associative array. If no matching record + * is found, an empty array is returned. */ public function getLangContent(int $resourceId, string $langKey): array { @@ -144,12 +167,17 @@ public function getLangContent(int $resourceId, string $langKey): array } /** - * Get automatic translation + * Translates a given text automatically using the Google Translate API. * - * @param $text - * @param $source - * @param $target - * @return string + * This method translates the provided text from the specified source language + * to the target language using the Google Translate API. The translation is performed + * automatically without any additional processing. + * + * @param string $text The text to be translated. + * @param string $source The source language code. + * @param string $target The target language code. + * + * @return string The translated text. */ public function getAutomaticTranslate($text, $source, $target) { @@ -159,7 +187,9 @@ public function getAutomaticTranslate($text, $source, $target) /** * Path where files root this module * - * @return mixed|string + * This method returns the base path of the module. + * + * @return string The base path of the module. */ public function basePath() { @@ -167,9 +197,11 @@ public function basePath() } /** - * Module url + * Generates the URL for the module. * - * @return string + * This method generates the URL for the module by appending the necessary query parameters. + * + * @return string The URL for the module. */ public function moduleUrl(): string { @@ -177,9 +209,12 @@ public function moduleUrl(): string } /** - * Fields list on content + * Retrieves the site content fields. * - * @return array + * This method returns the site content fields as an array. The site content fields + * contain the list of fields that are used for storing content related to the site. + * + * @return array The site content fields array. */ public function siteContentFields(): array { @@ -187,11 +222,15 @@ public function siteContentFields(): array } /** - * Display render + * Renders a view template with the given data. + * + * This method renders a view template using the Laravel View class. It allows passing + * additional data to the view in the form of an associative array. The view file name or path + * is provided as the first parameter, and the data array is optional. * - * @param $tpl - * @param array $data - * @return bool + * @param string $tpl The view template file name or path. + * @param array $data An optional associative array of data to be passed to the view. + * @return bool Returns true upon successful rendering of the view. */ public function view($tpl, $data = []) { @@ -211,12 +250,17 @@ public function view($tpl, $data = []) } /** - * Get Google Translations + * Translates the given text using Google Translate. * - * @param $text - * @param string $source - * @param string $target - * @return string + * This method sends a request to the Google Translate API and retrieves + * the translated text for the given input text. The source and target + * languages can be specified. If the source and target languages are the + * same, the method returns the input text as is. + * + * @param string $text The text to be translated. + * @param string $source The source (input) language. Default is 'uk'. + * @param string $target The target (output) language. Default is 'en'. + * @return string The translated text. */ protected function googleTranslate($text, $source = 'uk', $target = 'en') { @@ -262,8 +306,10 @@ protected function googleTranslate($text, $source = 'uk', $target = 'en') /** * Get system setting value bypassing cache * - * @param $name string - * @return string + * This method retrieves the value of the configuration setting with the given name. + * + * @param string $name The name of the configuration setting. + * @return string The value of the configuration setting, or an empty string if the setting does not exist. */ protected function getConfigValue($name): string {