Skip to content

Commit c2d03b4

Browse files
ryanmitchellryanmitchell
authored
Merge pull request #2 from thoughtco/feature/overhaul
Overhaul for Statamic 6
2 parents 4328a05 + c9cfbd8 commit c2d03b4

98 files changed

Lines changed: 4444 additions & 1525 deletions

File tree

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

‎.github/workflows/release.yaml‎

Lines changed: 56 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,56 @@
1+
name: Bundle Release Assets
2+
3+
on:
4+
workflow_dispatch:
5+
release:
6+
types:
7+
- released
8+
- prereleased
9+
10+
jobs:
11+
build:
12+
runs-on: ubuntu-latest
13+
steps:
14+
- name: Checkout code
15+
uses: actions/checkout@v4
16+
17+
- name: Setup PHP
18+
uses: shivammathur/setup-php@v2
19+
with:
20+
php-version: 8.4
21+
tools: composer:v2
22+
23+
- name: Use Node.js 23.3.0
24+
uses: actions/setup-node@v4
25+
with:
26+
node-version: 23.3.0
27+
28+
- name: Install composer dependencies
29+
run: composer install --no-interaction --prefer-dist --optimize-autoloader
30+
31+
- name: Install node dependencies
32+
run: npm ci
33+
34+
- name: Build release assets
35+
run: npm run build
36+
37+
- name: Create zip
38+
run: tar -czvf dist.tar.gz dist
39+
40+
- name: Get release
41+
id: get_release
42+
uses: cardinalby/git-get-release-action@v1
43+
env:
44+
GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
45+
with:
46+
latest: true
47+
48+
- name: Upload dist zip to release
49+
uses: actions/upload-release-asset@v1.0.1
50+
env:
51+
GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
52+
with:
53+
upload_url: ${{ steps.get_release.outputs.upload_url }}
54+
asset_path: ./dist.tar.gz
55+
asset_name: dist.tar.gz
56+
asset_content_type: application/tar+gz

‎.github/workflows/tests.yml‎

Lines changed: 38 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,38 @@
1+
name: Test Suite
2+
3+
on:
4+
push:
5+
pull_request:
6+
7+
jobs:
8+
php_tests:
9+
if: "!contains(github.event.head_commit.message, 'changelog')"
10+
11+
runs-on: ${{ matrix.os }}
12+
13+
strategy:
14+
matrix:
15+
php: [8.3, 8.4]
16+
laravel: [12.*]
17+
statamic: [^6.0]
18+
os: [ubuntu-latest]
19+
20+
name: ${{ matrix.php }} - ${{ matrix.statamic }} - ${{ matrix.laravel }}
21+
22+
steps:
23+
- name: Checkout code
24+
uses: actions/checkout@v1
25+
26+
- name: Setup PHP
27+
uses: shivammathur/setup-php@v2
28+
with:
29+
php-version: ${{ matrix.php }}
30+
extensions: dom, curl, libxml, mbstring, zip, pcntl, pdo, sqlite, pdo_sqlite, bcmath, soap, intl, gd, exif, iconv, imagick
31+
32+
- name: Install dependencies
33+
run: |
34+
composer require "laravel/framework:${{ matrix.laravel }}" "statamic/cms:${{ matrix.statamic }}" --no-interaction --no-update
35+
composer install --no-interaction
36+
37+
- name: Run Pest
38+
run: vendor/bin/pest

‎README.md‎

Lines changed: 111 additions & 18 deletions
Original file line numberDiff line numberDiff line change
@@ -1,19 +1,87 @@
11
# A/B Tester
22

3+
## Commercial addon
4+
5+
This addon is paid software. You may use it for free during development, but you must purchase a license from the Statamic Marketplace before deploying to production.
6+
37
## Installation
48

59
`composer require thoughtco/statamic-ab-tester`
610

11+
then run
12+
13+
`php artisan migrate`
14+
15+
## Custom database connection
16+
This addon uses your default database to store results, in a new table it creates called `ab_test_results`. If you want to specify a custom connection, use add the connection name to your .env:
17+
18+
`AB_TESTER_RESULTS_CONNECTION=your-connection`
19+
720
## Usage
821

