forked from colin/simple-glitchtip
Update README.md
This commit is contained in:
parent
12e14401d2
commit
5938c54af4
102
README.md
102
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.
|
||||
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.
|
||||
Loading…
Reference in New Issue