=== CountryCue for Contact Form 7 ===
Contributors: khavariali
Tags: contact form 7, country, geolocation, calling code
Requires at least: 6.7
Tested up to: 7.1
Requires PHP: 7.4
Requires Plugins: contact-form-7
Stable tag: 1.0.0
License: GPL-3.0-or-later
License URI: https://www.gnu.org/licenses/gpl-3.0.html

Editable country suggestions for Contact Form 7, with calling-code labels and the final selected country in notification emails.

== Description ==

CountryCue adds a country dropdown to Contact Form 7. Visitors can select a country manually or correct a suggestion from supported Cloudways GeoIP or a verified direct Cloudflare connection. Labels include calling codes, such as Cyprus (+357), and your notification email receives the final choice.

* Manual selection works on any host that supports WordPress and Contact Form 7.
* Optional automatic suggestions use existing hosting headers. No paid geolocation API, API key or GPS permission.
* A visitor's selection always takes priority over a delayed suggestion.
* Cached pages use a same-origin, uncached request for each visitor's suggestion.
* Existing telephone fields and raw country values remain unchanged.
* Native select controls, inherited form styling, popup forms and clean resets.
* No early required-field errors caused by automatic country selection. Normal submission validation remains active.

Created by Ali Khavari to solve a practical form problem: suggest a useful country without taking the final choice away from the visitor, and deliver that corrected choice to the person receiving the enquiry.

All features are free. CountryCue is an independent extension; it is not affiliated with Contact Form 7, Cloudways or Cloudflare.

== Installation ==

1. Install and activate Contact Form 7, then upload and activate this plugin.
2. Open Settings > CountryCue. Manual selection is the default. Select a supported country source if you want automatic suggestions.
3. Add this labelled field in your Contact Form 7 Form tab:

`<label>Country
[select* visitor-country class:qhfc-country first_as_label data:qhfc-countries "Select country"]
</label>`

4. Add `Country: [visitor-country]` to your Mail body. Keep your existing phone field and its mail tag unchanged.
5. Submit a test form after changing the suggested country. Verify that your email contains your final choice with its calling code.

Remove the asterisk from `select*` if the country should be optional. A placeholder helps visitors understand the field before making a choice.

= Supported automatic sources =

**Cloudways:** Enable Application Settings > General > Geo IP Detection, then choose Cloudways in CountryCue. This also applies to Cloudways' managed Cloudflare add-on. The application must overwrite X-Forwarded-Country with a trusted host-generated value. Do not select this mode on arbitrary hosting that forwards client-supplied headers.

**Direct Cloudflare:** Enable IP Geolocation and proxy the hostname. The plugin accepts CF-IPCountry only when the original connection address belongs to published Cloudflare IP ranges. If your server replaces REMOTE_ADDR with the visitor IP, ask your host to expose the original TCP peer in the server variable QH_CF_PEER_ADDR. An HTTP header with that name does not establish trust. Do not populate the variable from a visitor-supplied header. Additional proxy layers need correct host configuration; otherwise use manual selection.

**Other hosts:** Use manual selection. Unknown countries, Tor responses, missing headers and unverified Cloudflare peers leave the country for the visitor to choose.

== Frequently Asked Questions ==

= Does this work with every form builder? =

No. It requires WordPress and Contact Form 7. It does not support other form builders or non-WordPress sites.

= Does a calling code change the phone number? =

No. Calling codes are display labels and email information. The plugin does not format, validate or prepend telephone numbers. Territories missing from the bundled calling-code data keep country-only labels. Some countries share a calling code.

= Which country goes into the email? =

`[visitor-country]` uses the final submitted dropdown choice, including a visitor correction, and adds its calling code. Use this tag for normal notifications.

Optional legacy-compatible tags are `[_qh_selected_country]` for the submitted selection, `[_qh_country]` for the provider's estimate, and `[_qh_country_code]` for the estimated two-letter ISO code. These estimates can differ from the submitted selection.

= Will existing email templates change? =

Automatic appending is off by default. You can opt in to a simple country section in the main notification (Mail). It uses the submitted choice, or the estimate if no recognised choice exists. It never automatically appends to Mail (2). Existing country mail tags prevent duplicate appended sections. Optional numeric form IDs limit email enrichment; dropdowns work wherever their tag is added.