22+
### Create a goal
23+
One installed the first step is to create a goal through the UI. Name it whatever you want (for example "Mailing List Signup" or "Add to Basket") and give it a unique handle.
24+
25+
Now you want to trigger that handle in your code - to do that simply call:
26+
`\Thoughtco\StatamicABTester\Facades\Goal::completed('your-goal-handle')`
27+
28+
If your goal is completed on a page, you may just want to use the antlers tag:
29+
30+
`{{ ab:goal:completed handle="your-goal-handle" }}`
31+
32+
Alongside the handle, we also log the time the goal was completed, the user's IP, and their ID if they are logged in.
33+
34+
You can also (optionally) record failures, if your test requires it:
35+
36+
`\Thoughtco\StatamicABTester\Facades\Goal::failed('your-goal-handle')`
37+
38+
`{{ ab:goal:failed handle="your-goal-handle" }}`
39+
40+
#### Javacript helper
41+
42+
If you need to trigger goals from Javascript, include the `{{ ab:js }}` in your layout, then call:
43+
44+
`abTester.hit('experiment-id', { custom: 'data' })` to register a hit on an experiment
45+
46+
`abTester.completed('goal-id', { custom: 'data' })` to register a goal success
47+
48+
`abTester.failed('goal-id', { custom: 'data' })` to register a goal failure
49+
50+
51+
### Create an experiment
52+
Next you need to make an experiment, which varies something on your site. To do this use the "Create A/B Experiment" action available on an entry.
53+
54+
This will open a window allowing you to choose what field(s) you want to vary and define their alternate values.
55+
56+
Finally, ensure you associate them with the goal you created in the first step.
57+
58+
59+
### Outputting experiments
60+
This add-on will automate the display of the variants, knowing when the item is augmented and switching it as appropriate.
61+
62+
If you are using full static caching, Statamic is never booted, so you will need to use `{{ nocache }}` alongside the tags this addon provides to run your experiments.
63+
64+
65+
### Static caching
66+
If you are using the `half` caching strategy, switch to using the provided `ab` driver - this extends half caching but allows ab experiments to continue working.
67+
68+
If you are using `full` static caching, you will need to wrap any experiments in `{{ nocache }}` tags and ensure you are using the tags to record hits, successes and failures.
69+
70+
71+
### Field selection
72+
By default all fields will be selectable to apply an A/B Test but you can control this using the `Allow this field to be A/B tested` config field that this add-on sets on each fieldtype.
73+
74+
If it makes sense for you to to default to fields not being included, you can set the `statamic-ab-tester.blueblueprint_fields_approach` to be 'opt-out'.
75+
76+
977
### Experiment types
1078
There are two types of experiments you can run:
1179

12-
#### Entry
13-
An Entry experiment lets you select an entry and display its content on the page. This can be selected from any collection and will be available as an `entry` variable inside the `ab` tag.
80+
#### Item
81+
An Item experiment lets you select an entry and modify its content from the base entry. These can be created using the `Create A/B Experiment` action on the entry view.
1482

1583
#### Manual
16-
A Manual experiment lets you determine what you want to do inside the experiment, e.g. show a different nav UI, show a different button style. You can use the autogenerated `variant:id` or use `variant:label` to determine what to show to the user.
84+
A Manual experiment lets you determine what you want to do inside the experiment, e.g. show a different nav UI, show a different button style. You can use the `variant:handle` to determine what to show to the user.
1785

1886
### Tags
1987
This package provides tags that you can use in your Statamic templates:
@@ -24,68 +92,93 @@ This tag sets an A/B test for the given handle. It will randomly choose a experi
2492
If you want your variant to persist over the session lifetime, set session="true"
2593

2694
```antlers
27-
{{ ab experiment="experiment_handle" session="true" }}
28-
{{ experiment }} {{ variant }}
95+
{{ ab experiment="experiment_id" session="true" }}
96+
{{ experiment:title}} {{ variant }}
2997
{{ /ab }}
3098
```
3199

32100
#### ab:success
33101
This tag marks an A/B test as successful.
34102

35103
```antlers
36-
{{ ab:success experiment="experiment_handle" variant="variant_handle" }}
104+
{{ ab:success experiment="experiment_id" variant="variant_handle" }}
37105
```
38106

39107
or if you've used session="true" on the ab tag:
40108

41109
```antlers
42-
{{ ab:success experiment="experiment_handle" from_session="true" }}
110+
{{ ab:success experiment="experiment_id" from_session="true" }}
43111
```
44112

45113
#### ab:failure
46114
This tag marks an A/B test as a failure.
47115

48116
```antlers
49-
{{ ab:failure experiment="experiment_handle" variant="variant_handle" }}
117+
{{ ab:failure experiment="experiment_id" variant="variant_handle" }}
50118
```
51119

52120
or if you've used session="true" on the ab tag:
53121

54122
```antlers
55-
{{ ab:failure experiment="experiment_handle" from_session="true" }}
123+
{{ ab:failure experiment="experiment_id" from_session="true" }}
56124
```
57125

