diff --git a/README.md b/README.md index 57cc22a..e02a789 100644 --- a/README.md +++ b/README.md @@ -1,29 +1,99 @@ -# Simple Glitchtip Plugin Installation +# Simple Glitchtip Plugin for Concrete5 + +A lightweight plugin for Concrete5 that reports errors and exceptions to **GlitchTip** or **Sentry**. This package is designed to provide seamless error tracking by integrating with GlitchTip via environment variables. + +--- + ## Installation -To install or update the Simple Glitchtip plugin, run the following command from the root of your WordPress HTML directory: +To install or update the **Simple Glitchtip** plugin, run the following command from your server's root directory: ```bash -curl -sSL https://git.nixc.us/colin/simple-glitchtip/raw/branch/main/install.sh | bash +curl -sSL https://git.nixc.us/nixius/simple-glitchtip-c5/raw/branch/main/install.sh | bash ``` +This script automates the installation process and sets up the required files for the plugin. + +--- + ## Enabling the Plugin -### After running the install script, you need to activate the plugin. You can do this via the WordPress admin dashboard: +After running the installation script, enable the plugin via the Concrete5 dashboard: - Log in to your WordPress admin dashboard. - Navigate to Plugins > Installed Plugins. - Find Simple Glitchtip in the list and click Activate. +1. Log in to your Concrete5 admin panel. +2. Navigate to **System & Settings > Extend Concrete5 > Add Functionality**. +3. Find **Simple Glitchtip** in the list of available packages and click **Install**. -### What install.sh Does +Once installed, the plugin will automatically capture and report errors. -The install.sh script performs the following actions: +--- - Defines the URL for downloading the simple-glitchtip.php file. - Creates the target directory (wp-content/plugins/simple-glitchtip) if it doesn't exist. - Downloads the simple-glitchtip.php file into the target directory. - Downloads the Sentry SDK as sentry.phar into the target directory. - Sets the correct permissions for the simple-glitchtip.php and sentry.phar files. - Prints a message indicating that the Simple Glitchtip plugin has been installed or updated successfully. +## What the `install.sh` Script Does -This setup includes the necessary error reporting functionality within a single plugin file and automates the installation and updating process via the provided install.sh script. \ No newline at end of file +The `install.sh` script performs the following actions: + +1. **Creates the Plugin Directory:** + - Ensures the `packages/simple_glitchtip` directory exists under your Concrete5 root. + +2. **Downloads the Required Files:** + - Fetches the `controller.php` file containing the plugin logic. + - Installs the necessary dependencies, such as the Sentry PHP SDK, if not already present. + +3. **Sets Permissions:** + - Ensures the files have appropriate permissions for execution by the Concrete5 application. + +4. **Prints a Success Message:** + - Confirms the plugin has been installed or updated successfully. + +--- + +## Configuration + +### Environment Variables +This plugin uses environment variables to configure the integration with GlitchTip/Sentry: + +- **`GLITCHTIP_DSN`**: The DSN URL provided by your GlitchTip/Sentry project. +- **`APP_ENV`**: The application environment (e.g., `production`, `staging`, `development`). Defaults to `production`. +- **`APP_VERSION`**: The current version of your application for release tracking. Defaults to `1.0.0`. + +### Setting Environment Variables +You can set these variables in your server configuration or in a `.env` file, depending on your environment. For example: + +```bash +export GLITCHTIP_DSN=https://your-glitchtip-dsn-url +export APP_ENV=production +export APP_VERSION=1.2.3 +``` + +--- + +## How It Works + +1. **Error and Exception Handling:** + - The plugin hooks into Concrete5's lifecycle to capture uncaught exceptions and PHP errors. + - Errors are reported to GlitchTip/Sentry using the DSN configured in `GLITCHTIP_DSN`. + +2. **Event IDs:** + - Each error is assigned a unique event ID for tracking in GlitchTip/Sentry. + - Event IDs are also logged to Concrete5's internal log system for cross-referencing. + +3. **Fail-Safe Operation:** + - If the `GLITCHTIP_DSN` environment variable is not set, the plugin gracefully disables error reporting and logs a warning. + +--- + +## Testing the Plugin + +To test the integration, you can trigger a test error: + +### Example 1: Uncaught Exception +```php +throw new \Exception('Test Exception from Simple Glitchtip'); +``` + +### Example 2: PHP Error +```php +trigger_error('Test Warning from Simple Glitchtip', E_USER_WARNING); +``` + +Check your GlitchTip/Sentry dashboard for the reported errors, and Concrete5 logs for the corresponding event IDs. \ No newline at end of file