= Why is my country wrong or not suggested? =

IP location is an estimate. VPNs, proxies and mobile networks can change it; CountryCue does not detect VPN use. Visitors can correct the result. Confirm your hosting source, check the connection status in Settings > CountryCue, and exclude POST requests to wp-admin/admin-ajax.php from caching. If detection fails, manual selection still works.

= Does the plugin change validation? =

Forms containing the country dropdown defer Contact Form 7's change-time validation until the first submit attempt. Submission validation remains active. Resetting a form restores the initial clean state. CountryCue does not block acceptance checkbox change events.

= What happens without JavaScript? =

The server-rendered country list remains usable and Contact Form 7 handles its normal submission. Automatic suggestions and calling codes in the visible dropdown require JavaScript; email calling codes are added on the server.

= How do I remove the plugin? =

First remove the dynamic country field from your forms or replace it with static values, and remove its custom mail tags. Deactivation stops its data provider and scheduled task. Deletion removes CountryCue settings, cached ranges and diagnostic metadata, including across multisite. Forms and email templates are never edited automatically.

== Privacy and external services ==

Manual selection is the default. No remote request is made by CountryCue on activation. Country detection reads headers already supplied by your hosting/CDN; there is no visitor-IP lookup API.

An optional checkbox permits weekly server-side HTTPS downloads from https://www.cloudflare.com/ips-v4/ and https://www.cloudflare.com/ips-v6/ while direct Cloudflare mode is selected. These plain address lists verify the origin connection. The first scheduled download is approximately five minutes after enabling this option, subject to WordPress cron traffic. Both lists must pass validation before either replaces the cached lists. Failed updates retain the last verified data. Disabling consent or changing provider stops these downloads. Without consent, the bundled verified ranges are used.

These list requests disclose the website server's IP address and standard HTTP request metadata (WordPress' default HTTP user-agent may include the site URL) to Cloudflare. They never contain a visitor IP, selected country, form contents or credentials. Cloudflare may log the requests under its own policy.

Cloudflare: https://www.cloudflare.com/privacypolicy/ and https://www.cloudflare.com/website-terms/
Cloudways: https://www.cloudways.com/en/terms.php and https://www.cloudways.com/en/privacy-policy.php

CountryCue sets no cookies, uses no GPS, and creates no submission database. Diagnostic metadata retains only the latest notification check time, detection reason and country code; no visitor IP, name, email or message is stored by this plugin. The submitted country is part of the normal form/email and may be retained by other form-storage plugins. Hosting, CDN and mail-provider logs are outside CountryCue's control. A suggested privacy-policy paragraph is available through WordPress' privacy tools.

The country is self-reported and is not proof of location, nationality or residence.

== Screenshots ==

1. Country suggestion with a calling-code label in a Contact Form 7 form.
2. A visitor-corrected country and the resulting notification email.
3. Settings for manual selection, Cloudways and verified direct Cloudflare, with optional list downloads.
4. Manual selection remains available when no automatic suggestion exists.

== Credits ==

Copyright 2026 Ali Khavari. CountryCue is distributed under GPL-3.0-or-later; see LICENSE.txt.

Country names are derived from umpirsky/country-list (English), MIT; see COUNTRY-DATA-LICENSE.txt and https://github.com/umpirsky/country-list.

Calling-code data is derived from Google libphonenumber PhoneNumberMetadata.xml, retrieved 2026-09-18. Copyright The Libphonenumber Authors, Apache-2.0; see PHONE-DATA-LICENSE.txt and https://github.com/google/libphonenumber/blob/master/resources/PhoneNumberMetadata.xml. The PHP mapping is an extracted country-to-calling-code subset, not the full phone validation library. The combined distribution uses GPLv3-or-later for Apache-2.0 compatibility; third-party notices and licences are preserved.

Bundled Cloudflare public IP ranges were verified 2026-09-18: https://www.cloudflare.com/ips/.

== Changelog ==

= 1.0.0 =
Initial public release. Editable country selection, calling-code labels and final-choice email output. Optional Cloudways/direct Cloudflare suggestions, safe manual defaults, opt-in address-list downloads, neutral styling and privacy documentation.
