Skip to content

Commit 5bbd7ad

Browse files
AWqxKAWERbXoAWqxKAWERbXo
committed
Initial commit
0 parents  commit 5bbd7ad

107 files changed

Lines changed: 7074 additions & 0 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.

‎.DS_Store‎

6 KB
Binary file not shown.

‎.github/FUNDING.yml‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,3 @@
1+
github: alxndr-w
2+
ko_fi: alxndr-w
3+
custom: ['https://www.alexplus.de']

‎.github/copilot-instructions.md‎

Lines changed: 146 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,146 @@
1+
# Copilot Instructions for YForm Rapidmail
2+
3+
## Project Overview
4+
5+
This is a REDAXO 5 add-on that integrates the Rapidmail newsletter service with YForm. It provides:
6+
- Rapidmail PHP SDK integration
7+
- Email address synchronization with recipient lists
8+
- YForm action for newsletter signup
9+
10+
**Important**: This is NOT an official Rapidmail add-on, but a community-developed integration.
11+
12+
## Project Structure
13+
14+
```
15+
/
16+
├── .github/ # GitHub workflows and configuration
17+
├── assets/ # Frontend assets (CSS, JS, images)
18+
├── boot.php # Add-on bootstrap file
19+
├── lang/ # Language/translation files
20+
├── lib/ # PHP libraries
21+
│ ├── rapidmail/ # Rapidmail PHP SDK (third-party)
22+
│ └── yform/ # YForm integration
23+
│ └── action/ # YForm action classes
24+
├── pages/ # Backend page handlers
25+
├── package.yml # REDAXO package configuration
26+
└── README.md # Documentation (in German)
27+
```
28+
29+
## Technology Stack
30+
31+
- **Platform**: REDAXO 5 CMS (≥5.15)
32+
- **PHP**: 8.1+ (based on workflow configuration)
33+
- **Dependencies**:
34+
- YForm (≥4.2.1)
35+
- Rapidmail PHP SDK (bundled in `lib/rapidmail/`)
36+
- Guzzle HTTP client (via Rapidmail SDK)
37+
38+
## Coding Standards
39+
40+
- **PHP CS Fixer**: The project uses PHP CS Fixer for code style enforcement
41+
- Run via: `composer cs-fix` (see `.github/workflows/code-style.yml`)
42+
- Code style is automatically fixed on push/PR via GitHub Actions
43+
- PHP version: 8.1+ with extensions: gd, intl, pdo_mysql
44+
45+
## Key Components
46+
47+
### 1. YForm Action (`lib/yform/action/yform_rapidmail.php`)
48+
- Class: `rex_yform_action_yform_rapidmail`
49+
- Extends: `rex_yform_action_abstract`
50+
- Purpose: Handles newsletter signup form submissions
51+
- Key fields:
52+
- `list_id`: Rapidmail recipient list ID (required)
53+
- `email`: Email field name (required)
54+
- `optin`: DSGVO opt-in checkbox field (optional)
55+
- `fullname`: Full name field (optional)
56+
57+
### 2. API Configuration
58+
- Stored in REDAXO config system via `rex_config`
59+
- Keys: `api_user_hash`, `api_password_hash`
60+
- Set via backend: YForm > Rapidmail > Einstellungen
61+
62+
### 3. Rapidmail SDK
63+
- Location: `lib/rapidmail/`
64+
- Main class: `Rapidmail\ApiClient\Client`
65+
- Services: Recipients, Mailings, Stats, Jobs, etc.
66+
- Documentation: `lib/rapidmail/docs/`
67+
68+
## Development Guidelines
69+
70+
### When Working with YForm Actions:
71+
- Always check for validation errors before API calls: `count($this->params['warning_messages']) == 0`
72+
- Use `dump()` for error output (REDAXO convention)
73+
- Handle `ApiClientException` with proper HTTP status code checks (400, 401, 403, 406, 409, 415, 422)
74+
- Send activation emails via modifier: `['send_activationmail' => 'yes']`
75+
76+
### API Usage Pattern:
77+
```php
78+
use Rapidmail\ApiClient\Client;
79+
use rex_config;
80+
81+
$client = new Client(
82+
rex_config::get('yform_rapidmail', 'api_user_hash'),
83+
rex_config::get('yform_rapidmail', 'api_password_hash')
84+
);
85+
86+
$recipientsService = $client->recipients();
87+
```
88+
89+
### Form Field Definition Format:
90+
```
91+
action|yform_rapidmail|list_id|email_fieldname|opt:optin_fieldname|opt:fullname_fieldname
92+
```
93+
94+
## DSGVO/Privacy Compliance
95+
96+
- Newsletter opt-in must be DSGVO-compliant (German data protection law)
97+
- Use checkbox field for explicit consent
98+
- Activation emails are sent by default (`send_activationmail` = 'yes')
99+
- Only process subscriptions when opt-in is confirmed
100+
101+
## Testing
102+
103+
- No automated test suite currently exists
104+
- Manual testing via REDAXO backend required
105+
- Test API credentials in: YForm > Rapidmail > Einstellungen
106+
107+
## Documentation
108+
109+
- Main docs: `README.md` (German language)
110+
- API docs: `lib/rapidmail/docs/*.md`
111+
- Backend docs accessible at: YForm > Rapidmail > Docs page
112+
- Uses `rex_markdown` for rendering documentation
113+
114+
## Important Notes
115+
116+
- **Language**: Documentation and UI strings are in German
117+
- **No Composer**: Project doesn't use Composer at root level (Rapidmail SDK is bundled)
118+
- **REDAXO Conventions**: Use `rex_*` classes, `dump()` for debugging, `rex_config` for settings
119+
- **Backend Pages**: Defined in `package.yml` under `pages:` section
120+
- **Permissions**: Use `yform_rapidmail[]` permission system
121+
122+
## Common Tasks
123+
124+
### Adding New Features:
125+
1. Check if feature should be in YForm action or separate service
126+
2. Follow REDAXO naming conventions (`rex_yform_action_*`)
127+
3. Update `README.md` with examples (in German)
128+
4. Test in REDAXO backend environment
129+
130+
### Fixing API Issues:
131+
1. Check API credentials configuration
132+
2. Review error handling in action class
133+
3. Consult Rapidmail SDK docs in `lib/rapidmail/docs/`
134+
4. Test with different HTTP error codes
135+
136+
### Updating Documentation:
137+
1. Update `README.md` for user-facing changes
138+
2. Update backend page handlers if docs page needs changes
139+
3. Keep German language for consistency
140+
141+
## External Resources
142+
143+
- [Rapidmail API Documentation](https://developer.rapidmail.wiki/documentation.html)
144+
- [Rapidmail PHP SDK](https://github.com/rapidmail/rapidmail-apiv3-client-php)
145+
- [REDAXO Documentation](https://www.redaxo.org)
146+
- [YForm Documentation](https://github.com/yakamara/redaxo_yform)

‎.github/workflows/code-style.yml‎

Lines changed: 43 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,43 @@
1+
name: PHP-CS-Fixer
2+
3+
on:
4+
push:
5+
branches: [ master, main ]
6+
pull_request:
7+
branches: [ master, main ]
8+
9+
permissions:
10+
contents: read
11+
12+
jobs:
13+
code-style:
14+
15+
runs-on: ubuntu-latest
16+
permissions:
17+
contents: write # for Git to git apply
18+
19+
steps:
20+
- uses: actions/checkout@v3
21+
22+
- name: Setup PHP
23+
uses: shivammathur/setup-php@v2
24+
with:
25+
php-version: '8.1'
26+
extensions: gd, intl, pdo_mysql
27+
coverage: none # disable xdebug, pcov
28+
29+
# install dependencies from composer.json
30+
- name: Install test dependencies
31+
env:
32+
COMPOSER: composer.json
33+
run: composer install --prefer-dist --no-progress
34+
35+
# run php-cs-fixer, fix code styles
36+
- name: Run PHP CS Fixer
37+
run: composer cs-fix
38+
39+
# commit and push fixed files
40+
- uses: stefanzweifel/git-auto-commit-action@v4
41+
with:
42+
commit_message: Apply php-cs-fixer changes
43+
push_options: --force

‎.github/workflows/publish-to-redaxo-org.yml‎

Lines changed: 27 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,27 @@
1+
# Instructions: https://github.com/FriendsOfREDAXO/installer-action/
2+
3+
name: Publish to REDAXO.org
4+
on:
5+
release:
6+
types:
7+
- published
8+
9+
jobs:
10+
redaxo_publish:
11+
runs-on: ubuntu-latest
12+
steps:
13+
- uses: actions/checkout@v3
14+
- if: hashFiles('composer.json') != ''
15+
uses: shivammathur/setup-php@v2
16+
with:
17+
php-version: "8.2"
18+
- if: hashFiles('composer.json') != ''
19+
uses: ramsey/composer-install@v2
20+
with:
21+
composer-options: "--no-dev"
22+
- uses: FriendsOfREDAXO/installer-action@v1
23+
with:
24+
myredaxo-username: ${{ secrets.MYREDAXO_USERNAME }}
25+
myredaxo-api-key: ${{ secrets.MYREDAXO_API_KEY }}
26+
description: ${{ github.event.release.body }}
27+
version: ${{ github.event.release.tag_name }}

‎LICENSE‎

Lines changed: 21 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,21 @@
1+
MIT License
2+
3+
Copyright (c) 2024 Friends Of REDAXO
4+
5+
Permission is hereby granted, free of charge, to any person obtaining a copy
6+
of this software and associated documentation files (the "Software"), to deal
7+
in the Software without restriction, including without limitation the rights
8+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9+
copies of the Software, and to permit persons to whom the Software is
10+
furnished to do so, subject to the following conditions:
11+
12+
The above copyright notice and this permission notice shall be included in all
13+
copies or substantial portions of the Software.
14+
15+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21+
SOFTWARE.

‎README.md‎

Lines changed: 130 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,130 @@
1+
# YForm Rapidmail für REDAXO 5
2+
3+
Stellt den Rapidmail PHP-SDK zur Verfügung. Und synchronisiert Email-Adressen mit Empfängerlisten. REDAXO-Add-on für die Newsletter-Software rapidmail, kein offizielles rapidmail-Add-on.
4+
5+
## Einrichtung
6+
7+
1. API-Zugang bei Rapidmail einrichten
8+
2. API-Zugang in den Einstellungen YForm > Rapidmail > Einstellungen hinterlegen.
9+
3. Gewünschte Empfängerliste(n) bei Rapidmail anlegen
10+
11+
Wenn erfolgreich, dann werden in den Einstellungen die verfügbaren Empfängerlisten und deren IDs angezeigt.
12+
13+
## Beispiel-Action
14+
15+
Voraussetzung:
16+
17+
* Empfänger-Liste mit bekannter ID, diese als `###LIST_ID###` in der Action verwenden.
18+
19+
Optional:
20+
21+
* `newsletter_optin` als Checkbox, um Opt-In DSGVO-konform abzufragen.
22+
23+
Pipe-Schreibweise
24+
25+
```plaintext
26+
checkbox|newsletter_optin|Möchten Sie den Newsletter empfangen?|0|
27+
email|email|E-Mail-Adresse
28+
action|yform_rapidmail|###LIST_ID###|email|newsletter_optin
29+
```
30+
31+
PHP-Schreibweise
32+
33+
```php
34+
$yform->setValueField('checkbox', ['newsletter_optin','Möchten Sie den Newsletter empfangen?','0','0']);
35+
$yform->setValueField('text', ['email','E-Mail-Adresse','','0','{"type":"email"}','']);
36+
$yform->setActionField('yform_rapidmail', ['###LIST_ID###', 'email', 'newsletter_optin']);
37+
```
38+
Vollständige Definition:
39+
40+
```
41+
action|yform_rapidmail|list_id|email_fieldname(e.g. email)|opt:optin_fieldname(e.g. newsletter)|opt:fieldname_fullname(fullname)
42+
```
43+
44+
## Beispiel für eigene Nutzung / Ausgabe / etc
45+
46+
```php
47+
48+
<?php
49+
50+
use Rapidmail\ApiClient\Client;
51+
52+
$client = new Client(rex_config::get('yform_rapidmail', 'api_user_hash'), rex_config::get('yform_rapidmail', 'api_password_hash'));
53+
54+
$recipientsService = $client->recipients();
55+
56+
/*
57+
58+
$collection = $recipientsService->query(
59+
[
60+
'recipientlist_id' => rex_config::get('yform_rapidmail', 'sh_group_list_id') // Recipientlist ID MUST be provided
61+
]
62+
);
63+
64+
foreach ($collection as $recipient) {
65+
// dump($recipient);
66+
// Echo additional properties of $recipient individually
67+
echo $recipient['recipientlist_id'] . '<br>';
68+
echo $recipient['email'] . '<br>';
69+
echo $recipient['firstname'] . '<br>';
70+
echo $recipient['lastname'] . '<br>';
71+
echo $recipient['gender'] . '<br>';
72+
echo $recipient['title'] . '<br>';
73+
echo $recipient['zip'] . '<br>';
74+
echo $recipient['birthdate'] . '<br>';
75+
echo $recipient['extra1'] . '<br>';
76+
echo $recipient['extra2'] . '<br>';
77+
echo $recipient['extra3'] . '<br>';
78+
echo $recipient['extra4'] . '<br>';
79+
echo $recipient['extra5'] . '<br>';
80+
echo $recipient['extra6'] . '<br>';
81+
echo $recipient['extra7'] . '<br>';
82+
echo $recipient['extra8'] . '<br>';
83+
echo $recipient['extra9'] . '<br>';
84+
echo $recipient['extra10'] . '<br>';
85+
echo $recipient['mailtype'] . '<br>';
86+
echo $recipient['foreign_id'] . '<br>';
87+
echo $recipient['created_ip'] . '<br>';
88+
echo $recipient['created_host'] . '<br>';
89+
echo $recipient['created'] . '<br>';
90+
echo $recipient['updated'] . '<br>';
91+
echo $recipient['status'] . '<br>';
92+
// Add more properties as needed
93+
}
94+
*/
95+
96+
97+
// https://developer.rapidmail.wiki/documentation.html?urls.primaryName=Recipients#/RecipientImport/post_recipients_import
98+
$import = [];
99+
$import['recipientlist_id'] = rex_config::get('yform_rapidmail', 'sh_group_list_id');
100+
$import['file']['type'] = "text/csv";
101+
$import['file']['content'] = base64_encode(rex_file::get(rex_path::addon('yform_rapidmail', 'rapidmail.csv')));
102+
103+
$config = [];
104+
$config['recipient_exists'] = "importfile";
105+
$config['recipient_missing'] = "softdelete";
106+
$config['recipient_deleted'] = "import";
107+
$config['test_mode'] = "yes";
108+
$response = $recipientsService->import($import, $config);
109+
110+
dump($response);
111+
112+
```
113+
114+
## Lizenz
115+
116+
[MIT Lizenz](LICENSE)
117+
Bitte Lizenzbedingungen des Drittanbieters (Rapidmail PHP-SDK) beachten!
118+
119+
## Autor
120+
121+
**Friends Of REDAXO**
122+
http://www.redaxo.org
123+
https://github.com/FriendsOfREDAXO
124+
125+
**Projekt-Lead**
126+
[Alexander Walther](https://github.com/alexplusde)
127+
128+
## Credits
129+
[@alexplusde](https://github.com/sponsors/alexplusde) (Initiator)
130+
[rapidmail APIv3 client](https://github.com/rapidmail/rapidmail-apiv3-client-php)

‎assets/jetzt-beauftragen.svg‎

Lines changed: 1 addition & 0 deletions
Loading

‎boot.php‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,5 @@
1+
<?php
2+
3+
/**
4+
* @var rex_addon $this
5+
*/

0 commit comments

Comments
 (0)