commit 8a4802248c95abea019af48fae502c95ce950d3e Author: magdev Date: Wed Jan 21 18:46:34 2026 +0100 Initial project setup with configuration files Add .editorconfig, .gitignore, and CLAUDE.md project documentation. Co-Authored-By: Claude Opus 4.5 diff --git a/.editorconfig b/.editorconfig new file mode 100644 index 0000000..dd3fa9c --- /dev/null +++ b/.editorconfig @@ -0,0 +1,15 @@ +# EditorConfig is awesome: https://EditorConfig.org + +# top-most EditorConfig file +root = true + +[*] +indent_style = space +indent_size = 4 +end_of_line = lf +charset = utf-8 +trim_trailing_whitespace = true +insert_final_newline = true + +[*.md] +indent_size = 2 \ No newline at end of file diff --git a/.gitignore b/.gitignore new file mode 100644 index 0000000..3193733 --- /dev/null +++ b/.gitignore @@ -0,0 +1,4 @@ +# For development purposes +# Linked wordpress core and plugin folder +wp-plugins +wp-core diff --git a/CLAUDE.md b/CLAUDE.md new file mode 100644 index 0000000..60a9cb6 --- /dev/null +++ b/CLAUDE.md @@ -0,0 +1,192 @@ +# WooCommerce Plugin for licensed Products + +**Author:** Marco Graetsch +**Author URL:** +**Author Email:** +**Repository URL:** +**Issues URL:** + +## Project Overview + +This plugin adds a new product type named `licensed` to sell software products using license keys. It implements an endpoint to check valid licenses against the WooCommerce payment database. License keys are generated are bounded to a specific domain, which must be defined within the checkout process, and will be available as soon as an order is marked as paid. License keys can optionally be bound to major software versions. Customer can view their purchased license keys in their customer profile. + +### Features + +- Add a new product type named `licensed` +- Generate license keys based on purchased releases, bounded to a specific domain, if the related payment is marked as completed + +#### Frontend + +- Customers can view their purchased licenses in the customer area + +#### Administration + +- Add CRUD for license keys +- Manage different versions of the same licensed product + +### Known Bugs + +_No known bugs at this time._ + +### Key Fact: 100% AI-Generated + +This project is proudly **"vibe-coded"** using Claude.AI - the entire codebase was created through AI assistance. + +## Temporary Roadmap + +**Note for AI Assistants:** Clean this section after the specific features are done or new releases are made. Effective changes are tracked in `CHANGELOG.md` + +### Version 0.0.1 + +- Create the basic structure for a Wordpress/WooCommerce plugin, define `woocommerce` as required dependency +- Find a reasonable solution to implement a rather safe license management using a client-server-model, bound to single domains. The license server hooks into the existing Wordpress REST API +- Start to implement an initial version with the features defined and figured out so far + +## Technical Stack + +- **Language:** PHP 8.3.x +- **Framework:** Latest WordPress Plugin API +- **E-commerce:** WooCommerce 10.0+ +- **Template Engine:** Twig 3.0 (via Composer) +- **Wordpress Base Theme** twentytwentyfive +- **Frontend:** Vanilla JavaScript +- **Styling:** Custom CSS +- **Dependency Management:** Composer +- **Internationalization:** WordPress i18n (.pot/.po/.mo files) +- **Canonical Plugin Name:** `wc-licensed-product` + +### Security Best Practices + +- All user inputs are sanitized (integers for quantities/prices) +- Nonce verification on form submissions +- Output escaping in templates (`esc_attr`, `esc_html`, `esc_js`) +- Direct file access prevention via `ABSPATH` check + +### Translation Ready + +All user-facing strings use: + +```php +__('Text to translate', 'wc-licensed-product') +_e('Text to translate', 'wc-licensed-product') +``` + +Text domain: `wc-licensed-product` + +#### Translation Template + +- Base `.pot` file created: `languages/wc-licensed-product.pot` +- Ready for translation to any locale +- All translatable strings properly marked with text domain + +#### Available Translations + +- `en_US` - English (United States) [base language - .pot template] +- `de_CH` - German (Switzerland, formal) + +To compile translations to .mo files for production: + +```bash +for po in languages/*.po; do msgfmt -o "${po%.po}.mo" "$po"; done +``` + +### Create releases + +- The `vendor/` directory MUST be included in releases (Dependencies required for runtime) +- **Don't create any release files until version 0.1.x and up!** +- **CRITICAL**: Build `vendor/` for the MINIMUM supported PHP version, not the development version + - Use `composer config platform.php 8.3.0` before building release packages + - Run `composer update --no-dev --optimize-autoloader` to rebuild dependencies +- **CRITICAL**: WordPress requires plugins in a subdirectory structure + - Run zip from the `plugins/` parent directory, NOT from within the plugin directory + - Package must extract to `wc-licensed-product/` subdirectory with main file at `wc-licensed-product/wc-licensed-product.php` + - Correct command: `cd /wp-content/plugins/ && zip -r wc-licensed-product/releases/wc-licensed-product-x.x.x.zip wc-licensed-product ...` + - Wrong: Running zip from inside the plugin directory creates files at root level +- **CRITICAL**: Exclude symlinks explicitly - zip follows symlinks by default + - Always use `-x "wc-licensed-product/wp-core" -x "wc-licensed-product/wp-core/*" -x "wc-licensed-product/wp-plugins" -x "wc-licensed-product/wp-plugins/*"` to exclude development symlinks + - Otherwise the entire linked directory contents will be included in the package +- Exclusion patterns must match the relative path structure used in zip command +- Always verify the package structure with `unzip -l` before distribution + - Check all files are prefixed with `wc-licensed-product/` + - Verify main file is at `wc-licensed-product/wc-licensed-product.php` + - Check for duplicate entries (indicates multiple builds in same archive) +- Test installation on the minimum supported PHP version before final deployment +- Releases are stored in `releases/` including checksums +- Track release changes in a single `CHANGELOG.md` file +- Bump the version number to either bugfix release versions or on new features minor release versions +- **CRITICAL**: WordPress reads version from TWO places - BOTH must be updated: + 1. Plugin header comment `Version: x.x.x` (line ~6 in wp-artists.php) - WordPress uses THIS for admin display + 2. PHP constant `WC_LICENSED_PRODUCT_VERSION` (line ~25) - Used internally by the plugin + - If only the constant is updated, WordPress will show the old version in Plugins list + +**Important Git Notes:** + +- Default branch while development is `dev` +- Create releases from branch `main` after merging branch `dev` +- Tags should use format `vX.X.X` (e.g., `v1.1.22`), start with v0.1.0 +- Use annotated tags (`-a`) not lightweight tags +- Commit messages should follow the established format with Claude Code attribution +- `.claude/settings.local.json` changes are typically local-only (stash before rebasing) + +#### What Gets Released + +- All plugin source files +- Compiled vendor dependencies +- Translation files (.mo compiled from .po) +- Assets (CSS, JS) +- Documentation (README, CHANGELOG, etc.) + +#### What's Excluded + +- Git metadata (`.git/`) +- Development files (`.vscode/`, `.claude/`, `CLAUDE.md`, `wp-core`, `wp-plugins`) +- Logs and cache files +- Previous releases +- `composer.lock` (but `vendor/` is included) + +--- + +**For AI Assistants:** + +When starting a new session on this project: + +1. Read this CLAUDE.md file first +2. Semantic versioning follows the `MAJOR.MINOR.BUGFIX` pattern +3. Check git log for recent changes +4. Verify you're on the `dev` branch before making changes +5. Run `composer install` if vendor/ is missing +6. Test changes before committing +7. Follow commit message format with Claude Code attribution +8. Update this session history section with learnings +9. Never commit backup files (`*.po~`, `*.bak`, etc.) - check `git status` before committing +10. Follow markdown linting rules (see below) + +Always refer to this document when starting work on this project. + +### Markdown Linting Rules + +When editing CLAUDE.md or other markdown files, follow these rules to avoid linting errors: + +1. **MD031 - Blank lines around fenced code blocks**: Always add a blank line before and after fenced code blocks, even when they follow list items. Example of correct format: + + - **Item label**: + + (blank line here) + \`\`\`php + code example + \`\`\` + (blank line here) + +2. **MD056 - Table column count**: Table separators must have matching column counts and proper spacing. Use consistent dash lengths that match column header widths. + +3. **MD009 - No trailing spaces**: Remove trailing whitespace from lines + +4. **MD012 - No multiple consecutive blank lines**: Use only single blank lines between sections + +5. **MD040 - Fenced code blocks should have a language specified**: Always add a language identifier to code blocks (e.g., `txt`, `bash`, `php`). For shortcode examples, use `txt`. + +6. **MD032 - Lists should be surrounded by blank lines**: Add a blank line before AND after list blocks, including after bold labels like `**Attributes:**`. + +7. **MD034 - Bare URLs**: Wrap URLs in angle brackets (e.g., ``) or use markdown link syntax `[text](url)`. + +8. **Author section formatting**: Use a heading (`### Name`) instead of bold (`**Name**`) for the author name to maintain consistent document structure.