wp-plugin-swiss-football-matchdata/README-DEV.md

# Swiss Football Matchdata — Developer Setup Guide

This guide explains how to set up the development environment after checking out the project from Git and how to generate a distribution-ready package.

## Prerequisites

Before starting, ensure you have the following installed on your system:

- **Node.js** (LTS 18.x or newer) - [download](https://nodejs.org/)
- **npm** (comes with Node.js)
- **Git** (for cloning and version control)
- **PHP 7.4+** (for running WordPress locally, if developing)
- **WordPress** (local development installation recommended)

Verify installations:

```bash
node --version
npm --version
php --version
```

## Initial Setup After Git Checkout

### 1. Clone the Repository

```bash
git clone <repository-url> swiss-football-matchdata
cd swiss-football-matchdata
```

### 2. Install Dependencies

Install all npm dependencies required for building the Gutenberg editor blocks:

```bash
npm install
```

This reads `package.json` and installs:

- `@wordpress/scripts` — WordPress build tooling (webpack, babel, eslint)

### 3. Build the Editor Bundle

Create the compiled editor JavaScript bundle that the plugin requires:

```bash
npm run build
```

This command:

- Runs `wp-scripts build --output-path=assets/build`
- Uses the custom `webpack.config.js` to ensure output is named `editor-blocks.js`
- Generates additional asset files in `assets/build/`
- **Result**: `assets/build/editor-blocks.js` is now ready for use

### 4. Verify the Build

Check that the compiled bundle exists:

```bash
ls -lh assets/build/editor-blocks.js
```

You should see a JavaScript file (typically 50-150 KB depending on dependencies).

## Development Workflow

### Live Development with Hot Reload

For active development with automatic recompilation and browser refresh:

```bash
npm run start
```

This starts the WordPress development server with:

- **File watching**: Changes to `src/editor-blocks.js` trigger rebuilds
- **Hot module reload**: Changes appear in the editor without full page refresh
- **Source maps**: Easier debugging in browser DevTools

Press `Ctrl+C` to stop the server.

### Project Structure

```tree
swiss-football-matchdata/
├── src/
│   ├── editor-blocks.js         # Main editor block components
│   ├── format-shortcode.js       # Shortcode formatting toolbar
│   ├── index.js                  # Package entry point
│   └── [other source files]
├── blocks/                       # Block definitions (metadata)
│   ├── context/
│   ├── match-events/
│   ├── match-bench/
│   ├── match-referees/
│   ├── match-roster/
│   ├── schedule/
│   ├── standings/
│   └── shortcode-inserter/
├── assets/
│   ├── build/
│   │   ├── editor-blocks.js     # Compiled output (generated)
│   │   ├── editor-blocks.asset.php  # Asset dependencies (generated)
│   │   └── [other generated assets]
│   ├── admin.js / admin.css      # Admin-only frontend code
│   ├── blocks.js / blocks.css    # Public frontend code
│   └── [other assets]
├── includes/                     # PHP backend
│   ├── class-swi-foot-admin.php
│   ├── class-swi-foot-api.php
│   ├── class-swi-foot-blocks.php
│   ├── class-swi-foot-rest.php
│   └── class-swi-foot-shortcodes.php
├── languages/                    # Translation files (i18n)
├── tests/                        # Test files
├── webpack.config.js             # Custom webpack configuration
├── package.json                  # npm dependencies and scripts
├── README.md                      # User documentation
├── DEV-README.md                 # Legacy build notes
└── README-DEV.md                 # This file
```

## Editing WordPress Blocks

### Block Files

Each block is defined in its own directory under `blocks/`:

- `block.json` — Block metadata (name, icon, attributes, supports)
- The React component code lives in `src/editor-blocks.js`

### Example Workflow

1. **Edit block in editor** (`src/editor-blocks.js`):
   - Add UI elements (SelectControl, TextControl, etc.)
   - Implement save logic that generates shortcodes
   - Update attribute definitions

2. **Test with hot reload**:

   ```bash
   npm run start
   ```

- Hard-refresh your WordPress editor page
- Make changes in `src/editor-blocks.js`
- The browser auto-updates (HMR)

3. **Verify output**:
   - Insert/edit the block in WordPress
   - Check browser DevTools → Network → look for `editor-blocks.js`
   - Look at page source to verify shortcode is generated correctly

4. **Build for production**:

   ```bash
   npm run build
   ```

## Code Quality

### Linting and Formatting

The `@wordpress/scripts` package includes eslint configuration. WordPress code standards are automatically enforced on `.js` files in the project.

To fix common issues automatically:

```bash
npx eslint src/ --fix
```

### PHP Code

PHP files follow standard WordPress coding standards. Check syntax:

```bash
php -l includes/class-swi-foot-blocks.php
```

(or any other PHP file)

### Managing Translations

Translation files include:

- **`.po` files** — Human-editable source translations (one per language)
- **`.pot` file** — Translation template (extraction from source code)
- **`.mo` files** — Compiled binary translations (generated from `.po` files)

**Workflow when adding new translatable strings:**

1. Add translation strings to PHP or JavaScript with proper functions and translator comments:

   ```php
   /* translators: %s is the API error message */
   __('Error loading data: %s', 'swi_foot_matchdata')
   
   _e('Text to display', 'swi_foot_matchdata')
   ```

   **Important**: Always add `/* translators: ... */` comments above i18n functions with placeholders to clarify their meaning for translators.

2. Extract strings and update translation files using the i18n management script:

   ```bash
   ./dev-scripts/i18n-manage.sh extract
   ```

   This extracts all strings to `languages/swi_foot_matchdata.pot`.

3. Generate `.po` files for translation:

   ```bash
   ./dev-scripts/i18n-manage.sh translate
   ```

   Creates/updates `.po` files for: German (de_DE), French (fr_FR), Italian (it_IT), English (en_US)

4. Provide `.po` files to translators:

   - Translators edit `languages/swi_foot_matchdata-de_DE.po`, `-fr_FR.po`, `-it_IT.po`
   - They can use PoEdit, Crowdin, or any PO file editor
   - Translator comments help clarify placeholder meanings

5. After translations are complete, compile `.mo` files:

   ```bash
   ./dev-scripts/i18n-manage.sh build
   ```

   Generates binary `.mo` files from `.po` files.

6. Commit both `.po` and `.mo` files to git:

   ```bash
   git add languages/*.po languages/*.mo
   git commit -m "Update translations for [feature/language]"
   ```

7. (Optional) Clean up regional variants:

   ```bash
   ./dev-scripts/i18n-manage.sh clean
   ```

   Removes regional variants (de_AT, de_CH) to keep only core languages.

**Note**: Editor backup files (`.po~`) are **not** committed (ignored by `.gitignore`).

The `.mo` files are essential for distribution — they're included in both git commits and distribution packages so installations work immediately without requiring a build step.

### Complete i18n Workflow with Script

The `i18n-manage.sh` script automates the entire translation pipeline:

```bash
# Run complete workflow (extract → translate → build → clean)
./dev-scripts/i18n-manage.sh all
```

This is equivalent to running:
```bash
./dev-scripts/i18n-manage.sh extract     # Extract strings to .pot
./dev-scripts/i18n-manage.sh translate   # Generate .po files for each language
./dev-scripts/i18n-manage.sh build       # Compile .po to .mo files
./dev-scripts/i18n-manage.sh clean       # Remove regional variants
```

**Supported Languages (by default)**:
- de_DE — German
- fr_FR — French
- it_IT — Italian
- en_US — English

**Script Configuration**:

Edit `dev-scripts/i18n-manage.sh` lines 39-60 to customize:
- `WP_CLI_CMD` — WordPress CLI command (for Docker or local)
- `LANGUAGES` — Supported language codes
- `REGIONAL_VARIANTS` — Variants to remove during cleanup

**Best Practices**:

- Always add translator comments for strings with placeholders
- Use ordered placeholder syntax: `%1$d`, `%2$s` (not just `%d`, `%s`)
- Keep strings complete and translatable (don't break into fragments)
- Commit `.po` and `.mo` files to git along with source changes

For detailed documentation, see:
- `dev-docs/I18N_QUICK_REFERENCE.md` — Quick start guide
- `dev-docs/I18N_OPTIMIZATIONS.md` — Best practices and examples

## Testing in Development

### Local WordPress Installation

For testing the complete plugin:

1. **Place the plugin in WordPress**:

   ```bash
   # Assuming WordPress is at /path/to/wordpress
   cp -r . /path/to/wordpress/wp-content/plugins/swiss-football-matchdata
   ```

2. **Activate the plugin**:

   - Go to WordPress Admin → Plugins
   - Find "Swiss Football Matchdata"
   - Click "Activate"

3. **Test blocks**:

   - Create a new post/page
   - Insert blocks using the editor
   - Verify blocks are available and functional
   - Hard-refresh browser to clear cache after rebuilds

### Browser DevTools Checklist

- **Console**: Watch for JavaScript errors
- **Network**: Verify `editor-blocks.js` loads correctly
- **Sources**: Use source maps to debug original `.js` files
- **Application → Storage**: Clear LocalStorage/IndexedDB if blocks misbehave

## Building for Distribution

### 1. Ensure Clean Build

```bash
# Remove old build artifacts (optional)
rm -rf assets/build

# Install fresh dependencies
npm ci  # (instead of npm install - more reproducible)

# Build
npm run build
```

### 2. Verify Build Output

```bash
# All required files should exist
test -f assets/build/editor-blocks.js && echo "✓ Editor bundle present"
test -f assets/build/editor-blocks.asset.php && echo "✓ Asset manifest present"
```

### 3. Create Distribution Package

#### Using the Build Script (Recommended)

A convenience bash script is included to automate distribution packaging:

```bash
./dev-scripts/build-distribution.sh
```

This script:

- Creates a clean working directory
- Excludes all development files and dependencies
- Includes only files needed for distribution
- Generates a ZIP archive
- Displays summary information

**Excluded from the distribution**:

- `node_modules/` (development dependencies)
- `src/` (source code for building)
- `test/` (test files)
- `package.json` / `package-lock.json`
- `webpack.config.js` (build config)
- `dev-scripts/` (development scripts)
- `README-DEV.md` (developer guide)
- `.git`, `.gitignore`, `.DS_Store`, and other system files

#### Manual Packaging (Alternative)

If you prefer to create the distribution manually:

```bash
# Create a clean directory for the distribution
mkdir -p dist
PLUGIN_NAME="swiss-football-matchdata"

# Copy all plugin files (excluding development files)
rsync -av --exclude='.git' \
  --exclude='node_modules' \
  --exclude='.npm-cache' \
  --exclude='package-lock.json' \
  --exclude='.gitignore' \
  --exclude='README-DEV.md' \
  --exclude='.DS_Store' \
  --exclude='*.swp' \
  --exclude='.idea/' \
  --exclude='test/' \
  --exclude='src/' \
  --exclude='webpack.config.js' \
  . dist/$PLUGIN_NAME/

# Create ZIP archive
cd dist
zip -r "$PLUGIN_NAME.zip" $PLUGIN_NAME/
cd ..

# Result: dist/swiss-football-matchdata.zip
echo "Distribution package created: dist/$PLUGIN_NAME.zip"
```

### 4. Verify Distribution Package

```bash
# What's in the ZIP?
unzip -l dist/swiss-football-matchdata.zip | head -30

# Should include:
# ✓ swiss-football-matchdata.php (main plugin file)
# ✓ assets/build/editor-blocks.js (compiled bundle)
# ✓ includes/*.php (backend code)
# ✓ README.md (user documentation)

# Should NOT include:
# ✗ node_modules/ (development dependencies)
# ✗ package.json / package-lock.json
# ✗ README-DEV.md (developer guide)
# ✗ src/ (source code — users don't need it)
# ✗ test/ (test files)
# ✗ webpack.config.js (build configuration)
# ✗ .git (git history)
```

### 5. Size Check

The distribution ZIP should be reasonable in size:

- **With `assets/build/editor-blocks.js`**: ~150–300 KB
- **Typical unzipped size**: ~800 KB–2 MB

If significantly larger, check for unwanted files:

```bash
unzip -l dist/swiss-football-matchdata.zip | sort -k4 -rn | head -20
```

## Deployment / Installation

### For Site Administrators (Users)

Users install the distribution ZIP file normally:

1. Go to WordPress Admin → Plugins → Add New → Upload Plugin
2. Select the `.zip` file
3. Activate

**Important**: The plugin expects `assets/build/editor-blocks.js` to be present. Always run `npm run build` before packaging.

### For Developers on Target Site

If deploying to a site where you're also developing:

```bash
# Copy the plugin to WordPress
cp -r . /path/to/wordpress/wp-content/plugins/swiss-football-matchdata

# Navigate to plugin directory
cd /path/to/wordpress/wp-content/plugins/swiss-football-matchdata

# Ensure build is present (if needed)
npm ci && npm run build
```

## Continuous Integration (Optional)

### GitHub Actions Example

Add to `.github/workflows/build.yml`:

```yaml
name: Build and Verify

on:
  push:
    branches: [ main, develop ]
  pull_request:
    branches: [ main ]

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      
      - name: Setup Node.js
        uses: actions/setup-node@v3
        with:
          node-version: '18'
          cache: 'npm'
      
      - name: Install dependencies
        run: npm ci
      
      - name: Build editor bundle
        run: npm run build
      
      - name: Verify build output
        run: |
          test -f assets/build/editor-blocks.js || exit 1
          test -f assets/build/editor-blocks.asset.php || exit 1          
      
      - name: PHP Syntax Check
        run: |
          find includes -name "*.php" -exec php -l {} \;          
```

This ensures:

- Every push/PR has a valid build
- Missing build artifacts fail visibly
- PHP code is syntactically correct

## Troubleshooting

### Build Fails with Module Not Found

**Problem**: `npm run build` fails with "module not found"

**Solution**:

```bash
rm package-lock.json
npm install
npm run build
```

### Changes Don't Appear in Editor

**Problem**: Edited `src/editor-blocks.js` but changes don't show in WordPress

**Solutions**:

1. Hard-refresh browser: `Cmd+Shift+R` (Mac) or `Ctrl+Shift+R` (Windows/Linux)
2. Clear WordPress cache (if caching plugin is active)
3. Verify `assets/build/editor-blocks.js` was updated: `ls -l assets/build/editor-blocks.js`
4. Check browser console for JavaScript errors

### `npm start` Doesn't Work

**Problem**: Development server won't start

**Solution**:

```bash
# Kill any existing Node process on port 8888
lsof -i :8888 | grep -v PID | awk '{print $2}' | xargs kill -9

# Restart
npm start
```

### PHP Errors

**Problem**: Plugin doesn't activate or causes errors

**Solutions**:

1. Check WordPress error log: `wp-content/debug.log`
2. Verify PHP version: `php --version` (should be 7.4+)
3. Check file permissions: `chmod -R 755 includes/`
4. Look for syntax errors: `php -l includes/class-swi-foot-blocks.php`

## Quick Reference

| Task | Command |
|------|---------|
| Install deps | `npm install` |
| Build for production | `npm run build` |
| Development with hot reload | `npm start` |
| Extract and translate strings | `./dev-scripts/i18n-manage.sh all` |
| Create distribution ZIP | `./dev-scripts/build-distribution.sh` |
| Check PHP syntax | `php -l includes/class-swi-foot-blocks.php` |
| Fix linting issues | `npx eslint src/ --fix` |

## API Reference

This plugin integrates with the Swiss Football Association Club API. The API structure and endpoints are documented in the OpenAPI/Swagger specification:

**Swagger UI**: https://stg-club-api-services.football.ch/swagger/index.html

This documentation provides:

- All available REST endpoints
- Request/response schemas
- Authentication requirements
- Rate limits and performance guidelines
- Example requests and responses

Refer to this documentation when:

- Adding new API integrations
- Understanding the data structures used in the plugin
- Debugging API-related issues
- Extending plugin functionality with additional endpoints

## Additional Resources

- [WordPress Block Editor Handbook](https://developer.wordpress.org/block-editor/)
- [WordPress Plugin Handbook](https://developer.wordpress.org/plugins/)
- [@wordpress/scripts Documentation](https://developer.wordpress.org/block-editor/reference-guides/packages/packages-scripts/)
- [WordPress Coding Standards](https://developer.wordpress.org/coding-standards/)
- [Swiss Football Club API Swagger Specification](https://stg-club-api-services.football.ch/swagger/index.html)

## Support

For issues or questions:

1. Check existing Git issues
2. Review comments in the relevant PHP/JavaScript files
3. Consult the main [README.md](README.md) for user-facing documentation
4. See [DEV-README.md](DEV-README.md) for legacy build notes

---

Last updated: March 2026