phplist/web-frontend

A web frontend for phpList, the world's most popular open source newsletter manager

v5.0.0-alpha8 2025-07-02 03:34 UTC

Requires

• php: ^8.1
• phplist/core: v5.0.0-alpha8
• symfony/twig-bundle: ^6.4
• symfony/webpack-encore-bundle: ^2.2

Requires (Dev)

• bshaffer/phpunit-retry-annotations: ^0.3.0
• dbrekelmans/bdi: *
• guzzlehttp/guzzle: ^7.2.0
• nette/caching: ^3.1.0
• nikic/php-parser: ^v4.10.4
• phpmd/phpmd: ^2.9.1
• phpstan/phpstan: ^1.10
• phpunit/phpunit: ^9.5
• squizlabs/php_codesniffer: ^3.5.8
• symfony/panther: *
• symfony/process: ^6.4

AGPL-3.0-or-later

• Xheni Myrtaj
• Oliver Klee
• Tatevik Grigoryan

• newsletter
• email
• manager
• frontend
• phplist

Published on Packagist.org on 2025-07-02 03:36 UTC

README

About phpList

phpList is an open source newsletter manager.

About this package

This module will contain the web frontend for phpList 4. It will not have any SQL queries but use functionality from the phpList 4 core for DB access.

This module is optional, i.e., it will be possible to run phpList 4 without a web frontend.

Installation

Please install this package via Composer from within the phpList base distribution, which also has more detailed installation instructions in the README.

When this module is installed as a dependency, publish bundle assets to the host application's public/ directory:

php bin/console assets:install public --symlink --relative

This module serves its frontend files from /.

Contributing to this package

Please read the contribution guide on how to contribute and how to run the unit tests and style checks locally.

Code of Conduct

This project adheres to a Contributor Code of Conduct. By participating in this project and its community, you are expected to uphold this code.

Commands for running this project for local testing

# Start the Symfony local server
symfony local:server:start

# Compile and watch assets (including Vue.js components)
yarn encore dev --watch

Vue.js Integration

This project uses Vue.js for interactive UI components. Vue components are located in the assets/vue/ directory and are mounted to specific DOM elements:

• App.vue is mounted to the element with ID vue-app

To add new Vue components:

1. Create the component in the assets/vue/ directory
2. Import and mount it in assets/app.js
3. Add a mount point in the appropriate template

CKEditor 5 Integration

The rich text editor lives in assets/editor/ and is exposed to the existing forms through assets/vue/components/base/CkEditorField.vue.

Architecture

• assets/editor/CkEditor.vue is the reusable Vue 3 editor component.
• assets/editor/uploadAdapter.ts provides CKEditor upload support against a Symfony endpoint.
• assets/editor/assetBrowserPlugin.js adds a toolbar button that opens the native asset browser.
• assets/editor/EditorAssetPicker.vue shows existing uploaded files and inserts them as images or links.
• assets/editor/plugins.ts and assets/editor/toolbar.ts keep the editor configuration isolated and reusable.
• src/Service/EditorUploadService.php stores uploads in the public filesystem and returns a browser URL.
• src/Controller/EditorUploadController.php accepts authenticated uploads and lists existing assets.

Reused from the legacy plugin

• upload path conventions
• image validation rules
• public-file URL generation strategy
• file storage separation for editor content
• asset browsing behavior, expressed as a native Vue modal instead of a popup window

New behavior

• Vue component with v-model
• configurable toolbar and CKEditor options
• upload adapter with progress support
• cleanup on unmount
• read-only mode support
• existing file browser for reusing uploaded content

Build and test

yarn encore dev
yarn test:vue
vendor/bin/phpunit

Configuration

The backend uses the existing phpList upload directory parameters:

• phplist.upload_images_dir

Uploads are stored below public/<phplist.upload_images_dir>/ckeditor5/.

Limitations

• This integration only covers image uploads from CKEditor.
• elFinder is not embedded in the frontend UI; the frontend now provides a native asset browser instead.
• Existing legacy HTML content is preserved as-is, but custom HTML support still depends on CKEditor 5 output rules.