homeproz/wp-content/plugins/mls-by-hansonxyz/docs/USAGE.md

# MLS by HansonXyz - User Documentation

## Overview

This plugin syncs property listing data from MLS Grid (NorthStar MLS) into your WordPress database, making it available for use by themes and other plugins.

## Installation

1. Upload the `mls-by-hansonxyz` folder to `/wp-content/plugins/`
2. Activate the plugin through the WordPress admin
3. Configure API credentials (see below)
4. Run initial sync

## Configuration

### API Credentials

Add to your `wp-config.php`:

```php
define('MLSGRID_API_URL', 'https://api.mlsgrid.com/v2');
define('MLSGRID_ACCESS_TOKEN', 'your-access-token-here');
```

Alternatively, configure via Settings > MLS Settings in WordPress admin.

### Settings

Navigate to **Settings > MLS Settings** to configure:

- **Originating System**: MLS identifier (default: `northstar`)
- **Auto Sync**: Enable automatic background sync
- **Sync Interval**: How often to sync (30min to daily)
- **Sync Media**: Whether to download listing photos

## Running Sync

### Via Admin Panel

1. Go to Settings > MLS Settings
2. Click "Run Incremental Sync" or "Run Full Sync"
3. Wait for completion

### Via WP-CLI

#### Smart Sync (Recommended)

The `wp mls run` command is the recommended way to sync. It automatically handles all scenarios:

```bash
wp mls run                    # Smart sync with progress
wp mls run --quiet            # Status messages only
wp mls run --verbose          # Full API details
wp mls run --silent           # For cron (no output)
```

**What it does automatically:**
- If a sync is already running: aborts (prevents duplicates)
- If a previous sync failed/interrupted: resumes it
- If no data exists: runs full sync
- Otherwise: runs incremental sync

Failed syncs are automatically resumed on the next run - no manual intervention needed.

#### Manual Sync Commands

For more control, use the individual sync commands:

```bash
# Test connection first
wp mls test connection
wp mls test auth

# Run initial full sync
wp mls sync full

# Run incremental updates
wp mls sync incremental

# Use --verbose for detailed output
wp mls sync full --verbose
wp mls sync incremental --verbose
```

#### Progress Indicators

During sync, you'll see progress characters:
- `.` = new property
- `#` = updated property
- `x` = deleted property
- `P` = photo downloaded
- `p` = photo skipped (exists)
- `E` = photo error
- `|` = page complete

Use `--verbose` for detailed timestamped output showing API requests and individual items.

### Via Unix Cron

Add to your system crontab (`crontab -e`) for scheduled sync:

```bash
# Smart sync every 15 minutes (recommended)
# Automatically handles: initial sync, incremental updates, and error recovery
*/15 * * * * cd /var/www/html && wp mls run --silent --allow-root >> /var/log/mls-sync.log 2>&1
```

That's it! The `wp mls run` command handles everything automatically:
- First run: performs full initial sync
- Subsequent runs: performs incremental sync
- After failures: resumes from where it left off
- Concurrent runs: safely aborts if another sync is running

**For more control**, use the individual commands:

```bash
# Incremental sync every hour
0 * * * * cd /var/www/html && wp mls sync incremental --allow-root >> /var/log/mls-sync.log 2>&1

# Full sync weekly (Sunday at 3am) to rebuild from scratch
0 3 * * 0 cd /var/www/html && wp mls sync full --allow-root >> /var/log/mls-sync.log 2>&1
```

**Important Notes:**
- Use `--allow-root` when running as root user
- Redirect output to a log file for debugging
- MLS Grid requires refresh at least every 12 hours per IDX rules
- The plugin handles rate limits automatically (waits if approaching limits)
- Media images are fetched on-demand when properties are viewed (no separate cron needed)

### Via WP-Cron (Alternative)

Enable auto-sync in Settings > MLS Settings to use WordPress's built-in cron system. This runs on page loads rather than true system cron, so may be less reliable for high-frequency syncs.

## Checking Status

### Via Admin

Settings > MLS Settings shows:
- Database statistics (property counts by status)
- Last sync time and results
- Rate limit usage

