jvitasek / nwsltr
A ready-made self-hosted mailing system on PHP 8, Vue.js, Doctrine ORM and Nette Framework
Installs: 4
Dependents: 0
Suggesters: 0
Security: 0
Stars: 2
Watchers: 3
Forks: 0
Open Issues: 2
Type:project
Requires
- php: >= 8
- contributte/application: ^0.5.0
- contributte/console: ^0.9.0
- contributte/console-extra: ^0.6.0
- contributte/event-dispatcher: ^0.8.0
- contributte/event-dispatcher-extra: ^0.8.0
- contributte/forms-bootstrap: ^0.3.2
- contributte/monolog: ^0.5.0
- contributte/redis: ^0.3.0
- jvitasek/dumpanddie: ^1.1
- latte/latte: ^2.9
- nette/application: ^3.1
- nette/bootstrap: ^3.1
- nette/caching: ^3.1
- nette/database: ^3.1
- nette/di: ^3.0
- nette/finder: ^2.5
- nette/forms: ^3.0
- nette/http: ^3.1
- nette/mail: ^3.1
- nette/robot-loader: ^3.3
- nette/security: ^3.1
- nette/utils: ^3.2
- nettrine/annotations: ^0.7.0
- nettrine/cache: ^0.3.0
- nettrine/dbal: ^0.7.0
- nettrine/extensions-beberlei: ^0.2.0
- nettrine/fixtures: ^0.6.0
- nettrine/migrations: ^0.7.0
- nettrine/orm: ^0.8.1
- phpoffice/phpspreadsheet: ^1.16
- tracy/tracy: ^2.8
- ublaboo/api-router: ^4.0
Requires (Dev)
- codeception/codeception: ^4.1
- codeception/module-asserts: ^1.0.0
- codeception/module-phpbrowser: ^1.0.0
- jetbrains/phpstorm-attributes: ^1.0
- nette/tester: ^2.4
- phpstan/extension-installer: ^1.1
- phpstan/phpstan-nette: ^0.12.16
- slevomat/coding-standard: ^6.4
- symfony/thanks: ^1
This package is auto-updated.
Last update: 2024-09-22 18:22:23 UTC
README
This project contains a ready-made self-hosted mailing system written in PHP8, Nette Framework, Doctrine 2 and Vue.js
System Requirements
- >= PHP 8.0
- >= MySQL 8
- Redis Server
- Composer
- Yarn + Webpack
Installation
The ideal way of installing this project is via Composer:
$ composer create-project jvitasek/nwsltr
Or directly clone this repository:
$ git clone https://github.com/jvitasek/nwsltr.git
Once you have the project files, do the following:
- Create an empty MySQL database
- Create a new file config/test.neon and copy the contents of config/test.sample.neon in there
Now you have two options:
Automatic installation (recommended)
- Set the right permissions to the init script:
$ chmod +x bin/init
(UNIX only) - Run
$ bin/init
which takes care of all the necessary configuration
Manual Installation
- Create directories log and temp in the root folder (
$ mkdir log temp && chmod +x log temp
) $ composer i
$ php bin/console orm:clear-cache:metadata
$ php bin/console o:s:u -f
$ chmod +x bin/*
(UNIX only)$ php bin/console doctrine:fixtures:load -n
$ cd www/FrontModule && yarn && yarn build
Self-hosted Use
During the installation steps you loaded fixtures into the newly created database. These fixtures contain a sample account and a user. Once you finish the installation, you can access the website and log in using these credentials:
E-mail: admin@sample.com
Password: secret
With these credentials, you can access the system as an administrator. It is recommended to remove this account after creating a new one with a strong password.
Crontab setup
When you self-host this application, you need to set-up a cronjob to automatically send the planned mailings.
1-59 * * * * php bin/console mailing:send
Alternatively, you can run this command anytime you need to send the newsletter
# does a dry run not actually sending the e-mails $ php bin/console mailing:send -t # actually sends the e-mails $ php bin/console mailing:send
Tests
This package comes with some ready-made tests.
Acceptance Tests
For acceptence tests, Codeception was used. You can run these tests like this:
$ php vendor/bin/codecept run --steps
Unit Tests
Unit and feature tests are run with Nette Tester
$ vendor/bin/tester -c tests/tester/php.ini tests/tester
Static Analysis
There are two static analysis tools to help with detecting and fixing errors in the code.
PHPStan
$ vendor/bin/phpstan analyse
PHP_CodeSniffer with error detection
$ vendor/bin/phpcs --standard=ruleset.xml --extensions=php --tab-width=4 -sp app
PHP_CodeSniffer with error fixing
$ vendor/bin/phpcbf --standard=ruleset.xml --extensions=php --tab-width=4 -sp app
Web Application Usage
All use-cases require logging in first. Next sections will assume you are already logged in to the system.
Creating recipient data
It is important to first create some recipient data, since you cannot send a mailing without a recipient group with at least one subscribed recipient.
- Access the Groups section in the left sidebar
- Create the Group you want to send the mailing to (e.g. Golf Players)
- Now you have 2 choices:
- Import recipients to the created group using an Excel file
- Add recipients manually in the Recipients section and indicate the created group in their Recipient Groups field
Creating mailings
Now that we have some recipient data in the system, we can go ahead and start building a new mailing campaign.
- Go to the Mailings section in the left sidebar and click on the Create Mailing button in the top-right corner
- In the editor, proceed as follows:
- Click on the pencil icon in the top-left corner of the screen and fill out the title, subject and the date of the mailing. Then indicate which Recipient Groups should receive the mailing.
- Click on the plus icon in the top-left corner of the screen and use the components to build your mailing template.
- (Optional) You can view the preview of your progress by clicking the Preview button in the top-right corner of the screen.
- Once you are finished building the template, you can click the Back button and return to the Mailing datagrid.
- Now you are ready to set the status of your newly created mailing to Ready. Based on the date that was set in the mailing editor, the system will automatically send the mailing once the date is reached (the crontab should ideally run every minute)