From fbe68a5124a5b7d60561266b5993e6c25e51100b Mon Sep 17 00:00:00 2001 From: Dennis Ploetner Date: Wed, 22 Oct 2025 12:33:01 +0200 Subject: [PATCH 1/2] Documenation added --- .phpcs.xml.dist | 2 +- AGENTS.md | 35 +++++++++++++++++++++++++++++++++++ README.md | 26 +++++++++++++++++++++++++- composer.json | 4 ++-- 4 files changed, 63 insertions(+), 4 deletions(-) create mode 100644 AGENTS.md diff --git a/.phpcs.xml.dist b/.phpcs.xml.dist index 4d0b4c1..1e70209 100644 --- a/.phpcs.xml.dist +++ b/.phpcs.xml.dist @@ -1,6 +1,6 @@ - PHPCS MslsMenu configuration + PHPCS MslsSelect configuration bin/* tests/* diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 0000000..966e1d4 --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,35 @@ +# Repository Guidelines + +## Project Structure & Module Organization +- `MslsSelect.php` bootstraps the plugin and stays the single PHP entry point. +- `js/mslsselect.js` (with the minified twin) powers the UI; update both when tweaking frontend behavior. +- `tests/` houses PHPUnit specs and Brain Monkey helpers; keep fixtures beside the tests that use them. +- `bin/` contains contributor utilities (`git-release.sh`, githooks); call these scripts instead of duplicating logic. +- `mslsselect/` and `mslsselect.zip` are release artifacts regenerated only through the build script. + +## Build, Test, and Development Commands +- `composer install` installs PHP tooling; rerun after dependency bumps or fresh clones. +- `composer test` executes the PHPUnit suite defined by `phpunit.xml`. +- `composer phpstan` runs static analysis; clear warnings before opening a PR. +- `composer coverage` writes HTML reports to `coverage/` (requires Xdebug). +- `composer githooks` copies the pre-commit hook into `.git/hooks/`. +- `composer build` invokes `bin/git-release.sh` and refreshes the distributable. + +## Coding Style & Naming Conventions +- Follow WordPress PHP style: tabs for indentation, PascalCase classes, `snake_case` functions prefixed with `mslsselect_`. +- Lint PHP via `vendor/bin/phpcs --standard=WordPress MslsSelect.php tests` before committing. +- Mirror the spacing and semicolon usage already present in `js/mslsselect.js` for JavaScript updates. + +## Testing Guidelines +- Name PHPUnit classes `*Test.php` and mirror the namespace or class they cover. +- Use Brain Monkey helpers for WordPress hooks instead of creating globals manually. +- Run `composer test` before pushing; prefer regression cases that assert rendered HTML or hook behavior. + +## Commit & Pull Request Guidelines +- Write concise, imperative commit subjects (`Add select placeholder`) and reference issues in the body (`Refs #123`) when relevant. +- Summarize scope, manual testing, and screenshots (for UI changes) in every PR. +- Confirm local parity with CI by running `composer install`, `composer phpstan`, and `composer test` prior to review. + +## Release & Packaging Notes +- Use `composer build` to regenerate `mslsselect/` and `mslsselect.zip`; avoid manual edits to packaged files. +- Before tagging, check the zip for `MslsSelect.php`, the JavaScript bundle, and required `vendor/` dependencies. diff --git a/README.md b/README.md index a68b1c1..9ec4bfb 100644 --- a/README.md +++ b/README.md @@ -4,4 +4,28 @@ MslsSelect [![Scrutinizer Code Quality](https://scrutinizer-ci.com/g/lloc/MslsSelect/badges/quality-score.png?b=master)](https://scrutinizer-ci.com/g/lloc/MslsSelect/?branch=master) [![codecov](https://codecov.io/gh/lloc/MslsSelect/graph/badge.svg?token=W1CM7ZXXWM)](https://codecov.io/gh/lloc/MslsSelect) -Transforms the output of the Multisite Language Switcher to an HTML select \ No newline at end of file +Transforms the output of the Multisite Language Switcher to an HTML select + +## Requirements +- WordPress 5.6 or higher running in multisite mode. +- [Multisite Language Switcher](https://wordpress.org/plugins/multisite-language-switcher/) plugin (MslsSelect replaces its default list output). +- PHP 7.4+ to match the plugin minimum. + +## Installation +1. Install via the WordPress admin: go to `Plugins → Add New`, search for **MslsSelect**, and click *Install Now*. +2. Or install manually by uploading the latest `mslsselect.zip` to `wp-content/plugins`. +3. Activate **MslsSelect** network-wide (or on selected sites); the frontend hooks load automatically. + +## Usage +- Wherever Multisite Language Switcher renders its language list (widget, block, or `the_msls()` template tag), MslsSelect swaps the markup for a `` uses the `msls_languages` class; target it in your theme for styling, e.g.: + + ```css + .msls_languages { max-width: 220px; } + ``` +- No additional configuration is required. The plugin ensures the current site stays in the list by updating the `msls` option when needed. + +## Troubleshooting +- If you still see a list instead of a dropdown, confirm the Multisite Language Switcher plugin is active and outputting links on that template. +- Clear page caches or CDN layers after activation so the new markup and JavaScript load correctly. +- Check the browser console for JavaScript errors; the minified file is enqueued as `mslsselect` if you need to debug or dequeue it temporarily. diff --git a/composer.json b/composer.json index f1a8a7b..0358272 100644 --- a/composer.json +++ b/composer.json @@ -14,11 +14,11 @@ ] }, "require-dev": { - "phpunit/phpunit": "~9.6", "brain/monkey": "2.*", + "phpstan/extension-installer": "^1.1", "phpstan/phpstan": "^1.8", + "phpunit/phpunit": "~9.6", "szepeviktor/phpstan-wordpress": "^1.1", - "phpstan/extension-installer": "^1.1", "wp-coding-standards/wpcs": "^3.0" }, "scripts": { From 14e16e80f8bb411b6ac8f9ee146e25a8d66657b5 Mon Sep 17 00:00:00 2001 From: Dennis Ploetner Date: Wed, 22 Oct 2025 12:40:27 +0200 Subject: [PATCH 2/2] Dist configuration updated --- .distignore | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.distignore b/.distignore index d784bde..e1c09bb 100644 --- a/.distignore +++ b/.distignore @@ -16,7 +16,7 @@ /tests Changelog.md README.md -composer.json +AGENTS.md composer.lock mslsselect.zip package-lock.json