### General Information About the Plugin
Plugin Name: Suggester
Version: 1.0.1

### General Concept of the Plugin

The plugin is an intelligent suggestion generator based on the keyword entered by the user in the search bar, along with custom commands defined by the site owner in the backend within the "prompt text" field.
The tool operates using API keys from Google Gemini and the OpenRouter provider, which enables the use of multiple AI models. These models generate suggestions based on the entered keyword and according to instructions pre-defined by the site owner.
The plugin allows the creation of only three tools, each with a unique shortcode that can be embedded on any page on the WordPress site to activate it. The tools are clearly separated to avoid any overlap in functionality.
When creating the first tool, the shortcode looks like this:
[suggester id='1']
Each new tool automatically receives a sequential identifier, such as [suggester id='2'] and [suggester id='3'].
Note: When the maximum limit (three tools) is reached, the Create New tool button is disabled, and a warning appears when hovering over it, saying: "You are using the free version and cannot create more than three tools."
The plugin consists of:
Frontend: Designed for the average user, it contains pre-made templates that allow them to enter their keyword and receive instant suggestions when they click the "Suggest" button.

Backend: Designed for the site owner, it allows them to customize the tool's appearance, such as colors, text, and number of suggestions. It also allows them to create new tools with their own shortcodes.

Gutenberg Integration: The plugin provides direct support for inserting tools through the component editor, making it easier for site owners to use and customize.

### Tabs and Pages

Pages and tabs only appear within the plugin's backend interface, as follows.

The plugin contains three main pages that appear in the plugin's sidebar:

Dashboard Page: This is the plugin's home page and contains four tabs, as follows:

Tab 1: Overview
Tab 2: Statistics
Tab 3: Suggestion History
Tab 4: Our Other tools

Tools Page: Contains all previously created tools. You can also create a new tool from the Tools page, or delete or modify existing tools.

Settings Page: This is where you can control the plugin's general settings.

Note: If the page contains tabs, when reloading or refreshing the page, the user must remain on the same tab that was active, and they will not automatically return to the first tab.

Note: Navigating between tabs within the page must be done without reloading the entire page.

### Translation

The plugin will be built in English as the primary language, but it can be translated into Arabic using WordPress's built-in translation system. When you change the site's language in the WordPress settings, the plugin automatically displays the main texts in the backend in the new language, including support for right-to-left (RTL) text direction when Arabic is selected.
The frontend does not contain automatic translations, but it must be fully configured to support RTL to match the Arabic design.
To ensure translation support, you must create a folder named /languages ​​within the plugin files, where the translation files for the supported languages ​​are stored.

### Shortcodes

I want you to implement clear and organized logic to ensure that each Suggester tool in the plugin I'm developing (each one created using a different shortcode, such as [suggester id='1']) is completely independent in its settings.

Each tool should have its own settings (such as templates, commands, scripts, etc.) stored separately from the other tools. Therefore:

1. Store each tool's settings using the `update_option()` function in the form: `suggester_tool_settings_{$id}`.
2. When viewing the tool interface or editing its settings in the dashboard, use the `id` value to read the correct settings for each tool using `get_option()`.
3. When merging settings with global settings (such as an API key), use `array_merge()` so that the tool's specific settings are preferred over the global ones.
4. Don't use a single global option that contains the settings for all tools, to avoid update or read conflicts.
5. Make the execution of the shortcode depend on the `id` value to assign the correct settings, so that each call is independent and easy to customize.

**Goal:** Completely separate the settings of each tool and avoid any overlap or conflict between the settings of different tools, ensuring stable performance and future customization.

The shortcode system in the plugin should be based on a continuous, non-reusable sequence. When a tool is deleted, its associated ID should not be reassigned to a new tool. This approach helps prevent any conflicts or confusion in tracking statistics or usage data associated with that specific tool.

For example:
If three tools have been created with the following shortcodes: [suggester id='1'], [suggester id='2'], and [suggester id='3'], and the second tool is deleted, then the next tool created should receive a new, incremented ID: [suggester id='4'], rather than reusing [suggester id='2'].

This method ensures:

    Accurate tracking and analytics without data overlap between tools.

    Reliable historical data, even after a tool is deleted.

    Technical consistency, especially if old shortcodes remain embedded in pages or logs.

Therefore, it’s recommended that the plugin use an auto-incrementing ID system that does not recycle deleted IDs—similar to how primary keys work in relational databases.

### API Keys

take a look at @api-keys-integration.md

### Security

While developing this plugin, focus heavily on the following security aspects. Don't ignore any of them, as they are essential for protecting the site from vulnerabilities and ensuring the plugin's stability when used in practice:

1. User Permissions:
All backend actions (delete, edit, settings) must verify user permissions using:

current_user_can('manage_options')

Block the execution of any admin function if the user doesn't have permissions.

2. Nonce Validation:
Add a nonce to every operation executed via AJAX or a form in the settings.

Verify the nonce using check_ajax_referer() or check_admin_referer().

3. Input Sanitization:
When receiving data from the user (whether from AJAX or fields), use:

sanitize_text_field() for text.

sanitize_key() for IDs.

absint() or intval() for numbers.

Don't pass data directly to databases or APIs without sanitizing.

4. Output Filtering:
Any text displayed in HTML must pass through esc_html() or esc_attr() depending on the context.

Don't print content directly from user input or API responses without filtering.

5. File Security:
In all PHP files, add:

if (!defined('ABSPATH')) exit;

Do not allow PHP files to be run directly from outside WordPress.

6. API Key Security:
Store your Gemini API key using update_option(), and don't explicitly write it in your code.

Never send it to the frontend.

Only use it from the server in wp_remote_post().

7. Prevent Abuse:
Add a simple mechanism to limit the number of requests per IP (e.g., 1 request every 10 seconds).

Use Transients or an internal cache to reduce the number of Gemini API calls for the same keyword.

8. Performance Protection:
Enable Gemini API calls via AJAX with a timeout of no more than 10 seconds.

Check for errors using is_wp_error() and verify the response code.

9. Avoid eval and exec completely.
Never use eval() or execute dynamic code strings.

10. Logs:
If you add any error or usage logs, do not store sensitive data such as your API key or personal suggestions.

📌 Use OOP to organize your code, and do not write code directly within templates. Keep each function in its own file or class, with a clear division between the user interface, processing logic, and Google API contacts.


Always check @important-basics-when-programming.md