|
1 | | -raygun4cfml |
| 1 | +Raygun4CFML |
2 | 2 | =========== |
3 | 3 |
|
4 | | -Raygun Crash Reporting client for CFML. |
| 4 | +Raygun4CFML is a client library for integrating Raygun's Crash Reporting service with your CFML applications. It enables you to send error reports and crash data to Raygun for tracking and analysis. |
5 | 5 |
|
6 | | -Supported: |
| 6 | +Supported Platforms: |
7 | 7 |
|
8 | | -Adobe CF 2018+ |
9 | | -Lucee 5+ |
| 8 | +- Adobe ColdFusion 2021+ |
| 9 | +- Lucee 5.3+ |
| 10 | +- Boxlang 1+ |
10 | 11 |
|
11 | | -Current Version: 1.7.0 (November 14 2024) |
| 12 | +Current Version: 2.0.0 |
12 | 13 |
|
13 | | -Dependencies: |
| 14 | +## Active development |
14 | 15 |
|
15 | | -- Testbox (for running unit and BDD tests only) |
| 16 | +2.0.0 is a complete rewrite of the project and is ready-to-use for the 3 major CFML engines and their crash reports. |
16 | 17 |
|
17 | | -## Library organisation |
| 18 | +Please be aware that no testing and work has *yet* gone into framework-specific crash reports, e.g. a deeper integration with Coldbox HVMC, Fusebox, CF on Wheels etc. This will be added over time in future releases. |
18 | 19 |
|
19 | | -`/src` contains the source code. The package structure is `nz.co.ventego-creative.co.nz.raygun4cfml` but the library's components themselves are independent of the package path. Therefore you can use the library in multiple ways: |
| 20 | +## Dependencies |
20 | 21 |
|
21 | | -- Put the content of `/src` into your webroot and instantiate `RaygunClient` through something like the following: |
| 22 | +- Testbox (used as a development dependency for local and CI testing) |
22 | 23 |
|
23 | | - ``` |
24 | | - raygun = createObject("component","nz.co.ventego-creative.raygun4cfml.RaygunClient").init( |
25 | | - apiKey = "YOURAPIKEYHERE" |
26 | | - ); |
27 | | - ``` |
28 | | -- Put the contents of `/src` into any other place of your choice and create a mapping to `/nz` in your server administrator or through code and then use the instantiation code as above. |
| 24 | +## Installation and Setup |
29 | 25 |
|
30 | | -- Put the contents of the `raygun4cfml` directory into a place of your choice where your CFML has some sort of a mapping pointing towards and and just instantiate `RaygunClient` like this: |
31 | | - |
32 | | - ``` |
33 | | - raygun = createObject("component","RaygunClient").init( |
34 | | - apiKey = "YOURAPIKEYHERE" |
35 | | - ); |
36 | | - ``` |
37 | | - |
38 | | -`/samples` contains a set of files that show how the library can be used in your code through a global error handler as well as a contributed example for ColdBox 3.6 |
| 26 | +### Using CommandBox (Preferred Method) |
39 | 27 |
|
40 | | -`/tests` contains manual tests and more samples as well as a structure (but no tests at this stage) for Testbox unit and BDD tests. |
| 28 | +1. **Install via CommandBox:** |
41 | 29 |
|
42 | | -## Getting and Using raygun4cfml |
| 30 | + To install the latest version from the master repository, use: |
| 31 | + ``` |
| 32 | + box install raygun4cfml |
| 33 | + ``` |
43 | 34 |
|
44 | | -### Option 1 (preferred): |
| 35 | + To install a specific release or tag, use: |
| 36 | + ``` |
| 37 | + box install git://github.com/MindscapeHQ/raygun4cfml.git#{tagname} |
| 38 | + ``` |
45 | 39 |
|
46 | | -Use Commandbox and Forgebox to get the library and then follow the ideas outlined in 'Library organisation' for further setup. |
| 40 | + Alternatively, you can use: |
| 41 | + ``` |
| 42 | + box install MindscapeHQ/raygun4cfml#{tagname} |
| 43 | + ``` |
47 | 44 |
|
48 | | -To get the latest from the master repository |
| 45 | +2. **Setup:** |
49 | 46 |
|
50 | | -``` |
51 | | -box install raygun4cfml |
52 | | -``` |
| 47 | + After installation, follow the setup instructions in the 'Library Usage' section below. |
53 | 48 |
|
54 | | -To install a specific release or tag: |
| 49 | +### Manual Installation |
55 | 50 |
|
56 | | -``` |
57 | | -box install git://github.com/MindscapeHQ/raygun4cfml.git#{tagname} |
58 | | -``` |
| 51 | +1. **Clone or Download:** |
59 | 52 |
|
60 | | -Example tag names are `1.1.0`, `1.0.2.0`, `1.0.1.0` etc. Please check the list of tags on Github. Be aware that if you install any tag from before I introduced support for Commandbox and Forgebox there won't be a `box.json` file and therefore Commandbox will give you a warning as well as there won't be any dependency management for such an installation of the library. |
61 | | - |
62 | | -Shortcut for the above: |
63 | | - |
64 | | -``` |
65 | | -box install MindscapeHQ/raygun4cfml#{tagname} |
66 | | -``` |
| 53 | + - Fork and clone the repository to your local system, or download a zip file of the current content or a specific release/tag. |
67 | 54 |
|
68 | | -To get the latest from my development repository (be warned, this might contain all sorts of untested code): |
69 | | - |
70 | | -``` |
71 | | -box install TheRealAgentK/raygun4cfml |
72 | | -``` |
| 55 | +2. **Move Files:** |
73 | 56 |
|
74 | | -### Option 2: |
| 57 | + - Move the `src` and/or `tests` directories to locations suitable for your system. |
75 | 58 |
|
76 | | -Fork and clone the repo to your local system. Move the src/test directories into places of your choice and suitable for your system and follow the ideas outlined in 'Library organisation'. |
| 59 | +3. **Dependencies:** |
77 | 60 |
|
78 | | -### Option 3: |
| 61 | + - Note that manual installation will not automatically resolve dependencies. |
79 | 62 |
|
80 | | -Download a zip file containing the current content of the repo or a release/tag of your choice. Unzip the resulting file. Move the src/test directories into places of your choice and suitable for your system and follow the ideas outlined in 'Library organisation'. |
| 63 | +## Library Usage |
81 | 64 |
|
82 | | -#### Notes: |
| 65 | +### Initializing RaygunClient |
83 | 66 |
|
84 | | -(1) Options 2 and 3 will not fulfill any necessary dependencies, you're on your own. |
| 67 | +The `RaygunClient` is the primary component for sending error reports. You can initialize it in several ways depending on your setup: |
85 | 68 |
|
86 | | -## Version History |
87 | | -
|
88 | | -See CHANGELOG.md for further information. |
89 | | -
|
90 | | -## General Notes |
| 69 | +- **Webroot Setup:** |
91 | 70 |
|
92 | | -(1) All releases onwards from 0.5.0.0 will break your code if you've used 0.4 and older before and have used `customRequestData`. |
| 71 | + Place the contents of `/src` in your webroot and initialize the `RaygunClient` as follows: |
| 72 | + ```cfml |
| 73 | + raygun = createObject("component", "com.raygun.RaygunClient").init( |
| 74 | + apiKey = "YOURAPIKEYHERE" |
| 75 | + ); |
| 76 | + ``` |
93 | 77 |
|
94 | | -(2) If you are using the ACF Administrator setting: "Prefix serialized JSON with..." with anything else but the default prefix of `//`, the library will not work. |
| 78 | +- **Custom Mapping:** |
95 | 79 |
|
96 | | -(3) Version 1.1.0 and newer will not work on Adobe ColdFusion 8 and most likely not on Railo 3 (the latter not tested). |
| 80 | + Place the contents of `/src` in a directory of your choice and create a mapping to `/com` in your server administrator or through code. Them, initialise as suitable for the mapping. |
97 | 81 |
|
98 | | -(4) Version 1.7.0 and newer will most likely not work with Adobe ColdFUsion 2016 and Railo/Lucee 4.x. |
99 | 82 |
|
100 | | -(5) On newer Java versions (>11), there is no default access to Java Memory Management unless you add the following argument to your JVM configuration: `--add-opens java.management/sun.management=ALL-UNNAMED` |
| 83 | +### Using the Library |
101 | 84 |
|
102 | | -## How to contribute |
| 85 | +- **Error Reporting:** |
103 | 86 |
|
104 | | -Note: Please be aware that raygun4cfml is not an official Raygun library and not maintained by Raygun stuff. See [LICENSE](LICENSE) for more details. |
| 87 | + Once initialized, use the `RaygunClient` to send error reports with the `.send()` function. Refer to the `/samples` directory for examples. |
105 | 88 |
|
106 | | -The main repository of this project is https://github.com/MindscapeHQ/raygun4cfml. Please fork from there, create a local develop or feature branch and merge changes back to your local master branch to submit a pull request. Even better, get in touch with me on Twitter (@AgentK) or here on Github before you undertake any work so that it can be coordinated with what I'm doing. |
107 | | -
|
108 | | -Most of the active development happens in my own fork: https://github.com/TheRealAgentK/raygun4cfml - feel free to peek around in there. |
| 89 | +- **Testing:** |
109 | 90 |
|
| 91 | + The `/tests` directory contains structures for Testbox unit and integration tests. Use these to validate your integration. |
110 | 92 |
|
| 93 | +## Version History |
111 | 94 |
|
| 95 | +For detailed version history, refer to the `CHANGELOG.md` file. |
112 | 96 |
|
| 97 | +## Contribution Guidelines |
113 | 98 |
|
| 99 | +Raygun4CFML is not an official Raygun library and is not maintained by Raygun staff. |
114 | 100 |
|
| 101 | +Contributions are welcome. |
115 | 102 |
|
| 103 | +Please fork the main repository at https://github.com/MindscapeHQ/raygun4cfml, create a feature branch, and submit a pull request. Coordination via X (@AgentK) or GitHub (https://github.com/TheRealAgentK/) is encouraged before starting any work. |
116 | 104 |
|
| 105 | +For more active development, visit my development fork at https://github.com/TheRealAgentK/raygun4cfml. |
0 commit comments