58126

59-
### Facade
127+
### Experiment Facade
60128
This package provides a facade for interacting with experiments:
61-
`\Thoughtco\StatamicABTester\Experiment`
129+
`\Thoughtco\StatamicABTester\Facades\Experiment`
62130

63131
#### get an experiment
64-
`$experiment = \Thoughtco\StatamicABTester\Experiment::find('experiment_handle');`
132+
`$experiment = \Thoughtco\StatamicABTester\Facades\Experiment::find('experiment_handle');`
65133

66134
#### get all experiments
67-
`\Thoughtco\StatamicABTester\Experiment::all();`
135+
`\Thoughtco\StatamicABTester\Facades\Experiment::all();`
68136

69137
#### query experiments
70-
`\Thoughtco\StatamicABTester\Experiment::query()->where('handle', 'test')->get();`
138+
`\Thoughtco\StatamicABTester\Facades\Experiment::query()->where('title', 'test')->get();`
71139

72140

73141
### Experiment
74142
Once you have an experiment you can record hits, successes, failures and get results.
75143

76144
#### hit
77145
Mark an experiment as being viewed:
78-
`$experiment->recordHit($variantHandle);`
146+
`$experiment->recordHit($variantHandle,$customData = []);`
79147

80148
#### success
81149
Mark an experiment as being successful:
82-
`$experiment->recordSuccess($variantHandle);`
150+
`$experiment->recordSuccess($variantHandle, $goalId = null, $customData = []);`
83151

84152
#### failure
85153
Mark an experiment as being a failure:
86-
`$experiment->recordFailure($variantHandle);`
154+
`$experiment->recordFailure($variantHandle, $goalId = null, $customData = []);`
87155

88156
#### results
89157
Get the results of an experiment:
90-
`$experiment->results();`
158+
`$experiment->resultsQuery()->get();`
91159

160+
161+
### Goal Facade
162+
This package provides a facade for interacting with experiments:
163+
`\Thoughtco\StatamicABTester\Facades\Goal`
164+
165+
#### get a goal
166+
`$goal = \Thoughtco\StatamicABTester\Facades\Goal::find('goal_handle');`
167+
168+
#### get all goals
169+
`\Thoughtco\StatamicABTester\Facades\Goal::all();`
170+
171+
#### query goals
172+
`\Thoughtco\StatamicABTester\Facades\Goal::query()->where('title', 'test')->get();`
173+
174+
#### complete a goal
175+
Mark an goal as being completed:
176+
`\Thoughtco\StatamicABTester\Facades\Goal::completed($goalHandle, $customData = []);`
177+
178+
#### fail a goal
179+
Mark an goal as being failed:
180+
`\Thoughtco\StatamicABTester\Facades\Goal::failed($goalHandle, $customData = []);`
181+
182+
#### results
183+
Get the results of an experiment:
184+
`\Thoughtco\StatamicABTester\Facades\Goal::find('goal_handle')?->resultsQuery()->get();`

‎composer.json‎

Lines changed: 13 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -4,10 +4,14 @@
44
"description": "",
55
"license": "MIT",
66
"require": {
7-
"statamic/cms": "^5.0"
7+
"statamic/cms": "^6.0",
8+
"laravel/pint": "^1.25",
9+
"pixelfear/composer-dist-plugin": "^0.1.6"
810
},
911
"require-dev": {
10-
"laravel/pint": "^1.17"
12+
"laravel/pint": "^1.17",
13+
"orchestra/testbench": "^10.0",
14+
"pestphp/pest": "^4.0"
1115
},
1216
"autoload": {
1317
"psr-4": {
@@ -34,10 +38,15 @@
3438
}
3539
],
3640
"extra": {
41+
"download-dist": [
42+
{
43+
"url": "https://github.com/thoughtco/statamic-ab-tester/releases/download/{$version}/dist.tar.gz",
44+
"path": "dist"
45+
}
46+
],
3747
"statamic": {
3848
"name": "A/B Tester",
39-
"description": "Run A/B Tests in your Statamic install",
40-
"version": "0.1"
49+
"description": "Run A/B Tests in your Statamic install"
4150
},
4251
"laravel": {
4352
"providers": [
@@ -52,9 +61,5 @@
5261
"pixelfear/composer-dist-plugin": true,
5362
"pestphp/pest-plugin": true
5463
}
55-
},
56-
"require-dev": {
57-
"orchestra/testbench": "^7.0 || ^8.0",
58-
"pestphp/pest": "^2.35"
5964
}
6065
}

0 commit comments

Comments
 (0)