PHPackages devsrealm/csskiller-plugin-mail-contract - PHPackages - PHPackages [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register) 1. [Directory](/) 2. / 3. devsrealm/csskiller-plugin-mail-contract ActiveLibrary devsrealm/csskiller-plugin-mail-contract ======================================== CSS Killer Mail Contract Plugin 1.0.3(3mo ago)00MITPHPPHP >=8.2 Since Feb 4Pushed 3mo agoCompare [ Source](https://github.com/devsrealm/csskiller-plugin-mail-contract)[ Packagist](https://packagist.org/packages/devsrealm/csskiller-plugin-mail-contract)[ RSS](/packages/devsrealm-csskiller-plugin-mail-contract/feed)WikiDiscussions main Synced 1mo ago READMEChangelog (3)Dependencies (1)Versions (4)Used By (0) CSS Killer Mail Contract Plugin =============================== [](#css-killer-mail-contract-plugin) A secure email-based terms acceptance plugin for CSS Killer CMS. This plugin provides a complete solution for collecting user consent through email verification, with built-in token management, audit trails, and automated cleanup. Features -------- [](#features) - **Secure Email Verification**: Generate cryptographically secure tokens for email confirmation - **Terms Acceptance Flow**: Complete workflow from form submission to confirmation - **Token Management**: Automatic expiration (24 hours), status tracking, and cleanup - **Audit Trail**: Permanent records of confirmed acceptances for compliance - **Responsive UI**: Modern, mobile-friendly templates using Tailwind CSS - **Console Commands**: Automated cleanup of expired tokens - **RESTful API**: JSON endpoints for integration with other systems Requirements ------------ [](#requirements) - PHP 8.2 or higher - CSS Killer CMS - Composer for dependency management Installation ------------ [](#installation) 1. Install via Composer: ``` composer require devsrealm/csskiller-plugin-mail-contract ``` 2. Enable the plugin in your CSS Killer CMS admin panel 3. Configure your email settings in the CMS configuration Usage ----- [](#usage) ### Basic Terms Acceptance Flow [](#basic-terms-acceptance-flow) 1. **Display Terms Form**: Direct users to `/terms` to show the acceptance form 2. **Submit Email**: User enters their email and submits the form 3. **Email Confirmation**: System sends a secure confirmation link via email 4. **Confirm Acceptance**: User clicks the link to confirm their acceptance 5. **Success Page**: User sees confirmation of successful acceptance ### API Endpoints [](#api-endpoints) The plugin provides the following REST endpoints under the `/terms` route: #### GET `/terms` [](#get-terms) Displays the terms acceptance form. #### POST `/terms/submit` [](#post-termssubmit) Submits the terms acceptance request. **Request Body:** ``` { "email": "user@example.com" } ``` **Response:** ``` { "success": true, "message": "Please check your email to confirm your acceptance...", "email": "user@example.com" } ``` #### GET `/terms/confirm?token=` [](#get-termsconfirmtokentoken) Confirms the terms acceptance using the token from the email link. #### GET `/terms/status?email=` [](#get-termsstatusemailemail) Retrieves the status of tokens for a given email address. **Response:** ``` { "email": "user@example.com", "total_tokens": 2, "tokens": [ { "id": 1, "token": "abc123...", "data": { "email": "user@example.com", "status": "confirmed", "expires_at": "2024-01-01 12:00:00", "confirmed_at": "2024-01-01 10:30:00" }, "created_at": "2024-01-01 09:00:00", "updated_at": "2024-01-01 10:30:00" } ] } ``` ### Console Commands [](#console-commands) #### Cleanup Expired Tokens [](#cleanup-expired-tokens) Remove expired pending tokens while preserving confirmed tokens for audit purposes: ``` php console --cleanup:terms:tokens ``` This command: - Removes tokens that have expired and are still pending - Preserves all confirmed tokens as permanent audit records - Should be run periodically (e.g., via cron job) ### Programmatic Usage [](#programmatic-usage) #### Using the TokenSignatureService [](#using-the-tokensignatureservice) ``` use CSSKillerMailContract\services\TokenSignatureService; // Generate a confirmation token $service = new TokenSignatureService($core); $token = $service->generateToken('user@example.com', [ 'ip_address' => $_SERVER['REMOTE_ADDR'], 'user_agent' => $_SERVER['HTTP_USER_AGENT'] ]); // Generate a full confirmation link $confirmation = $service->generateConfirmationLink( email: 'user@example.com', baseUrl: 'https://yoursite.com/terms/confirm', metadata: ['source' => 'registration'] ); // Validate a token $result = $service->validateToken($token); if ($result['valid']) { // Mark as confirmed $service->markAsConfirmed($token, $_SERVER['REMOTE_ADDR']); } // Get all tokens for an email $tokens = $service->getTokensByEmail('user@example.com'); ``` Configuration ------------- [](#configuration) ### Environment Variables [](#environment-variables) No additional environment variables are required beyond standard CSS Killer CMS configuration. ### Email Configuration [](#email-configuration) The plugin uses PHP's built-in `mail()` function by default. For production use, you should configure a proper email service in your CMS settings. ### Token Settings [](#token-settings) - **Token Expiry**: 24 hours (configurable in `TokenSignatureService::TOKEN_EXPIRY_HOURS`) - **Token Length**: 64 characters (32 bytes of random data, hex-encoded) - **Storage**: Tokens are stored in the CMS `system_global` table with context `MAIL_SIGN` Security Features ----------------- [](#security-features) - **Cryptographically Secure Tokens**: Uses `random_bytes()` for token generation - **Token Expiration**: Automatic expiration prevents indefinite validity - **Single-Use Tokens**: Tokens can only be confirmed once - **IP Tracking**: Records IP addresses for audit purposes - **Metadata Storage**: Stores user agent, timestamps, and custom metadata - **Audit Preservation**: Confirmed tokens are never deleted for compliance Templates --------- [](#templates) The plugin includes the following templates (located in `src/templates/`): - `terms-form.html` - The main terms acceptance form - `terms-success.html` - Success confirmation page - `terms-error.html` - Error display page Templates use the CSS Killer CMS template system and can be customized by overriding them in your theme. Database Storage ---------------- [](#database-storage) Tokens are stored in the `system_global` table with: - `context`: `MAIL_SIGN` - `key`: The token string - `value_json`: JSON data containing email, status, expiry, metadata, etc. Compliance & GDPR --------------------- [](#compliance--gdpr) - **Audit Trail**: All confirmations are permanently stored - **Data Minimization**: Only necessary data is collected - **Consent Records**: Permanent proof of user consent - **Cleanup**: Automated removal of unconfirmed/expired data Development ----------- [](#development) ### Project Structure [](#project-structure) ``` src/ ├── PluginEntry.php # Plugin registration ├── Routes.php # Route definitions ├── controllers/ │ └── TermsAcceptanceController.php ├── services/ │ └── TokenSignatureService.php ├── commands/ │ └── CleanupExpiredTokensCommand.php ├── middlewares/ │ └── AuthMiddleware.php └── templates/ ├── terms-form.html ├── terms-success.html └── terms-error.html ``` ### Extending the Plugin [](#extending-the-plugin) #### Custom Email Templates [](#custom-email-templates) Override the email sending in `TermsAcceptanceController::sendConfirmationEmail()` to use your preferred email service. #### Additional Metadata [](#additional-metadata) Pass additional metadata when generating tokens: ``` $confirmation = $service->generateConfirmationLink( email: $email, baseUrl: $baseUrl, metadata: [ 'custom_field' => 'value', 'user_id' => 123, 'campaign' => 'newsletter_signup' ] ); ``` #### Custom Validation [](#custom-validation) Extend the controller to add custom validation logic before token generation. License ------- [](#license) This plugin is licensed under the GNU Affero General Public License v3.0. Support ------- [](#support) For support and contributions, please contact the maintainer or create an issue in the project repository. Changelog --------- [](#changelog) ### Version 1.0.0 [](#version-100) - Initial release - Basic terms acceptance flow - Token management service - Console cleanup command - Responsive templates ### Health Score 36 — LowBetter than 82% of packages Maintenance80 Actively maintained with recent releases Popularity0 Limited adoption so far Community6 Small or concentrated contributor base Maturity49 Maturing project, gaining track record Bus Factor1 Top contributor holds 100% of commits — single point of failure How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window. **Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores. **Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement. **Maturity (30%)** — Project age, version count, PHP version support, and release stability. ### Release Activity Cadence Every ~0 days Total 3 Last Release 103d ago ### Community Maintainers ![](https://www.gravatar.com/avatar/0cf8f4cd756c2ce702e44d7e0542ca9e5d2cd9f4cf28fb3759081d19fe727894?d=identicon)[Tonics](/maintainers/Tonics) --- Top Contributors [![devsrealm](https://avatars.githubusercontent.com/u/37757164?v=4)](https://github.com/devsrealm "devsrealm (3 commits)") ### Embed Badge ![Health badge](/badges/devsrealm-csskiller-plugin-mail-contract/health.svg) ``` [![Health](https://phpackages.com/badges/devsrealm-csskiller-plugin-mail-contract/health.svg)](https://phpackages.com/packages/devsrealm-csskiller-plugin-mail-contract) ``` PHPackages © 2026 [Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)