{"id":20961848,"url":"https://github.com/heimrichhannot/contao-pwa-bundle","last_synced_at":"2025-06-16T01:39:38.060Z","repository":{"id":52875953,"uuid":"154449816","full_name":"heimrichhannot/contao-pwa-bundle","owner":"heimrichhannot","description":"A bundle to provide progressive web app support for contao.","archived":false,"fork":false,"pushed_at":"2025-03-12T10:45:36.000Z","size":834,"stargazers_count":6,"open_issues_count":4,"forks_count":3,"subscribers_count":4,"default_branch":"main","last_synced_at":"2025-06-09T16:58:39.190Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"PHP","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"gpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/heimrichhannot.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2018-10-24T06:25:22.000Z","updated_at":"2025-03-12T10:38:18.000Z","dependencies_parsed_at":"2024-01-03T14:31:08.700Z","dependency_job_id":"31c37511-d132-4cf5-a703-4119b362032a","html_url":"https://github.com/heimrichhannot/contao-pwa-bundle","commit_stats":{"total_commits":127,"total_committers":7,"mean_commits":"18.142857142857142","dds":"0.11023622047244097","last_synced_commit":"010e3d62b6a3ac41f5a566d1e7756e38d363c532"},"previous_names":[],"tags_count":43,"template":false,"template_full_name":null,"purl":"pkg:github/heimrichhannot/contao-pwa-bundle","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/heimrichhannot%2Fcontao-pwa-bundle","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/heimrichhannot%2Fcontao-pwa-bundle/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/heimrichhannot%2Fcontao-pwa-bundle/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/heimrichhannot%2Fcontao-pwa-bundle/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/heimrichhannot","download_url":"https://codeload.github.com/heimrichhannot/contao-pwa-bundle/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/heimrichhannot%2Fcontao-pwa-bundle/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":260082766,"owners_count":22956341,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-11-19T02:17:54.517Z","updated_at":"2025-06-16T01:39:38.036Z","avatar_url":"https://github.com/heimrichhannot.png","language":"PHP","readme":"# Contao Progressive Web App Bundle\n\nA bundle to provide progressive web app support for contao.\n\n\u003e This bundle is still in beta. Please provide feedback if you use it!\n\nThis bundle is using [PHP Web Push lib](https://github.com/web-push-libs/web-push-php) to provide push notifications. \n\n## Features\n\n* Create and register manifest file for each page root\n* Create and register service worker for each page root\n* send custom push notifications from backend\n* set an offline fallback page\n* Frontend module and content element to subscribe to push notifications\n* Install PWA button content element\n* [Encore Bundle](https://github.com/heimrichhannot/contao-encore-bundle) support, including asset precaching\n* expandable architecture\n\n## Setup\n\n### Requirements\n\n* PHP \u003e= 7.4\n* Contao \u003e=4.9 \n* [Contao Head Bundle](https://github.com/heimrichhannot/contao-head-bundle)\n\nFor web push notifications:\n- Composer package [`\"minishlink/web-push\": \"^8.0\"`](https://github.com/web-push-libs/web-push-php) (version 5 to 8 are supported)\n- PHP extensions:\n    * gmp\n    * mbstring\n    * curl\n    * openssl\n\n\n### Install\n\n1. Install via composer or contao manager \n\n        composer require heimrichhannot/contao-pwa-bundle\n\n2. Update your database\n\n\n### First Steps\n1. Your page template (typically `fe_page.html5`) must support [Head Bundle](https://github.com/heimrichhannot/contao-head-bundle). This means it must output at least `$this-\u003emeta()` in head section. See [Head Bundle readme](https://github.com/heimrichhannot/contao-head-bundle/blob/master/README.md) for more information\n1. If you want to use push notifications, add vapid keys to your config (see [Setup -\u003e Vapidkeys](#push-notifications))\n1. Create an PWA Configuration(Backend -\u003e System -\u003e PWA Configuration)\n1. Add the configuration to a page root (in page settings you find a new section \"Progressive Web App\", select yes and choose your configuration)\n    * On saving the page the page manifest and the serviceworker will be generated\n1. To provide an option to register to your push notifications, add the Push Subscription Button content element or the push notification popup frontend module to your page.\n \n### Push Notifications\n\n#### VAPID keys\n\nYou need to add your server vapid keys to your config file, typical in your project config.yml. If you haven't already vapid keys, you can generate in the PWA Bundle backend (Contao Backend -\u003e System -\u003e PWA Configuration -\u003e Control -\u003e Authentication)\n\n```yaml\nhuh_pwa:\n  vapid:\n    subject: \"mailto:test@example.org\"\n    publicKey: \"BPZACSEB_Efa3_e2XdVRm4M3Suga2WnhNs9THpVixfScWicSiA3ZYQ3zCG4Uez3EnbL3q-O2RomlZtYejva642M\"\n    privateKey: \"W0qtmwq0aB47Swmid0uDZyW945p9b5bgv_WmfsmsRHw\"\n```\n\n## Usage\n\n### Regenerate files\nYou can regenerate all your manifest and service worker files at once from the Pwa Control (Contao Backend -\u003e System -\u003e PWA Configuration -\u003e Control -\u003e Files -\u003e Rebuild files)\n\nThere is also an command available: `huh:pwa:build`\n\n## Developers\n\n### JS Event\n\nTo support custom controls, there are events and event listeners that can be used. All events are dispatched and listen to on `document`. \n\n#### Events\n\nEvent                              | Description\n---------------------------------- | --------------------\nhuh_pwa_sw_not_supported           | Fired if browser not supports serviceworker or no service worker found.\nhuh_pwa_push_not_supported         | Fired if browser not supports push notifications\nhuh_pwa_push_permission_denied     | Fired if browser has push notifications blocked\nhuh_pwa_push_isSubscribed          | Fired when subscribed to push notifications (on page load or when subscribe)\nhuh_pwa_push_isUnsubscribed        | Fired when unsubscribed from push notification (on page load or when unsubscribe)\nhuh_pwa_push_subscription_failed   | Fired when subscription to push notifications failed. Error reason can be found in event.detail.reason.\nhuh_pwa_push_unsubscription_failed | Fired when unsubscribe from push notifications failed. Error reason can be found in event.detail.reason.\n\n#### Listener\n\nEvent type | Usage | Description\n---------- | ----- | -----------\nhuh_pwa_push_changeSubscriptionState | `new CustomEvent( 'huh_pwa_push_changeSubscriptionState', {detail: ['subscribe'\\|'unsubscribe']} )` | Fire this event when the user interacts with your control to change his subscription state. Use a `CustomEvent` with detail parameter set to subscribe or unsubscrive.\n\n### Complete configuration\n\n```yaml\nhuh_pwa:\n  vapid:\n    subject: \"mailto:test@example.org\"\n    publicKey: \"BPZACSEB_Efa3_e2XdVRm4M3Suga2WnhNs9THpVixfScWicSiA3ZYQ3zCG4Uez3EnbL3q-O2RomlZtYejva642M\"\n    privateKey: \"W0qtmwq0aB47Swmid0uDZyW945p9b5bgv_WmfsmsRHw\"\n  push:\n    automatic_padding: 2847 # int (payload size in byte (min 0, max 4078)) or boolean (enable/disable)\n  manifest_path: '/pwa' # where the manifest files should be located within web folder\n  configfile_path: '/pwa' # where the configuration files should be located within web folder\n```\n\n### Commands\n \nCommand          | Description\n---------------- | -----------\nhuh:pwa:build    | (Re)Build config specific files like service worker and manifest\nhuh:pwa:sendpush | Send unsent push notifications\n\n### Add additional head scripts\n\nIt is possible to add additional js code to the head section by using the `PwaHeadScriptTags` object available available as `huh.head.tag.pwa.script` service. Code added with `addScript` will be outputted in header section of your page within `\u003cscript type='text/javascript'\u003e` tags.\n\n### Polyfills\n\nFuntion | Example Polyfill | Description\n------- | ---------------- | -----------\nCustomEvent | [custom-event-polyfill](https://github.com/kumarharsh/custom-event-polyfill) | Custom events are needed to update the subscribe button (to inform the user that the browser not supporting push notifications). Also an error is thrown if the browser not supporting CustomEvents.\n\n## Todo\n* image size config\n* support svg icons\n* select pages to precache\n* customize add to homescreen and push notification notifications\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fheimrichhannot%2Fcontao-pwa-bundle","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fheimrichhannot%2Fcontao-pwa-bundle","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fheimrichhannot%2Fcontao-pwa-bundle/lists"}