{"id":31241639,"url":"https://github.com/arraypress/wp-referrer-utils","last_synced_at":"2026-01-20T16:39:50.890Z","repository":{"id":312870275,"uuid":"1020706437","full_name":"arraypress/wp-referrer-utils","owner":"arraypress","description":"A lean WordPress library for HTTP referrer detection and analysis.","archived":false,"fork":false,"pushed_at":"2025-09-08T19:24:59.000Z","size":9,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-09-23T00:20:54.850Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"PHP","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/arraypress.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-07-16T09:16:52.000Z","updated_at":"2025-09-08T19:25:03.000Z","dependencies_parsed_at":"2025-09-02T15:14:34.665Z","dependency_job_id":"04af973a-b58b-4a17-a53f-e349f0d6752b","html_url":"https://github.com/arraypress/wp-referrer-utils","commit_stats":null,"previous_names":["arraypress/wp-referrer-utils"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/arraypress/wp-referrer-utils","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/arraypress%2Fwp-referrer-utils","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/arraypress%2Fwp-referrer-utils/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/arraypress%2Fwp-referrer-utils/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/arraypress%2Fwp-referrer-utils/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/arraypress","download_url":"https://codeload.github.com/arraypress/wp-referrer-utils/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/arraypress%2Fwp-referrer-utils/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":281092778,"owners_count":26442440,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-10-26T02:00:06.575Z","response_time":61,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2025-09-23T00:13:01.623Z","updated_at":"2025-10-26T10:43:01.614Z","avatar_url":"https://github.com/arraypress.png","language":"PHP","readme":"# WordPress Referrer Utils - HTTP Referrer Detection \u0026 Analysis\n\nA lightweight WordPress library for detecting and analyzing HTTP referrers. Perfect for analytics, security, and understanding your traffic sources without external dependencies.\n\n## Features\n\n* 🎯 **Clean API**: WordPress-style snake_case methods with consistent interfaces\n* 🔍 **Traffic Analysis**: Identify search engines, social media, and campaign sources\n* 🔒 **Security Ready**: Validate referrers for CSRF protection and security checks\n* 📊 **UTM Support**: Extract campaign parameters for marketing analysis\n* 🔗 **Domain Operations**: Check internal vs external referrers\n* 🌐 **Search Engine Detection**: Identify 10+ search engines and extract search terms\n* 📱 **Social Media Detection**: Recognize 13+ social platforms\n* 🛡️ **WordPress Native**: Uses WordPress sanitization and validation\n\n## Requirements\n\n* PHP 7.4 or later\n* WordPress 5.0 or later\n\n## Installation\n\n```bash\ncomposer require arraypress/wp-referrer-utils\n```\n\n## Basic Usage\n\n### Get Referrer Information\n\n```php\nuse ArrayPress\\ReferrerUtils\\Referrer;\n\n// Get current referrer\n$referrer = Referrer::get();\n// Returns: \"https://google.com/search?q=wordpress\" or null\n\n// Check if valid URL\nif ( Referrer::is_valid( $referrer ) ) {\n\t// Valid referrer URL\n}\n\n// Get domain from referrer\n$domain = Referrer::get_domain();\n// Returns: \"google.com\"\n```\n\n### Traffic Source Analysis\n\n```php\n// Get traffic source type\n$source = Referrer::get_traffic_source();\n// Returns: 'search', 'social', 'direct', 'referral', 'campaign', or 'unknown'\n\n// Check specific source types\nif ( Referrer::is_search_engine() ) {\n\t// Visitor came from search engine\n}\n\nif ( Referrer::is_social() ) {\n\t// Visitor came from social media\n}\n\nif ( Referrer::is_external() ) {\n\t// Visitor came from external site\n}\n```\n\n### Search Engine Detection\n\n```php\n// Get search engine name\n$engine = Referrer::get_search_engine();\n// Returns: \"google\", \"bing\", \"yahoo\", \"duckduckgo\", etc.\n\n// Get search terms\n$terms = Referrer::get_search_terms();\n// Returns: \"wordpress plugins\" or null\n```\n\n### Social Media Detection\n\n```php\n// Get social platform\n$platform = Referrer::get_social_platform();\n// Returns: \"facebook\", \"twitter\", \"instagram\", \"linkedin\", etc.\n```\n\n### Campaign Tracking\n\n```php\n// Get UTM parameters\n$utm = Referrer::get_utm_parameters();\n/*\nReturns:\n[\n    'source' =\u003e 'newsletter',\n    'medium' =\u003e 'email', \n    'campaign' =\u003e 'summer-sale',\n    'term' =\u003e 'discount',\n    'content' =\u003e 'header-link'\n]\n*/\n```\n\n### Comprehensive Analysis\n\n```php\n// Get all referrer information at once\n$info = Referrer::get_referrer_info();\n/*\nReturns:\n[\n    'url' =\u003e 'https://google.com/search?q=wordpress',\n    'is_valid' =\u003e true,\n    'domain' =\u003e 'google.com',\n    'root_domain' =\u003e 'google.com',\n    'is_external' =\u003e true,\n    'search_engine' =\u003e 'google',\n    'search_terms' =\u003e 'wordpress',\n    'social_platform' =\u003e null,\n    'utm_parameters' =\u003e [],\n    'traffic_source' =\u003e 'search'\n]\n*/\n```\n\n## Common Use Cases\n\n### Analytics Tracking\n\n```php\nfunction track_visitor_sources() {\n\t$info = Referrer::get_referrer_info();\n\n\t// Store analytics data\n\t$analytics = [\n\t\t'traffic_source'  =\u003e $info['traffic_source'],\n\t\t'search_engine'   =\u003e $info['search_engine'],\n\t\t'search_terms'    =\u003e $info['search_terms'],\n\t\t'social_platform' =\u003e $info['social_platform'],\n\t\t'utm_source'      =\u003e $info['utm_parameters']['source'],\n\t\t'timestamp'       =\u003e current_time( 'mysql' )\n\t];\n\n\tupdate_option( 'traffic_analytics', $analytics );\n}\nadd_action( 'wp_head', 'track_visitor_sources' );\n```\n\n### CSRF Protection\n\n```php\nfunction check_form_referrer() {\n\tif ( ! Referrer::is_internal() ) {\n\t\twp_die( 'Invalid form submission - referrer check failed.' );\n\t}\n}\n\n// Use in form processing\nif ( $_POST['submit'] ) {\n\tcheck_form_referrer();\n\t// Process form...\n}\n```\n\n### Content Personalization\n\n```php\nfunction personalize_content_by_source() {\n\t$source = Referrer::get_traffic_source();\n\n\tswitch ( $source ) {\n\t\tcase 'search':\n\t\t\techo '\u003cdiv class=\"welcome-search\"\u003eWelcome from search!\u003c/div\u003e';\n\t\t\tbreak;\n\t\tcase 'social':\n\t\t\t$platform = Referrer::get_social_platform();\n\t\t\techo \"\u003cdiv class='welcome-social'\u003eThanks for visiting from {$platform}!\u003c/div\u003e\";\n\t\t\tbreak;\n\t\tcase 'campaign':\n\t\t\t$utm = Referrer::get_utm_parameters();\n\t\t\techo \"\u003cdiv class='welcome-campaign'\u003eWelcome {$utm['campaign']} visitor!\u003c/div\u003e\";\n\t\t\tbreak;\n\t}\n}\nadd_action( 'wp_head', 'personalize_content_by_source' );\n```\n\n## Supported Platforms\n\n### Search Engines (17+)\n**Traditional Search Engines:**\n- **Google** - All international domains (google.com, google.co.uk, etc.)\n- **Bing** - Microsoft's search engine\n- **Yahoo** - Yahoo Search with international variants\n- **DuckDuckGo** - Privacy-focused search\n- **Baidu** - Chinese search engine\n- **Yandex** - Russian search engine\n- **Ask** - Ask.com search\n- **AOL** - AOL Search\n- **Ecosia** - Environmental search engine\n- **Startpage** - Privacy search engine\n\n**AI Search Engines (2024-2025):**\n- **Perplexity** - AI-powered answer engine with citations\n- **You.com** - AI search with personalized results\n- **Phind** - AI search engine for developers\n- **Kagi** - Premium ad-free search with AI features\n- **SearchGPT** - OpenAI's ChatGPT Search\n- **Andi** - Conversational AI search assistant\n- **DeepSeek** - AI-powered search and chat\n\n### Social Media Platforms (13+)\n- **Facebook** - Including mobile variants and short links (fb.me, m.me)\n- **Twitter/X** - Including t.co short links and x.com rebrand\n- **Instagram** - Meta's photo platform with ig.me short links\n- **LinkedIn** - Professional networking with lnkd.in short links\n- **Pinterest** - Visual discovery with pin.it short links\n- **Reddit** - Social news aggregation with redd.it short links\n- **YouTube** - Video platform and youtu.be short links\n- **TikTok** - Short video platform with vm.tiktok.com\n- **Snapchat** - Multimedia messaging\n- **Discord** - Gaming and community chat with discord.gg\n- **Telegram** - Messaging platform with t.me short links\n- **WhatsApp** - Messaging app with wa.me short links\n- **Mastodon** - Decentralized social network\n- **Threads** - Meta's Twitter alternative\n\n### Campaign Parameters\n- **UTM Parameters** - utm_source, utm_medium, utm_campaign, utm_term, utm_content\n- **Search Parameters** - q, query, p, wd, text (for search term extraction)\n\n## Method Reference\n\n### Core Methods\n- `get()` - Get current HTTP referrer\n- `is_valid( ?string $referrer )` - Check if referrer is valid URL\n- `get_domain( ?string $referrer )` - Get domain from referrer\n- `get_root_domain( ?string $referrer )` - Get root domain without subdomains\n\n### Domain Operations\n- `is_external( ?string $referrer, ?string $current_site )` - Check if external referrer\n- `is_internal( ?string $referrer, ?string $current_site )` - Check if internal referrer\n\n### Search Engine Detection\n- `get_search_engine( ?string $referrer )` - Get search engine name\n- `get_search_terms( ?string $referrer )` - Get search terms\n- `is_search_engine( ?string $referrer )` - Check if from search engine\n\n### Social Media Detection\n- `get_social_platform( ?string $referrer )` - Get social platform name\n- `is_social( ?string $referrer )` - Check if from social media\n\n### Campaign Tracking\n- `get_utm_parameters( ?string $referrer )` - Get UTM parameters array\n- `get_campaign_source( ?string $referrer )` - Get campaign source\n\n### Analysis\n- `get_traffic_source( ?string $referrer )` - Get traffic source type\n- `get_referrer_info( ?string $referrer )` - Get comprehensive referrer information\n\n## WordPress Integration\n\n- **Sanitized Input**: All referrer data is sanitized using `wp_strip_all_tags()` and `wp_unslash()`\n- **Enhanced Security**: UTM parameters and search terms use `sanitize_text_field()` for additional protection\n- **WordPress Native**: Uses `get_option('siteurl')` for site URL detection\n- **Performance Optimized**: Efficient domain lookups with comprehensive coverage\n- **Standards Compliant**: Follows WordPress coding standards and best practices\n\n## Privacy Considerations\n\nThis library analyzes referrer headers that are automatically sent by browsers. It:\n- **Does not store personal data** - only analyzes traffic patterns\n- **Respects user privacy** - works with publicly available referrer information\n- **GDPR Compliant** - when used for analytics, follows standard referrer analysis practices\n\n## Requirements\n\n- PHP 7.4+\n- WordPress 5.0+\n\n## Testing\n\nThe library has been thoroughly tested with:\n- ✅ **100% test coverage** for core functionality\n- ✅ **Real-world referrer patterns** from major platforms\n- ✅ **Edge case handling** for malformed URLs and invalid input\n- ✅ **Performance validation** with hundreds of URLs\n- ✅ **WordPress integration** with proper sanitization\n- ✅ **Modern AI search engines** and social media short links\n\n## Contributing\n\nContributions are welcome! Please feel free to submit a Pull Request.\n\n## License\n\nThis project is licensed under the GPL-2.0-or-later License.\n\n## Support\n\n- [Documentation](https://github.com/arraypress/wp-referrer-utils)\n- [Issue Tracker](https://github.com/arraypress/wp-referrer-utils/issues)","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Farraypress%2Fwp-referrer-utils","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Farraypress%2Fwp-referrer-utils","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Farraypress%2Fwp-referrer-utils/lists"}