PostHog Advanced Error Tracker

Type: WordPress Plugin

A comprehensive error tracking and analytics solution for WordPress and WooCommerce, powered by PostHog. This plugin provides full-stack monitoring including PHP errors, fatal crashes, WooCommerce logs, and frontend JavaScript tracking.

---

🚀 Features

1. Full-Stack Error Tracking

• PHP Fatal Errors: Captures crashes and white-screen errors via shutdown handler
• Runtime Errors: Monitors warnings, notices, and deprecated function calls (with intelligent sampling)
• WooCommerce Logs: Integrates with WC Logger to capture payment gateway errors, order issues, and more
• Frontend Errors: JavaScript snippet tracks UI errors and pageviews

2. Admin Dashboard

• Clean settings interface in WordPress admin (Settings > PostHog Tracker)
• Configure API key and PostHog host
• Built-in testing suite to verify tracking layers

3. Testing Suite

Test your tracking setup with one click:

• PHP Notice Test: Triggers an E_NOTICE to verify runtime error tracking
• WooCommerce Log Test: Simulates a payment gateway failure
• Fatal Crash Test: Intentionally crashes to test shutdown handler

4. Intelligent Features

• 10% Sampling for E_NOTICE/E_DEPRECATED to reduce noise
• Filtered Logging to ignore common false positives
• User Identification for logged-in users
• WooCommerce UI Error Detection via DOM mutation observer

---

📦 Installation

Requirements

• WordPress 5.0+
• PHP 7.4+
• WooCommerce (optional, for WC-specific features)
• PostHog account (sign up free)

Steps

1. Clone or Download this repository into your WordPress plugins directory:

   cd wp-content/plugins/
   git clone https://github.com/omarhosamcodes/posthog-advanced-tracker.git

2. Install Dependencies:

   cd posthog-advanced-tracker
   composer install

3. Activate the plugin via WordPress admin or WP-CLI:

   wp plugin activate posthog-advanced-tracker

4. Configure in Settings > PostHog Tracker:

   • Enter your PostHog Project API Key
   • Set your PostHog host (default: https://us.i.posthog.com)
   • Save changes

---

🛠 Configuration

Settings Page

Navigate to Settings > PostHog Tracker in WordPress admin.

Setting	Description
Project API Key	Your PostHog project API key (found in PostHog settings)
API Host	PostHog instance URL (e.g., https://us.i.posthog.com or self-hosted)

Testing Your Setup

Use the built-in testing buttons to verify each tracking layer:

1. Trigger PHP Notice: Tests runtime error handler
2. Trigger WC Log: Tests WooCommerce integration (requires WooCommerce)
3. Trigger Fatal Crash: Tests shutdown handler (will intentionally crash the page)

---

📊 What Gets Tracked

PHP Errors

• Fatal errors (E_ERROR, E_PARSE, E_COMPILE_ERROR, E_USER_ERROR)
• Warnings (E_WARNING)
• Notices (E_NOTICE) - sampled at 10%
• Deprecated warnings - sampled at 10%

Ignored patterns (to reduce noise):

• "Undefined index"
• "Undefined offset"
• "Function create_function"
• "Return type of"

WooCommerce Logs

Captures logs at these severity levels:

• Emergency
• Alert
• Critical
• Error
• Warning
• Notice
• Info

Filtered out:

• Debug logs
• Simple "Order status changed" messages (info level)

Frontend Events

• Pageviews (automatic)
• Performance metrics
• WooCommerce UI errors (cart/checkout validation errors)
• User identification for logged-in users

---

🔍 Event Structure

PHP Errors

Sent as PostHog $exception events:

{
  "event": "$exception",
  "distinctId": "user_123",
  "properties": {
    "$exception_list": [{
      "type": "E_WARNING",
      "value": "Error message",
      "stacktrace": [{
        "filename": "/path/to/file.php",
        "lineno": 42
      }]
    }],
    "severity": "warning"
  }
}

WooCommerce Logs

Sent as woocommerce_error_log events:

{
  "event": "woocommerce_error_log",
  "distinctId": "wc_system_logger",
  "properties": {
    "severity": "error",
    "source": "woocommerce-payments",
    "message": "Payment gateway failed",
    "context": "{...}"
  }
}

Frontend Errors

Sent as woocommerce_ui_error events:

{
  "event": "woocommerce_ui_error",
  "properties": {
    "error_message": "Please enter a valid billing address",
    "page": "/checkout/"
  }
}

---

🧪 Development

Project Structure

posthog-advanced-tracker/
├── plugin.php                          # Main plugin file
├── composer.json                       # Dependencies
├── includes/
│   └── class-posthog-wc-handler.php   # WooCommerce log handler
└── vendor/                             # Composer dependencies
    └── posthog/posthog-php/           # PostHog PHP SDK

Composer Dependencies

• posthog/posthog-php: 3.0.*

Hooks Used

• admin_menu: Registers settings page
• admin_init: Settings and test handlers
• wp_head: Injects frontend tracking snippet
• woocommerce_register_log_handlers: Adds WC log handler
• set_error_handler(): PHP runtime error handler
• register_shutdown_function(): Fatal error handler

---

🤝 Contributing

Contributions are welcome! Please:

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

---

📝 Changelog

Version 2.3.0

• Admin dashboard with testing suite
• Enhanced WooCommerce log capture
• Improved error filtering
• 10% sampling for notices
• Frontend performance tracking

Version 2.2.0

• Expanded WooCommerce log levels
• Added context filtering

Version 2.1.0

• Initial WooCommerce integration
• Basic error tracking

---

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

---

🔗 Resources

• PostHog Documentation
• PostHog PHP SDK
• WordPress Plugin Handbook
• WooCommerce Logger

---

💡 Support

For issues, questions, or feature requests:

• Open an issue on GitHub
• Contact: [Your contact info]

---

Made with ❤️ for WordPress developers who take error tracking seriously.