wpallstars/wp-plugin-starter-template-for-ai-coding
Template
1
1
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Add missing wiki pages and fix Plugin class constructor

Browse Source
This commit is contained in:
Marcus Quinn
2025-04-18 15:32:13 +01:00
parent 7072f21d49
commit 1c049a91c5
9 changed files with 1329 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

108
.wiki/AI-Workflow-Documentation.md Normal file
View File

@@ -0,0 +1,108 @@
# AI Workflow Documentation
This document provides an overview of the AI-assisted development workflows for this plugin.
## Introduction to AI-Assisted Development
AI-assisted development uses artificial intelligence tools to help with coding, documentation, testing, and other development tasks. This plugin is designed to work seamlessly with AI assistants to make development faster and more efficient.
## Setting Up Your AI Environment
### Required Files
To get the most out of AI-assisted development, make sure to include these files in your AI IDE context:
1. **.ai-assistant.md**: Contains essential information about the project structure and conventions
2. **.ai-workflows/**: Directory containing detailed workflow documentation for common tasks
### Pinning Files in AI IDEs
For the best results, pin these files in your AI IDE chat context:
- **Claude**: Use the "Pin" feature to keep files in context
- **GitHub Copilot**: Use the "Pin" feature in the chat interface
- **ChatGPT**: Use the "Pin" feature in the Advanced Data Analysis mode
- **Other AI IDEs**: Refer to your specific IDE's documentation for pinning files
## AI Workflow Files
The `.ai-workflows/` directory contains detailed guides for common development tasks:
1. **plugin-customization.md**: Guide for customizing the plugin for specific needs
2. **feature-development.md**: Workflow for developing new features
3. **bug-fixing.md**: Process for identifying and fixing bugs
4. **testing.md**: Guide for writing and running tests
5. **documentation.md**: Workflow for updating documentation
6. **release-process.md**: Steps for creating new releases
7. **wiki-documentation.md**: Guide for maintaining wiki documentation
## Using the Starter Prompt
The [Starter Prompt](Starter-Prompt) is a comprehensive guide for AI tools to help customize the template for your specific plugin. It includes:
1. **Project Overview**: Description of the plugin and its purpose
2. **Customization Steps**: Detailed steps for customizing the template
3. **File Structure**: Overview of the plugin's file structure
4. **Coding Standards**: Guidelines for code style and quality
5. **Testing Requirements**: Instructions for testing the plugin
## AI-Assisted Development Workflows
### Customizing the Plugin
1. Open your AI IDE and pin the `.ai-assistant.md` file and `.ai-workflows/` directory
2. Provide the Starter Prompt to the AI
3. Follow the AI's guidance to customize the plugin
4. Review and test the changes
### Developing New Features
1. Define the feature requirements
2. Ask the AI to help design the feature
3. Implement the feature with AI assistance
4. Write tests for the feature
5. Update documentation
### Fixing Bugs
1. Describe the bug to the AI
2. Ask the AI to help identify the cause
3. Implement the fix with AI assistance
4. Write tests to prevent regression
5. Update documentation if necessary
### Writing Tests
1. Describe the functionality to be tested
2. Ask the AI to help write unit tests
3. Ask the AI to help write end-to-end tests
4. Run the tests and fix any issues
### Updating Documentation
1. Describe the changes that need documentation
2. Ask the AI to help update the relevant documentation files
3. Review and refine the documentation
## Best Practices for AI-Assisted Development
1. **Be Specific**: Provide clear, detailed instructions to the AI
2. **Review Carefully**: Always review AI-generated code before committing
3. **Iterative Approach**: Work with the AI in small, iterative steps
4. **Provide Context**: Keep relevant files in the AI's context
5. **Ask Questions**: If you're unsure about something, ask the AI to explain
6. **Test Thoroughly**: Always test AI-generated code
## Troubleshooting AI Assistance
If you encounter issues with AI assistance:
1. **Refresh Context**: Sometimes the AI may lose context. Try refreshing the conversation or repinning files
2. **Be More Specific**: Provide more detailed instructions
3. **Break Down Tasks**: Divide complex tasks into smaller, manageable parts
4. **Provide Examples**: Show examples of what you want
5. **Try Different Approaches**: If one approach doesn't work, try a different one
## Conclusion
AI-assisted development can significantly speed up your workflow and improve code quality. By following these guidelines and using the provided AI workflow documentation, you can make the most of AI tools in your development process.

111
.wiki/Architecture-Overview.md Normal file
View File

@@ -0,0 +1,111 @@
# Architecture Overview
This document provides an overview of the plugin's architecture, explaining the core components and how they interact.
## Directory Structure
The plugin follows a structured organization to maintain clean separation of concerns:
```
wp-plugin-starter-template/
├── admin/ # Admin-specific functionality
│ ├── css/ # Admin stylesheets
│ ├── js/ # Admin JavaScript files
│ └── lib/ # Admin PHP classes
├── assets/ # Frontend assets
│ ├── css/ # Frontend stylesheets
│ ├── js/ # Frontend JavaScript files
│ └── images/ # Images used by the plugin
├── includes/ # Core plugin functionality
│ ├── core.php # Core functionality class
│ └── plugin.php # Main plugin class
├── languages/ # Translation files
├── tests/ # Test files
│ ├── e2e/ # End-to-end tests
│ └── unit/ # Unit tests
├── .github/ # GitHub-specific files
│ └── workflows/ # GitHub Actions workflows
├── .ai-workflows/ # AI workflow documentation
├── .wiki/ # Wiki documentation
└── wp-plugin-starter-template.php # Main plugin file
```
## Core Components
### Main Plugin File
The `wp-plugin-starter-template.php` file serves as the entry point for WordPress. It:
1. Defines plugin metadata
2. Prevents direct access
3. Loads the main plugin class
4. Initializes the plugin
### Plugin Class
The `Plugin` class in `includes/plugin.php` is the main controller for the plugin. It:
1. Initializes core functionality
2. Sets up hooks and filters
3. Manages plugin activation/deactivation
4. Handles plugin updates
### Core Class
The `Core` class in `includes/core.php` contains the core functionality of the plugin. It:
1. Implements the main plugin features
2. Provides utility methods
3. Manages data processing
### Admin Class
The `Admin` class in `admin/lib/admin.php` handles all admin-specific functionality. It:
1. Creates admin menu pages
2. Registers settings
3. Enqueues admin assets
4. Processes admin form submissions
## Object-Oriented Approach
The plugin follows object-oriented programming principles:
1. **Encapsulation**: Each class encapsulates its own functionality
2. **Inheritance**: Classes can extend others to inherit functionality
3. **Namespaces**: PHP namespaces are used to avoid conflicts
4. **Autoloading**: PSR-4 autoloading for efficient class loading
## Hook System
The plugin integrates with WordPress through its hook system:
1. **Actions**: Used to add functionality at specific points
2. **Filters**: Used to modify data before it's used by WordPress
## Data Flow
1. WordPress loads the main plugin file
2. The Plugin class is instantiated
3. The Plugin class initializes the Core class
4. The Plugin class initializes the Admin class (in admin context)
5. WordPress hooks trigger plugin functionality as needed
## Extensibility
The plugin is designed to be extensible:
1. **Filters**: Key data points can be modified via filters
2. **Actions**: Additional functionality can be added via actions
3. **Class Structure**: Classes can be extended to add or modify functionality
## Testing
The plugin includes a comprehensive testing framework:
1. **Unit Tests**: For testing individual components
2. **End-to-End Tests**: For testing the plugin as a whole
## Conclusion
This architecture provides a solid foundation for WordPress plugin development, following best practices and modern coding standards. It's designed to be maintainable, extensible, and easy to understand.

227
.wiki/Coding-Standards.md Normal file
View File

@@ -0,0 +1,227 @@
# Coding Standards
This document outlines the coding standards used in this plugin. Following these standards ensures consistency, readability, and maintainability of the codebase.
## PHP Coding Standards
This plugin follows the [WordPress Coding Standards](https://developer.wordpress.org/coding-standards/wordpress-coding-standards/php/) with some additional guidelines.
### File Structure
- Each PHP file should begin with the PHP opening tag `<?php` (no closing tag)
- Files should use the Unix line endings (LF)
- Files should be encoded in UTF-8 without BOM
### Naming Conventions
- **Classes**: Use `PascalCase` for class names
```php
class MyClassName {}
```
- **Methods and Functions**: Use `snake_case` for method and function names
```php
function my_function_name() {}
public function my_method_name() {}
```
- **Variables**: Use `snake_case` for variable names
```php
$my_variable_name = 'value';
```
- **Constants**: Use `UPPERCASE_WITH_UNDERSCORES` for constants
```php
define('MY_CONSTANT', 'value');
const MY_CLASS_CONSTANT = 'value';
```
- **Namespaces**: Use `PascalCase` for namespace segments
```php
namespace WPALLSTARS\PluginStarterTemplate;
```
- **Hooks**: Prefix hooks with the plugin's prefix
```php
do_action('wpst_hook_name');
apply_filters('wpst_filter_name', $value);
```
### Indentation and Formatting
- Use 4 spaces for indentation (not tabs)
- Opening braces for classes and functions should be on the same line
- Control structures should have one space between the statement and the opening parenthesis
- Each line should be no longer than 100 characters
```php
if ($condition) {
// Code here
} elseif ($another_condition) {
// More code
} else {
// Default code
}
```
### Documentation
- All classes, methods, and functions should be documented using PHPDoc
- Include a description, parameters, return values, and exceptions
```php
/**
* Short description of the function.
*
* Longer description if needed.
*
* @param string $param1 Description of the parameter.
* @param int $param2 Description of the parameter.
* @return bool Description of the return value.
* @throws Exception When something goes wrong.
*/
function my_function($param1, $param2) {
// Function code
}
```
### Object-Oriented Programming
- Each class should have a single responsibility
- Use visibility declarations for all properties and methods (public, protected, private)
- Use type hints for parameters and return types when possible
```php
class MyClass {
/**
* Property description.
*
* @var string
*/
private $property;
/**
* Method description.
*
* @param string $param Description of the parameter.
* @return bool Description of the return value.
*/
public function my_method(string $param): bool {
// Method code
}
}
```
## JavaScript Coding Standards
This plugin follows the [WordPress JavaScript Coding Standards](https://developer.wordpress.org/coding-standards/wordpress-coding-standards/javascript/).
### Naming Conventions
- **Variables and Functions**: Use `camelCase` for variable and function names
```javascript
var myVariableName = 'value';
function myFunctionName() {}
```
- **Constants**: Use `UPPERCASE_WITH_UNDERSCORES` for constants
```javascript
var MY_CONSTANT = 'value';
```
### Indentation and Formatting
- Use 4 spaces for indentation (not tabs)
- Opening braces should be on the same line as the statement
- Each line should be no longer than 100 characters
```javascript
if (condition) {
// Code here
} else if (anotherCondition) {
// More code
} else {
// Default code
}
```
### Documentation
- Use JSDoc for documenting functions and objects
```javascript
/**
* Short description of the function.
*
* @param {string} param1 - Description of the parameter.
* @param {number} param2 - Description of the parameter.
* @returns {boolean} Description of the return value.
*/
function myFunction(param1, param2) {
// Function code
}
```
## CSS Coding Standards
This plugin follows the [WordPress CSS Coding Standards](https://developer.wordpress.org/coding-standards/wordpress-coding-standards/css/).
### Naming Conventions
- Use lowercase for selectors
- Use hyphens to separate words in class and ID names
- Prefix classes and IDs with the plugin's prefix
```css
.wpst-container {
margin: 0;
}
#wpst-header {
padding: 10px;
}
```
### Indentation and Formatting
- Use 4 spaces for indentation (not tabs)
- Each property should be on its own line
- Include a space after the colon in property declarations
- End each declaration with a semicolon
- Use single quotes for attribute selectors and property values
```css
.wpst-container {
margin: 0;
padding: 10px;
font-family: 'Helvetica', sans-serif;
}
```
## Automated Code Checking
This plugin uses automated tools to enforce coding standards:
1. **PHP_CodeSniffer (PHPCS)**: Checks PHP code against the WordPress Coding Standards
```bash
composer run phpcs
```
2. **PHP Code Beautifier and Fixer (PHPCBF)**: Automatically fixes some coding standard violations
```bash
composer run phpcbf
```
3. **ESLint**: Checks JavaScript code against the WordPress Coding Standards
```bash
npm run lint:js
```
4. **Stylelint**: Checks CSS code against the WordPress Coding Standards
```bash
npm run lint:css
```
## Conclusion
Following these coding standards ensures that the plugin's code is consistent, readable, and maintainable. All contributors should adhere to these standards when submitting code to the project.

130
.wiki/Contributing.md Normal file
View File

@@ -0,0 +1,130 @@
# Contributing
Thank you for considering contributing to this project! This document provides guidelines and instructions for contributing.
## Code of Conduct
By participating in this project, you agree to abide by our code of conduct:
- Be respectful and inclusive
- Be patient and welcoming
- Be considerate
- Be collaborative
- Be open-minded
## How to Contribute
### Reporting Bugs
If you find a bug, please report it by creating an issue on GitHub:
1. Go to the [Issues](https://github.com/wpallstars/wp-plugin-starter-template-for-ai-coding/issues) page
2. Click "New Issue"
3. Select "Bug Report"
4. Fill out the template with as much detail as possible
5. Submit the issue
Please include:
- A clear, descriptive title
- Steps to reproduce the bug
- Expected behavior
- Actual behavior
- Screenshots (if applicable)
- Your environment (WordPress version, PHP version, browser, etc.)
### Suggesting Enhancements
If you have an idea for an enhancement:
1. Go to the [Issues](https://github.com/wpallstars/wp-plugin-starter-template-for-ai-coding/issues) page
2. Click "New Issue"
3. Select "Feature Request"
4. Fill out the template with as much detail as possible
5. Submit the issue
Please include:
- A clear, descriptive title
- A detailed description of the enhancement
- Why this enhancement would be useful
- Any relevant examples or mockups
### Pull Requests
If you want to contribute code:
1. Fork the repository
2. Create a new branch for your feature or bugfix
3. Make your changes
4. Run tests to ensure your changes don't break anything
5. Submit a pull request
#### Pull Request Process
1. Fork the repository on [GitHub](https://github.com/wpallstars/wp-plugin-starter-template-for-ai-coding/) or [Gitea](https://gitea.wpallstars.com/wpallstars/wp-plugin-starter-template-for-ai-coding/)
2. Clone your fork: `git clone https://github.com/YOUR-USERNAME/wp-plugin-starter-template-for-ai-coding.git`
3. Create your feature branch: `git checkout -b feature/amazing-feature`
4. Make your changes
5. Commit your changes: `git commit -m 'Add some amazing feature'`
6. Push to the branch: `git push origin feature/amazing-feature`
7. Submit a pull request
#### Pull Request Guidelines
- Follow the coding standards (see [Coding Standards](Coding-Standards))
- Write tests for your changes
- Update documentation as needed
- Keep pull requests focused on a single change
- Write a clear, descriptive title and description
- Reference any related issues
## Development Environment
To set up your development environment:
1. Clone the repository: `git clone https://github.com/wpallstars/wp-plugin-starter-template-for-ai-coding.git`
2. Install dependencies: `composer install && npm install`
3. Start the development environment: `npm run start`
### Testing
Before submitting a pull request, make sure to run the tests:
- PHP Unit Tests: `npm run test:php`
- End-to-End Tests: `npm run test:e2e`
- Coding Standards: `npm run lint:php`
## Documentation
If you're adding a new feature or changing existing functionality, please update the documentation:
- Update the README.md file if necessary
- Update the readme.txt file if necessary
- Update or create wiki pages as needed
- Update code comments
## Community
Join our community to discuss the project:
- [GitHub Discussions](https://github.com/wpallstars/wp-plugin-starter-template-for-ai-coding/discussions)
- [Gitea Issues](https://gitea.wpallstars.com/wpallstars/wp-plugin-starter-template-for-ai-coding/issues)
## Recognition
Contributors will be recognized in the following ways:
- Added to the contributors list in readme.txt
- Mentioned in release notes for significant contributions
- Thanked in the Changelog for specific contributions
## License
By contributing to this project, you agree that your contributions will be licensed under the project's [GPL-2.0+ License](https://www.gnu.org/licenses/gpl-2.0.html).
## Questions?
If you have any questions about contributing, please open an issue or contact the maintainers.
Thank you for your contributions!

162
.wiki/Customization-Guide.md Normal file
View File

@@ -0,0 +1,162 @@
# Customization Guide
This guide provides detailed instructions on how to customize the plugin starter template for your specific needs.
## Basic Customization
### Renaming the Plugin
1. **Main Plugin File**: Rename `wp-plugin-starter-template.php` to match your plugin name (e.g., `my-awesome-plugin.php`)
2. **Update Plugin Header**: Edit the plugin header in your main plugin file:
```php
/**
* Plugin Name: My Awesome Plugin
* Plugin URI: https://www.example.com
* Description: A brief description of your plugin
* Version: 0.1.0
* Author: Your Name
* Author URI: https://www.example.com
* License: GPL-2.0+
* License URI: http://www.gnu.org/licenses/gpl-2.0.txt
* Text Domain: my-awesome-plugin
* Domain Path: /languages
*/
```
3. **Update Text Domain**: Change the text domain throughout the codebase from `wp-plugin-starter-template` to your plugin's text domain
### Updating Namespaces
1. **Change Namespace**: Update all namespace references from `WPALLSTARS\PluginStarterTemplate` to your own namespace (e.g., `MyCompany\MyAwesomePlugin`)
2. **Update Autoloading**: Modify the `composer.json` file to reflect your new namespace:
```json
"autoload": {
"psr-4": {
"MyCompany\\MyAwesomePlugin\\": "includes/"
}
}
```
3. **Run Composer**: After updating the namespace, run `composer dump-autoload` to update the autoloader
### Customizing Documentation
1. **README.md**: Update the README.md file with your plugin's information
2. **readme.txt**: Update the readme.txt file for WordPress.org compatibility
3. **CHANGELOG.md**: Start a fresh changelog for your plugin
4. **Wiki Documentation**: Customize the wiki documentation to match your plugin
## Advanced Customization
### Adding Custom Functionality
1. **Core Functionality**: Modify the `includes/core.php` file to implement your core functionality
2. **Admin Interface**: Customize the `admin/lib/admin.php` file to create your admin interface
3. **Frontend Features**: Add frontend functionality as needed
### Customizing Assets
1. **CSS**: Modify or add stylesheets in the `assets/css/` directory
2. **JavaScript**: Customize JavaScript files in the `assets/js/` directory
3. **Images**: Add your own images to the `assets/images/` directory
### Adding Custom Post Types
If your plugin needs custom post types, add them to the Core class:
```php
public function register_post_types() {
register_post_type('my_custom_post', [
'labels' => [
'name' => __('Custom Posts', 'my-awesome-plugin'),
'singular_name' => __('Custom Post', 'my-awesome-plugin'),
],
'public' => true,
'has_archive' => true,
'supports' => ['title', 'editor', 'thumbnail'],
'menu_icon' => 'dashicons-admin-post',
]);
}
```
### Adding Custom Taxonomies
For custom taxonomies, add them to the Core class:
```php
public function register_taxonomies() {
register_taxonomy('custom_category', 'my_custom_post', [
'labels' => [
'name' => __('Custom Categories', 'my-awesome-plugin'),
'singular_name' => __('Custom Category', 'my-awesome-plugin'),
],
'hierarchical' => true,
'show_admin_column' => true,
]);
}
```
### Adding Settings Pages
To add a settings page, customize the Admin class:
```php
public function add_menu_pages() {
add_menu_page(
__('My Plugin Settings', 'my-awesome-plugin'),
__('My Plugin', 'my-awesome-plugin'),
'manage_options',
'my-awesome-plugin',
[$this, 'render_settings_page'],
'dashicons-admin-generic',
100
);
}
public function render_settings_page() {
include plugin_dir_path(__FILE__) . '../templates/settings-page.php';
}
```
### Customizing Update Mechanism
The template includes functionality for updates from different sources. Customize the update source options in the main plugin file:
```php
/**
* GitHub Plugin URI: username/repository
* GitHub Branch: main
* Primary Branch: main
* Release Branch: main
* Release Asset: true
* Requires at least: 5.0
* Requires PHP: 7.0
* Update URI: https://example.com/plugin-updates
*/
```
## Testing Your Customizations
After making your customizations, it's important to test your plugin:
1. **Unit Tests**: Update and run the unit tests to ensure your core functionality works correctly
2. **End-to-End Tests**: Update and run the end-to-end tests to test the plugin as a whole
3. **Manual Testing**: Test your plugin in different WordPress environments
## Building Your Plugin
Once you've customized the plugin to your needs, build it for distribution:
```bash
./build.sh {VERSION}
```
This will create a ZIP file that you can install in WordPress or distribute to users.
## Conclusion
By following this customization guide, you can transform the plugin starter template into a fully functional plugin that meets your specific needs. Remember to maintain the same level of code quality and documentation as you customize the template.

190
.wiki/Extending-the-Plugin.md Normal file
View File

@@ -0,0 +1,190 @@
# Extending the Plugin
This guide explains how to extend the plugin's functionality through various extension points.
## Extension Points
The plugin is designed with extensibility in mind, providing several ways to extend or modify its functionality:
1. **Action Hooks**: Add custom functionality at specific points
2. **Filter Hooks**: Modify data or behavior
3. **Class Extension**: Extend existing classes to add or modify functionality
4. **Template Overrides**: Customize the plugin's output
## Using Action Hooks
Action hooks allow you to add custom functionality at specific points in the plugin's execution. Here are some examples:
### Available Actions
- `wpst_plugin_init`: Fires when the plugin is initialized
- `wpst_before_process`: Fires before the plugin processes data
- `wpst_after_process`: Fires after the plugin processes data
- `wpst_admin_init`: Fires when the admin functionality is initialized
### Example: Adding Custom Functionality
```php
add_action('wpst_plugin_init', 'my_custom_init_function');
function my_custom_init_function() {
// Your custom initialization code here
}
```
### Example: Adding Custom Admin Functionality
```php
add_action('wpst_admin_init', 'my_custom_admin_function');
function my_custom_admin_function() {
// Your custom admin initialization code here
}
```
## Using Filter Hooks
Filter hooks allow you to modify data or behavior at specific points. Here are some examples:
### Available Filters
- `wpst_settings`: Filter the plugin settings
- `wpst_process_data`: Filter the data being processed
- `wpst_admin_tabs`: Filter the admin tabs
- `wpst_display_output`: Filter the output before display
### Example: Modifying Settings
```php
add_filter('wpst_settings', 'my_custom_settings_filter');
function my_custom_settings_filter($settings) {
// Modify the settings array
$settings['custom_option'] = 'custom_value';
return $settings;
}
```
### Example: Modifying Output
```php
add_filter('wpst_display_output', 'my_custom_output_filter');
function my_custom_output_filter($output) {
// Modify the output
$output = str_replace('original', 'modified', $output);
return $output;
}
```
## Extending Classes
You can extend the plugin's classes to add or modify functionality.
### Example: Extending the Core Class
```php
use WPALLSTARS\PluginStarterTemplate\Core;
class My_Extended_Core extends Core {
public function __construct() {
parent::__construct();
// Add your custom initialization here
}
// Override an existing method
public function filter_content($content) {
// Modify the content
$content = parent::filter_content($content);
$content = str_replace('original', 'modified', $content);
return $content;
}
// Add a new method
public function custom_method() {
// Your custom method implementation
}
}
```
### Example: Extending the Admin Class
```php
use WPALLSTARS\PluginStarterTemplate\Admin\Admin;
class My_Extended_Admin extends Admin {
public function __construct($core) {
parent::__construct($core);
// Add your custom initialization here
}
// Override an existing method
public function enqueue_admin_assets($hook) {
parent::enqueue_admin_assets($hook);
// Add your custom assets
wp_enqueue_script(
'my-custom-script',
plugin_dir_url(__FILE__) . 'js/custom-script.js',
['jquery'],
'1.0.0',
true
);
}
// Add a new method
public function custom_admin_method() {
// Your custom method implementation
}
}
```
## Creating Add-ons
You can create separate add-on plugins that extend the functionality of the main plugin.
### Example: Basic Add-on Structure
```php
<?php
/**
* Plugin Name: My Awesome Add-on
* Description: Extends the WordPress Plugin Starter Template with awesome features
* Version: 1.0.0
* Author: Your Name
* License: GPL-2.0+
* License URI: http://www.gnu.org/licenses/gpl-2.0.txt
* Text Domain: my-awesome-addon
* Requires: WordPress Plugin Starter Template
*/
// Check if the main plugin is active
if (!class_exists('WPALLSTARS\\PluginStarterTemplate\\Plugin')) {
add_action('admin_notices', 'my_addon_missing_main_plugin_notice');
return;
}
function my_addon_missing_main_plugin_notice() {
echo '<div class="error"><p>';
echo __('My Awesome Add-on requires the WordPress Plugin Starter Template to be installed and activated.', 'my-awesome-addon');
echo '</p></div>';
}
// Initialize the add-on
add_action('wpst_plugin_init', 'initialize_my_addon');
function initialize_my_addon() {
// Your add-on initialization code here
}
```
## Best Practices for Extensions
1. **Use Namespaces**: Use PHP namespaces to avoid conflicts with other plugins
2. **Follow Coding Standards**: Maintain the same coding standards as the main plugin
3. **Document Your Extensions**: Provide clear documentation for your extensions
4. **Test Thoroughly**: Test your extensions with different WordPress versions
5. **Version Compatibility**: Specify which versions of the main plugin your extension is compatible with
## Conclusion
By using these extension points, you can customize and extend the plugin's functionality to meet your specific needs without modifying the core plugin files. This approach ensures that your customizations will continue to work even when the main plugin is updated.

180
.wiki/Release-Process.md Normal file
View File

@@ -0,0 +1,180 @@
# Release Process
This document outlines the process for creating and publishing new releases of the plugin.
## Version Numbering
This plugin follows [Semantic Versioning](https://semver.org/) (SemVer):
- **MAJOR version** (x.0.0): Incompatible API changes
- **MINOR version** (0.x.0): Add functionality in a backward-compatible manner
- **PATCH version** (0.0.x): Backward-compatible bug fixes
## Pre-Release Checklist
Before creating a new release, complete the following checklist:
1. **Code Review**: Ensure all code has been reviewed and approved
2. **Testing**: Verify that all tests pass
- Unit tests
- End-to-end tests
- Manual testing in different environments
3. **Documentation**: Update all relevant documentation
- README.md
- readme.txt
- Wiki pages
- Code comments
4. **Changelog**: Update CHANGELOG.md with all changes since the last release
5. **Version Numbers**: Update version numbers in:
- Main plugin file header
- Plugin initialization
- readme.txt
- package.json (if applicable)
- composer.json (if applicable)
## Creating a Release
### Manual Release Process
1. **Create a Release Branch**:
```bash
git checkout -b release/x.y.z
```
2. **Update Version Numbers**:
- Update the version number in the main plugin file header
- Update the version number in the plugin initialization
- Update the "Stable tag" in readme.txt
- Update the version in package.json and composer.json (if applicable)
3. **Update Changelog**:
- Add a new section to CHANGELOG.md for the new version
- Add a new section to the Changelog in readme.txt
- Add a new section to the Upgrade Notice in readme.txt
4. **Commit Changes**:
```bash
git add .
git commit -m "Bump version to x.y.z"
```
5. **Create a Pull Request**:
- Push the release branch to GitHub
- Create a pull request against the main branch
- Have the pull request reviewed and approved
6. **Merge the Pull Request**:
- Merge the pull request into the main branch
7. **Create a Release Tag**:
```bash
git checkout main
git pull
git tag -a vx.y.z -m "Version x.y.z"
git push origin vx.y.z
```
8. **Create a GitHub Release**:
- Go to the GitHub repository
- Click on "Releases"
- Click "Draft a new release"
- Select the tag you just created
- Add a title and description
- Upload the built plugin ZIP file
- Publish the release
### Automated Release Process
This plugin uses GitHub Actions to automate the release process:
1. **Create a Release Branch**:
```bash
git checkout -b release/x.y.z
```
2. **Update Version Numbers and Changelog** (as described above)
3. **Commit Changes**:
```bash
git add .
git commit -m "Bump version to x.y.z"
```
4. **Create a Pull Request** (as described above)
5. **Merge the Pull Request** (as described above)
6. **Create a Release Tag**:
```bash
git checkout main
git pull
git tag -a vx.y.z -m "Version x.y.z"
git push origin vx.y.z
```
7. **Automated GitHub Release**:
- The GitHub Actions workflow will automatically:
- Build the plugin
- Create a GitHub release
- Upload the built plugin ZIP file
- Update the wiki (if configured)
## Post-Release Tasks
After creating a release, complete the following tasks:
1. **Verify the Release**:
- Check that the GitHub release was created successfully
- Download the ZIP file and verify its contents
- Test the plugin by installing it from the ZIP file
2. **Update Documentation**:
- Update any external documentation that references the plugin version
- Update the plugin's website (if applicable)
3. **Announce the Release**:
- Announce the release on relevant channels (blog, social media, etc.)
- Notify users who have reported issues that are fixed in this release
4. **Start Planning the Next Release**:
- Create issues for the next release
- Update the project roadmap
## Hotfix Process
For critical bugs that need to be fixed immediately:
1. **Create a Hotfix Branch**:
```bash
git checkout -b hotfix/x.y.z
```
2. **Fix the Bug**:
- Make the necessary changes to fix the bug
- Add tests to prevent regression
3. **Update Version Numbers and Changelog** (as described above)
4. **Commit Changes**:
```bash
git add .
git commit -m "Hotfix: description of the fix"
```
5. **Create a Pull Request** (as described above)
6. **Merge the Pull Request** (as described above)
7. **Create a Release Tag and GitHub Release** (as described above)
## Release Branches
This plugin uses the following branch strategy:
- **main**: The main development branch
- **release/x.y.z**: Temporary branches for preparing releases
- **hotfix/x.y.z**: Temporary branches for hotfixes
## Conclusion
Following this release process ensures that releases are consistent, well-documented, and properly tested. It also helps users understand what has changed between versions and how to upgrade safely.

168
.wiki/Troubleshooting.md Normal file
View File

@@ -0,0 +1,168 @@
# Troubleshooting
This guide provides solutions to common issues you might encounter when using or developing with this plugin.
## Installation Issues
### Plugin Installation Fails
**Problem**: The plugin fails to install in WordPress.
**Solutions**:
1. Verify that your WordPress version meets the minimum requirement (5.0+)
2. Check that your PHP version meets the minimum requirement (7.0+)
3. Ensure the ZIP file is properly formatted and contains all required files
4. Try installing the plugin manually by uploading the unzipped folder to the `wp-content/plugins` directory
### Activation Error
**Problem**: You receive an error when activating the plugin.
**Solutions**:
1. Check the error message for specific details
2. Verify that all plugin dependencies are installed and activated
3. Check your server's error logs for more information
4. Temporarily deactivate other plugins to check for conflicts
## Development Issues
### Composer Dependencies
**Problem**: Composer fails to install dependencies.
**Solutions**:
1. Verify that you have Composer installed and up to date
2. Check that your PHP version meets the requirements for all dependencies
3. Try clearing Composer's cache: `composer clear-cache`
4. Run `composer install --verbose` to see detailed error messages
### NPM Dependencies
**Problem**: NPM fails to install dependencies.
**Solutions**:
1. Verify that you have Node.js and NPM installed and up to date
2. Try clearing NPM's cache: `npm cache clean --force`
3. Delete the `node_modules` directory and run `npm install` again
4. Run `npm install --verbose` to see detailed error messages
### WordPress Environment (wp-env)
**Problem**: The WordPress environment fails to start.
**Solutions**:
1. Verify that Docker is installed and running
2. Check that the Docker daemon has enough resources allocated
3. Try stopping and removing existing containers: `npm run wp-env stop && npm run wp-env clean`
4. Run `npm run wp-env start --debug` to see detailed error messages
### Unit Tests
**Problem**: Unit tests are failing.
**Solutions**:
1. Verify that you have PHPUnit installed and configured correctly
2. Check that all dependencies are installed: `composer install`
3. Run tests with verbose output: `./vendor/bin/phpunit --verbose`
4. Check for syntax errors in your PHP files
### End-to-End Tests
**Problem**: End-to-end tests are failing.
**Solutions**:
1. Verify that the WordPress environment is running: `npm run start`
2. Check that Cypress is installed correctly: `npx cypress verify`
3. Run tests in interactive mode to debug: `npm run test:e2e`
4. Check for issues with selectors or timing in your test scripts
## Plugin Functionality Issues
### Plugin Settings Not Saving
**Problem**: Changes to plugin settings are not being saved.
**Solutions**:
1. Check for JavaScript errors in the browser console
2. Verify that the settings form is submitting correctly
3. Check that the WordPress nonce is being verified correctly
4. Ensure that the user has the necessary permissions to save settings
### Plugin Conflicts
**Problem**: The plugin conflicts with other plugins.
**Solutions**:
1. Deactivate other plugins one by one to identify the conflict
2. Check for JavaScript errors in the browser console
3. Check for PHP errors in the server logs
4. Contact the developers of both plugins to report the conflict
### Performance Issues
**Problem**: The plugin is causing performance issues.
**Solutions**:
1. Check if the plugin is making excessive database queries
2. Verify that assets (CSS/JS) are being properly enqueued and minified
3. Consider implementing caching for resource-intensive operations
4. Use a profiling tool to identify bottlenecks
## Update Issues
### Update Fails
**Problem**: The plugin fails to update.
**Solutions**:
1. Verify that your WordPress version meets the requirements for the new version
2. Check that your PHP version meets the requirements for the new version
3. Try updating manually by downloading the new version and replacing the old files
4. Check for file permission issues on your server
### Lost Settings After Update
**Problem**: Plugin settings are lost after updating.
**Solutions**:
1. Check if the plugin includes a data migration process for updates
2. Verify that the settings are being stored in the database correctly
3. Restore settings from a backup if available
4. Contact plugin support for assistance
## Multisite Issues
### Plugin Not Working on Multisite
**Problem**: The plugin doesn't work correctly on a multisite installation.
**Solutions**:
1. Verify that the plugin is network activated if required
2. Check that the plugin is compatible with multisite (it should be!)
3. Ensure that the plugin has the necessary permissions on each site
4. Check for multisite-specific settings or options
## Getting Additional Help
If you're still experiencing issues after trying these troubleshooting steps:
1. Check the [Frequently Asked Questions](Frequently-Asked-Questions) for more information
2. Search for similar issues in the [GitHub Issues](https://github.com/wpallstars/wp-plugin-starter-template-for-ai-coding/issues)
3. Create a new issue with detailed information about your problem
4. Contact the plugin developers for direct support
## Reporting Bugs
If you've identified a bug in the plugin:
1. Go to the [GitHub Issues](https://github.com/wpallstars/wp-plugin-starter-template-for-ai-coding/issues) page
2. Click "New Issue"
3. Select "Bug Report"
4. Fill out the template with as much detail as possible
5. Submit the issue
Please include:
- A clear description of the bug
- Steps to reproduce the issue
- Your environment details (WordPress version, PHP version, etc.)
- Any relevant error messages or screenshots

53
includes/plugin.php
View File

@@ -1 +1,54 @@
<?php
/**
* Main plugin class
*
* @package WPALLSTARS\PluginStarterTemplate
*/
namespace WPALLSTARS\PluginStarterTemplate;
/**
* Plugin class
*/
class Plugin {
/**
* Core instance
*
* @var Core
*/
private $core;
/**
* Plugin file
*
* @var string
*/
private $plugin_file;
/**
* Plugin version
*
* @var string
*/
private $version;
/**
* Constructor
*
* @param string $plugin_file Main plugin file path.
* @param string $version Plugin version.
*/
public function __construct($plugin_file, $version) {
$this->plugin_file = $plugin_file;
$this->version = $version;
$this->core = new Core();
}
/**
* Initialize the plugin
*/
public function init() {
// Initialize plugin
}
}