# Development Guide

This guide covers how to set up the development environment, build assets, and contribute to Antom Payments for WooCommerce.

## Prerequisites

- **Node.js** (LTS version recommended — 18.x or 20.x)
- **npm** (bundled with Node.js)
- **PHP** 7.2 or higher
- **Composer** (for PHP dependency management and linting)
- **WooCommerce** (local installation for testing)
- **WordPress** (local installation for testing)

## Setup

### 1. Clone the Repository

```bash
git clone <repository-url>
cd woo-antom-paymnets
```

### 2. Install Node Dependencies

```bash
npm install
```

This installs:
- `@wordpress/scripts` — WordPress build toolchain (Webpack, Babel, ESLint)
- `@woocommerce/dependency-extraction-webpack-plugin` — WooBlocks dependency management
- `sass` — SCSS compilation
- `@alipay/ams-checkout` — Antom Elements SDK (card payment)
- `credit-card-type` — Card brand detection utility

### 3. Install PHP Dependencies (for linting)

```bash
composer install
```

## Development Commands

### Start Watch Mode

```bash
# Run both Block JS and CSS watchers in parallel
npm start

# Or run individually:
npm run start:blocks   # Webpack watch mode → compiles to assets/blocks/
npm run start:css      # Sass watch mode → compiles to assets/css/
```

### Production Build

```bash
# Build Block JS + CSS with minification and source maps
npm run build

# Or individually:
npm run build:blocks   # Production Webpack build
npm run build:css      # Production Sass build (compressed + source maps)
```

### Linting

```bash
# PHP CodeSniffer
npm run lint:php

# Auto-fix PHP issues
npm run lint:php-fix
```

## Project Structure for Development

### Frontend Source

```
resource/
├── blocks/          # WooCommerce Block Checkout React components
│   ├── alipay_cn.js
│   ├── alipay_hk.js
│   ├── card.js
│   ├── dana.js
│   ├── gcash.js
│   ├── kakao_pay.js
│   ├── naver_pay.js
│   ├── payments.js     # CKP (Cashier Payment) block
│   ├── tng.js
│   ├── toss_pay.js
│   └── true_money.js
├── components/      # Shared React components
│   ├── antom-card-fields.js     # Card field rendering (Elements SDK)
│   ├── card-pay-fields.js        # Card pay integration
│   ├── custom-label.js
│   ├── default-content.js
│   ├── dynamic-label.js
│   └── test-mode-warning.js
├── hooks/
│   └── useAntomPaymentsSettings.js
└── css/             # SCSS source files
    ├── antom-payments-b27-admin.scss
    ├── antom-payments-b27-frontend.scss
    ├── antom-payments-gateway-admin.scss
    ├── antom-payments-gateway-frontend.scss
    └── antom-settings-payments.scss
```

### Frontend Build Output

```
assets/
├── blocks/          # Compiled Block JS (entry points + asset.php manifests)
├── css/             # Compiled CSS (with source maps in production)
└── js/              # Third-party JS libraries and frontend/backend scripts
```

### Adding a New Payment Method

To add a new payment method:

1. Create gateway class: `includes/gateways/class-wc-gateway-antom-{method}.php`
   - Extend `WC_Gateway_Antom_Common`
   - Implement `process_payment()` and any method-specific logic

2. Create block support class: `includes/blocks/class-wc-gateway-antom-{method}-block-support.php`
   - Extend `WC_Gateway_Antom_Block_Support_Common`

3. Create block component: `resource/blocks/{method}.js`
   - Register via `registerPaymentMethod` from WooCommerce Blocks registry

4. Register in `antom_get_payment_methods()` in `includes/antom-payment-gateway-settings.php`

5. Add method icon: `assets/images/{Method}-A+.svg`

6. Build the assets:
   ```bash
   npm run build
   ```

## PHP Coding Standards

This project follows the WordPress PHP Coding Standards. PHP linting uses PHP CodeSniffer with a `phpcs.xml` configuration file.

```bash
# Check PHP files
npm run lint:php

# Auto-fix issues
npm run lint:php-fix
```

## JavaScript Build Configuration

The project uses `@wordpress/scripts` (Webpack) for building JavaScript. Key configuration points in `webpack.config.js`:

- **Entry Points** — Each block JS file in `resource/blocks/` is a separate entry point
- **Output** — Compiled files go to `assets/blocks/`
- **Dependency Extraction** — WooCommerce and WordPress dependencies are externalized (not bundled)

## Version Compatibility

| Component | Minimum | Tested Up To |
|---|---|---|
| WordPress | 5.3 | 6.9 |
| WooCommerce | 8.0+ | 9.0.0 |
| PHP | 7.2 | 8.x |
| HPOS | Yes | Latest |

## Translation

The plugin is translation-ready with text domain `antom-payments`.

- Language files location: `/languages/`
- Translation functions used: `__()`, `esc_html__()`, `esc_html_e()`

To generate a `.pot` file for translation:

```bash
wp i18n make-pot . languages/antom-payments.pot
```

## Testing

### Manual Testing

1. Set up a local WordPress + WooCommerce installation
2. Enable **Test Mode** in plugin settings
3. Use sandbox credentials from Antom Merchant Portal
4. Place test orders with different payment methods
5. Check order statuses and webhook notifications

### Note on Automated Tests

The plugin currently does not include automated unit or integration tests. Test coverage is manual. Contributions adding test coverage are welcome.

## Debugging

Enable WordPress debug mode in `wp-config.php`:

```php
define('WP_DEBUG', true);
define('WP_DEBUG_LOG', true);
define('WP_DEBUG_DISPLAY', false);
```

Logs are written to `/wp-content/debug.log`. Key events logged:
- Payment session creation requests and responses
- Webhook notification receipts
- Payment inquiry results
- Refund processing
- Error conditions and exceptions

## Git Workflow

```bash
# Create a feature branch
git checkout -b feature/my-feature

# Make changes and commit
git add .
git commit -m "feat: description of the change"

# Rebase on latest master
git checkout master
git pull
git checkout feature/my-feature
git rebase master

# Push and create PR
git push origin feature/my-feature
```

### Commit Message Convention

Use conventional commit format:
- `feat:` — New feature
- `fix:` — Bug fix
- `chore:` — Maintenance tasks
- `docs:` — Documentation changes
- `refactor:` — Code refactoring
- `style:` — Code style/formatting (non-functional)

## See Also

- [Architecture Overview](architecture.md) — System architecture
- [Webhook & API Reference](webhook-api.md) — API details
- [Configuration Guide](configuration.md) — Settings reference