# WP BnB Management
A comprehensive Bed & Breakfast management system for WordPress. Manage buildings, rooms, bookings, and guests all within your WordPress admin.
## Description
WP BnB Management enables WordPress to act as a full management system for B&B hosts. It handles multiple buildings with multiple rooms each, bookings, and guest data required for room rentals.
### Key Features
- **Multi-Property Support**: Manage multiple buildings, each with multiple rooms
- **Flexible Pricing**: Configure short-term (nights), mid-term (weeks), and long-term (months) pricing
- **Seasonal Pricing**: Set price modifiers for high/low seasons
- **Booking Management**: Track reservations from inquiry to checkout
- **Guest Management**: Store guest information securely with GDPR compliance
- **Data Encryption**: Sensitive guest data (ID/passport) encrypted at rest
- **Additional Services**: Offer extras like breakfast, parking, or tours
- **Frontend Integration**: Gutenberg blocks, widgets, and shortcodes
- **Auto-Updates**: Automatic update checks and installation from license server
- **Development Mode**: License bypass for local development environments
- **Contact Form 7 Integration**: Accept booking requests and inquiries through CF7 forms
- **Dashboard**: Comprehensive admin dashboard with statistics and charts
- **Reports**: Detailed reports with CSV and PDF export
- **Prometheus Metrics**: Expose operational metrics for monitoring with Grafana
### Requirements
- WordPress 6.0 or higher
- PHP 8.3 or higher
- Valid license key
- Contact Form 7 (optional, for booking forms)
## Installation
1. Download the latest release from the [releases page](https://src.bundespruefstelle.ch/magdev/wp-bnb/releases)
2. Upload the plugin to your `/wp-content/plugins/` directory
3. Activate the plugin through the 'Plugins' menu in WordPress
4. Go to **WP BnB → Settings → License** to enter your license key
5. Configure your business settings under **WP BnB → Settings**
## Configuration
### License Activation
1. Navigate to **WP BnB → Settings → License**
2. Enter your License Server URL
3. Enter your License Key (from purchase confirmation)
4. Enter the Server Secret (from purchase confirmation)
5. Click **Activate License**
### General Settings
- **Business Name**: Your B&B business name
- **Currency**: Select your preferred currency (CHF, EUR, USD, GBP)
- **Business Address**: Street, city, postal code, country
- **Contact Information**: Email, phone, website
- **Social Media**: Facebook, Instagram, X (Twitter), LinkedIn, TripAdvisor
### Update Settings
- **Update Notifications**: Enable/disable update notifications in WordPress
- **Automatic Updates**: Enable/disable automatic plugin updates
- **Check Frequency**: How often to check for updates (1-168 hours)
### Development Mode
The plugin automatically detects local development environments and bypasses license validation. Supported environments:
- localhost, 127.0.0.1, ::1
- Domains ending in .local, .test, .localhost, .dev, .ddev.site
- Private IP ranges (10.x.x.x, 172.16-31.x.x, 192.168.x.x)
## Usage
### Managing Buildings
1. Go to **WP BnB → Buildings**
2. Click **Add New**
3. Enter building details (name, address, description)
4. Add featured image
5. Publish
### Managing Rooms
1. Go to **WP BnB → Rooms**
2. Click **Add New**
3. Select the parent building
4. Configure room details and pricing
5. Add amenities and room type
6. Publish
### Managing Bookings
1. Go to **WP BnB → Bookings**
2. View and manage all reservations
3. Update booking status as guests progress
### Managing Guests
1. Go to **WP BnB → Guests**
2. View guest records and booking history
3. Manage guest information
### Dashboard
The dashboard (**WP BnB → Dashboard**) provides an at-a-glance overview of your B&B operations:
**Statistics Cards:**
- **Occupancy Rate** - Current percentage of rooms occupied with trend indicator
- **Monthly Revenue** - This month's revenue with comparison to previous month
- **Total Bookings** - Active bookings count with status breakdown
- **Total Guests** - Guest count with new guests this month
**Today's Activity:**
- Check-ins scheduled for today with guest names and room assignments
- Check-outs scheduled for today
- Quick links to manage each booking
**Upcoming Bookings:**
- Next 7 days of arrivals
- Guest name, room, dates, and booking status
- Direct links to booking details
**Quick Actions:**
- New Booking - Create a booking directly
- New Guest - Add a guest record
- View Calendar - Open the availability calendar
- View Reports - Access detailed reports
**Trend Charts:**
- 30-day occupancy trend line chart
- 6-month revenue bar chart
### Reports
Access detailed reports at **WP BnB → Reports**. All reports support date range filtering and export.
**Occupancy Report:**
- Overall occupancy percentage for the selected period
- Breakdown by room showing nights booked, available, and occupancy rate
- Visual progress bars for easy comparison
- Total nights booked vs. available across all rooms
**Revenue Report:**
- Total revenue for the selected period
- Revenue breakdown by room
- Revenue breakdown by pricing tier (short-term, mid-term, long-term)
- Revenue from additional services
- Average booking value
**Guest Statistics:**
- Total guests and new guests in period
- Repeat guest rate (guests with 2+ bookings)
- Top guests by total spending
- Guest nationality distribution
- Average spending per guest
**Export Options:**
- **CSV Export** - Download report data as spreadsheet-compatible CSV
- **PDF Export** - Generate formatted PDF reports for printing or archiving
**Date Filters:**
- This Month (default)
- Last Month
- This Year
- Custom date range
## Shortcodes
Display buildings and rooms on your site using shortcodes:
```txt
[bnb_buildings] - List all buildings (grid/list layout)
[bnb_rooms building="123"] - List rooms, optionally filtered by building
[bnb_room_search] - Interactive room search form
[bnb_building id="123"] - Display a single building
[bnb_room id="456"] - Display a single room with availability
```
### Shortcode Attributes
**`[bnb_buildings]`** and **`[bnb_rooms]`**:
- `layout` - "grid" or "list" (default: grid)
- `columns` - 1-4 columns (default: 3)
- `limit` - Number of items (default: 12)
- `orderby` - title, date, price, capacity (default: title)
- `order` - ASC or DESC (default: ASC)
**`[bnb_rooms]`** additional attributes:
- `building` - Building ID to filter by
- `room_type` - Room type slug to filter by
- `amenities` - Comma-separated amenity slugs
## Gutenberg Blocks
The following blocks are available in the block editor:
- **Building** - Display a single building with details
- **Room** - Display a single room with availability form
- **Room Search** - Interactive search form with filters
- **Buildings List** - Display buildings grid/list
- **Rooms List** - Display rooms grid/list with filters
## Widgets
Available sidebar widgets:
- **Similar Rooms** - Show rooms from same building or room type
- **Building Rooms** - List all rooms in a building
- **Availability Calendar** - Mini calendar showing booking status
## Contact Form 7 Integration
The plugin integrates with Contact Form 7 to accept booking requests and inquiries. Custom form tags are provided for room selection, date pickers, and guest counts.
### Custom Form Tags
Use these tags in your CF7 forms:
- `[bnb_building_select name]` - Building dropdown (optional filter for rooms)
- `[bnb_room_select* name]` - Room dropdown with capacity data
- `[bnb_date_checkin* name]` - Check-in date picker
- `[bnb_date_checkout* name]` - Check-out date picker
- `[bnb_guests* name]` - Guest count input
### Tag Options
**`[bnb_building_select]`**:
- `first_as_label:"text"` - Placeholder text (default: "All Locations")
**`[bnb_room_select]`**:
- `building_field:"name"` - Link to building field for filtering
- `first_as_label:"text"` - Placeholder text (default: "Select Room")
**`[bnb_guests]`**:
- `min:N` - Minimum guests (default: 1)
- `max:N` - Maximum guests (default: 10)
- `default:N` - Default value (default: 1)
### Example Booking Form
```txt
```
### Example Inquiry Form
For room-specific inquiries, add the `wp-bnb-inquiry-form` class:
```txt
```
### Form Features
- **Availability Checking**: Real-time AJAX validation shows room availability
- **Price Display**: Estimated total calculated and displayed automatically
- **Room Filtering**: Rooms filter by building selection
- **Date Validation**: Check-out must be after check-in, no past dates
- **Capacity Validation**: Guest count validated against room capacity
- **Automatic Booking**: Booking record created with "pending" status on submission
- **Guest Linking**: Guest records created or linked by email address
### Custom Mail Tags
Use these in your CF7 mail templates:
- `[_bnb_room_name]` - Room title
- `[_bnb_building_name]` - Building name
- `[_bnb_calculated_price]` - Formatted price
- `[_bnb_nights]` - Number of nights
- `[_bnb_booking_reference]` - Booking reference (after creation)
## Hooks and Filters
Developers can customize behavior using these hooks:
```php
// Modify price calculation
add_filter( 'wp_bnb_calculate_price', function( $price, $room_id, $dates ) {
// Custom pricing logic
return $price;
}, 10, 3 );
// Before booking creation
add_action( 'wp_bnb_before_booking_create', function( $booking_data ) {
// Custom validation or logging
} );
```
## Prometheus Metrics
The plugin integrates with [WP Prometheus](https://src.bundespruefstelle.ch/magdev/wp-prometheus) to expose operational metrics for monitoring with Prometheus and Grafana.
### Enabling Metrics
1. Install and activate the WP Prometheus plugin
2. Navigate to **WP BnB → Settings → Metrics**
3. Enable "Expose BnB metrics via Prometheus"
4. Metrics will be available at your site's `/metrics/` endpoint
### Available Metrics
**Inventory Metrics:**
- `wp_bnb_buildings_total` - Total number of buildings
- `wp_bnb_rooms_total{status}` - Rooms by status (available, occupied, maintenance, inactive)
- `wp_bnb_services_total{status}` - Services by status (active, inactive)
- `wp_bnb_total_capacity_beds` - Total bed capacity across all rooms
**Booking Metrics:**
- `wp_bnb_bookings_total{status}` - Bookings by status (pending, confirmed, checked_in, checked_out, cancelled)
- `wp_bnb_checkins_today` - Check-ins scheduled for today
- `wp_bnb_checkouts_today` - Check-outs scheduled for today
- `wp_bnb_bookings_upcoming_7days` - Bookings starting in next 7 days
- `wp_bnb_booking_avg_duration_nights` - Average booking duration
**Occupancy Metrics:**
- `wp_bnb_occupancy_rate_current` - Current room occupancy rate (percentage)
- `wp_bnb_occupancy_rate_this_month` - Monthly occupancy rate (percentage)
- `wp_bnb_rooms_currently_occupied` - Rooms currently occupied
**Revenue Metrics:**
- `wp_bnb_revenue_this_month{currency}` - Revenue for current month
- `wp_bnb_revenue_ytd{currency}` - Revenue year to date
- `wp_bnb_booking_avg_value{currency}` - Average booking value
- `wp_bnb_services_revenue_this_month{currency}` - Services revenue this month
**Guest Metrics:**
- `wp_bnb_guests_total` - Total registered guests
- `wp_bnb_guests_by_status{status}` - Guests by status (active, blocked, vip)
- `wp_bnb_guests_repeat` - Guests with more than one booking
- `wp_bnb_guests_new_this_month` - New guests this month
### Grafana Dashboard
A pre-configured Grafana dashboard is included at `assets/grafana/wp-bnb-dashboard.json`. If WP Prometheus is installed, the dashboard is automatically registered and available for export.
The dashboard includes:
- Occupancy gauges with color-coded thresholds
- Bookings, rooms, and guests pie charts by status
- Revenue and guest statistics panels
- Today's check-ins/check-outs
- Trend indicators
## REST API
The plugin provides a comprehensive REST API for integration with external applications, mobile apps, and third-party services.
### Enabling the API
1. Navigate to **WP BnB → Settings → API**
2. In the **General** subtab, enable "Enable REST API"
3. Optionally enable rate limiting for protection against abuse
4. Configure rate limits in the **Rate Limits** subtab
5. View all available endpoints in the **Endpoints** subtab
### Base URL
All API endpoints are prefixed with:
```txt
https://your-site.com/wp-json/wp-bnb/v1/
```
### Authentication
**Public endpoints** (room listings, availability checks) require no authentication.
**Admin endpoints** (booking management, guest data) require authentication via:
- **Cookie + Nonce**: For same-domain JavaScript requests
- **Application Passwords**: For external applications (WordPress 5.6+, recommended)
To create an Application Password:
1. Go to **Users → Profile**
2. Scroll to "Application Passwords"
3. Enter a name and click "Add New Application Password"
4. Use the generated password with HTTP Basic Auth
```bash
curl -u "username:app-password" https://site.com/wp-json/wp-bnb/v1/bookings
```
### Public Endpoints
| Method | Endpoint | Description |
| ------ | -------- | ----------- |
| GET | `/buildings` | List all buildings |
| GET | `/buildings/{id}` | Get building details |
| GET | `/buildings/{id}/rooms` | Get rooms in a building |
| GET | `/rooms` | List/search rooms |
| GET | `/rooms/{id}` | Get room details |
| GET | `/rooms/{id}/availability` | Check room availability |
| GET | `/rooms/{id}/calendar` | Get monthly calendar data |
| POST | `/availability/search` | Search available rooms |
| GET | `/services` | List all services |
| GET | `/services/{id}` | Get service details |
| POST | `/pricing/calculate` | Calculate booking price |
| POST | `/bookings` | Create a new booking (pending status) |
### Admin Endpoints
| Method | Endpoint | Description |
| ------ | -------- | ----------- |
| GET | `/bookings` | List all bookings |
| GET | `/bookings/{id}` | Get booking details |
| PATCH | `/bookings/{id}` | Update a booking |
| DELETE | `/bookings/{id}` | Cancel a booking |
| POST | `/bookings/{id}/confirm` | Confirm a pending booking |
| POST | `/bookings/{id}/check-in` | Check in a guest |
| POST | `/bookings/{id}/check-out` | Check out a guest |
| GET | `/guests` | List all guests |
| GET | `/guests/{id}` | Get guest details |
| GET | `/guests/search` | Search guests |
| GET | `/guests/{id}/bookings` | Get guest's booking history |
### Rate Limiting
When enabled, rate limits are applied per client (by user ID or IP address). Configure limits in **Settings → API → Rate Limits**.
**Default Limits:**
| Type | Default | Applies To |
| ---- | ------- | ---------- |
| Public | 60/min | Room/building listings |
| Availability | 30/min | Availability and calendar endpoints |
| Booking | 10/min | Booking creation |
| Admin | 120/min | All admin endpoints |
**Configuration Options:**
- **Time Window**: 10-300 seconds (default: 60 seconds)
- **Per-endpoint limits**: Customize for each endpoint type
- **Rate limiting toggle**: Enable/disable without losing settings
Rate limit headers are included in responses:
- `X-RateLimit-Limit`: Maximum requests allowed
- `X-RateLimit-Remaining`: Requests remaining in window
- `X-RateLimit-Reset`: Unix timestamp when limit resets
### Example: Check Room Availability
```bash
curl "https://site.com/wp-json/wp-bnb/v1/rooms/42/availability?check_in=2026-03-15&check_out=2026-03-20"
```
Response:
```json
{
"available": true,
"room_id": 42,
"check_in": "2026-03-15",
"check_out": "2026-03-20",
"nights": 5,
"pricing": {
"base_price": 500.00,
"seasonal_modifier": 1.0,
"weekend_surcharge": 40.00,
"total": 540.00,
"currency": "CHF"
}
}
```
### Example: Create a Booking
```bash
curl -X POST https://site.com/wp-json/wp-bnb/v1/bookings \
-H "Content-Type: application/json" \
-d '{
"room_id": 42,
"check_in": "2026-03-15",
"check_out": "2026-03-20",
"guests": 2,
"guest_info": {
"first_name": "John",
"last_name": "Doe",
"email": "john@example.com",
"phone": "+41 79 123 4567"
},
"services": [
{"service_id": 5, "quantity": 1}
],
"notes": "Late arrival expected"
}'
```
Response:
```json
{
"id": 123,
"reference": "BNB-2026-00042",
"status": "pending",
"room": {
"id": 42,
"title": "Deluxe Suite"
},
"check_in": "2026-03-15",
"check_out": "2026-03-20",
"nights": 5,
"guests": 2,
"pricing": {
"room_total": 540.00,
"services_total": 50.00,
"grand_total": 590.00,
"currency": "CHF"
},
"_links": {
"self": [{"href": "https://site.com/wp-json/wp-bnb/v1/bookings/123"}]
}
}
```
### Example: Search Available Rooms
```bash
curl -X POST https://site.com/wp-json/wp-bnb/v1/availability/search \
-H "Content-Type: application/json" \
-d '{
"check_in": "2026-03-15",
"check_out": "2026-03-20",
"guests": 2,
"amenities": ["wifi", "parking"]
}'
```
### Error Responses
Errors follow WordPress REST API conventions:
```json
{
"code": "rest_not_found",
"message": "Room not found.",
"data": {
"status": 404
}
}
```
Common error codes:
- `rest_invalid_param` (400): Invalid request parameters
- `rest_forbidden` (403): Insufficient permissions
- `rest_not_found` (404): Resource not found
- `rest_conflict` (409): Booking conflict
- `rest_rate_limit_exceeded` (429): Rate limit exceeded
## Frequently Asked Questions
### Do I need a license to use this plugin?
Yes, a valid license is required to use the frontend features in production. The admin functionality works without a license for evaluation purposes. Local development environments (localhost, .local, .test, .dev domains) automatically bypass license validation.
### Can I manage multiple properties?
Yes, you can create unlimited buildings and rooms.
### Is the plugin GDPR compliant?
Yes, guest data can be exported and deleted on request, and consent is tracked appropriately.
### Does it integrate with WooCommerce?
WooCommerce integration for payments is planned for a future release.
### How is guest data secured?
Sensitive guest data like passport/ID numbers are encrypted using AES-256-CBC encryption before storage. The encryption key is derived from your WordPress AUTH_KEY, ensuring data is secure at rest.
## Changelog
See [CHANGELOG.md](CHANGELOG.md) for a detailed list of changes.
## Support
For support, please create an issue at:
## Author
**Marco Graetsch**
- Website:
- Email:
## License
GPL-2.0-or-later
This plugin is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 2 of the License, or any later version.