### Via CLI

```bash
# Full status
wp mls status

# Just rate limits
wp mls status rate-limits

# Database statistics
wp mls stats
```

## Using the Data

### For Theme Developers

The plugin provides global helper functions:

```php
// Get active properties in a city
$properties = mls_get_properties([
    'status' => 'Active',
    'city' => 'Albert Lea',
    'limit' => 20,
]);

foreach ($properties as $property) {
    echo $property->list_price;
    echo $property->bedrooms_total;
    echo $property->city;
}

// Get a single property
$property = mls_get_property('NST123456');

// Get property images
$media = mls_get_property_media($property->listing_key);
$primary_image = mls_get_property_image($property->listing_key);

// Get cities with active listings
$cities = mls_get_cities('Active');

// Check if data is available
if (mls_is_available()) {
    // Show property search
}
```

### Query Parameters

`mls_get_properties()` accepts these filters:

| Parameter | Type | Description |
|-----------|------|-------------|
| status | string | Active, Pending, Closed |
| property_type | string | Residential, Land, etc. |
| city | string | City name |
| county | string | County name |
| postal_code | string | ZIP code |
| min_price | int | Minimum price |
| max_price | int | Maximum price |
| min_beds | int | Minimum bedrooms |
| max_beds | int | Maximum bedrooms |
| min_baths | int | Minimum bathrooms |
| min_sqft | int | Minimum square feet |
| max_sqft | int | Maximum square feet |
| search | string | Search address/remarks |
| limit | int | Results per page |
| offset | int | Pagination offset |
| orderby | string | Sort field |
| order | string | ASC or DESC |
| include_media | bool | Include media array |

### Property Object Fields

Each property object includes:

```php
$property->listing_key       // Unique ID
$property->listing_id        // MLS number
$property->list_price        // Price
$property->standard_status   // Active, Pending, Closed
$property->street_number
$property->street_name
$property->street_suffix
$property->city
$property->state_or_province
$property->postal_code
$property->county
$property->latitude
$property->longitude
$property->property_type
$property->property_sub_type
$property->bedrooms_total
$property->bathrooms_total
$property->living_area       // Square feet
$property->lot_size_area
$property->year_built
$property->garage_spaces
$property->public_remarks    // Description
$property->directions
$property->list_office_name
$property->photos_count
$property->days_on_market
$property->modification_timestamp
```

## Media Storage

Downloaded images are stored in:
```
wp-content/uploads/mls-listings/{prefix}/{listing_key}/
```

Images are named by order: `1.jpg`, `2.jpg`, etc.

Access via:
```php
$media = mls_get_property_media($listing_key);
foreach ($media as $image) {
    echo '<img src="' . esc_url($image->local_url) . '">';
}
```

## Troubleshooting

### Connection Failed

1. Verify API token is correct in wp-config.php
2. Check that MLSGRID_API_URL is set
3. Run `wp mls test connection` for details

### No Data After Sync

1. Check `wp mls status` for errors
2. Review rate limits - may need to wait
3. Check WordPress debug log for API errors

### Media Not Downloading

1. Verify `sync_media` is enabled in settings
2. Check upload directory is writable
3. Run `wp mls sync media` manually

### Rate Limit Exceeded

The plugin automatically waits when approaching limits. If suspended:
1. Wait for the rate limit window to reset
2. Reduce sync frequency
3. Contact MLS Grid support if persistent

### Clearing Data

To start fresh:
```bash
wp mls cache clear --confirm
```

This removes all synced data but keeps settings.

### Missing Media Log

Failed media downloads are logged for review:

```bash
# View missing media log
wp mls cache missing

# View first 20 entries
wp mls cache missing --limit=20

# Clear the log
wp mls cache missing --clear
```

Log location: `wp-content/uploads/mls-missing-media.log`

The log shows listing key, media key, error type, and original URL for each failed download. Media downloads automatically retry with exponential backoff (up to 5 attempts) for rate limit and server errors.

## Support

For plugin issues: Check logs at Settings > MLS Settings

For API issues: Contact MLS Grid support at support@mlsgrid.com