Download the PHP package minishlink/web-push without Composer

On this page you can find all versions of the php package minishlink/web-push. It is possible to download/install these versions without Composer. Possible dependencies are resolved automatically.

FAQ

After the download, you have to make one include require_once('vendor/autoload.php');. After that you have to import the classes with use statements.

Example:
If you use only one package a project is not needed. But if you use more then one package, without a project it is not possible to import the classes with use statements.

In general, it is recommended to use always a project to download your libraries. In an application normally there is more than one library needed.
Some PHP packages are not free to download and because of that hosted in private repositories. In this case some credentials are needed to access such packages. Please use the auth.json textarea to insert credentials, if a package is coming from a private repository. You can look here for more information.

  • Some hosting areas are not accessible by a terminal or SSH. Then it is not possible to use Composer.
  • To use Composer is sometimes complicated. Especially for beginners.
  • Composer needs much resources. Sometimes they are not available on a simple webspace.
  • If you are using private repositories you don't need to share your credentials. You can set up everything on our site and then you provide a simple download link to your team member.
  • Simplify your Composer build process. Use our own command line tool to download the vendor folder as binary. This makes your build process faster and you don't need to expose your credentials for private repositories.
Please rate this library. Is it a good library?

Example code of minishlink/web-push

Informations about the package web-push

WebPush

Web Push library for PHP

Build Status

WebPush can be used to send push messages to endpoints as described in the Web Push protocol.

This push message is then received by the browser, which can then create a notification using the service worker and the Notifications API.

Requirements

PHP 8.1+ and the following extensions:

There is no support and maintenance for older PHP versions, however you are free to use the following compatible versions:

This README is only compatible with the latest version. Each version of the library has a git tag where the corresponding README can be read.

Installation

Use composer to download and install the library and its dependencies.

Usage

Example

A complete example with html+JS frontend and php backend using web-push-php can be found here: Minishlink/web-push-php-example

Send Push Message

Authentication (VAPID)

Browsers need to verify your identity. A standard called VAPID can authenticate you for all browsers. You'll need to create and provide a public and private key for your server. These keys must be safely stored and should not change.

You can specify your authentication details when instantiating WebPush. The keys can be passed directly (recommended), or you can load a PEM file or its content:

In order to generate the uncompressed public and secret key, encoded in Base64, enter the following in your Linux bash:

If you can't access a Linux bash, you can print the output of the createVapidKeys function:

On the client-side, don't forget to subscribe with the VAPID public key as the applicationServerKey: (urlBase64ToUint8Array source here)

Reusing VAPID headers

VAPID headers make use of a JSON Web Token (JWT) to verify your identity. That token payload includes the protocol and hostname of the endpoint included in the subscription and an expiration timestamp (usually between 12-24h), and it's signed using your public and private key. Given that, two notifications sent to the same push service will use the same token, so you can reuse them for the same flush session to boost performance using:

Notifications and default options

Each notification can have a specific Time To Live, urgency, and topic. The WebPush standard states that urgency is optional but some users reports that Safari throws errors when it is not specified. This might be fixed in the future. You can change the default options with setDefaultOptions() or in the constructor:

TTL

Time To Live (TTL, in seconds) is how long a push message is retained by the push service (eg. Mozilla) in case the user browser is not yet accessible (eg. is not connected). You may want to use a very long time for important notifications. The default TTL is 4 weeks. However, if you send multiple nonessential notifications, set a TTL of 0: the push notification will be delivered only if the user is currently connected. For other cases, you should use a minimum of one day if your users have multiple time zones, and if they don't several hours will suffice.

urgency

Urgency can be either "very-low", "low", "normal", or "high". If the browser vendor has implemented this feature, it will save battery life on mobile devices (cf. protocol).

topic

This string will make the vendor show to the user only the last notification of this topic (cf. protocol).

batchSize

If you send tens of thousands notifications at a time, you may get memory overflows due to how endpoints are called in Guzzle. In order to fix this, WebPush sends notifications in batches. The default size is 1000. Depending on your server configuration (memory), you may want to decrease this number. Do this while instantiating WebPush or calling setDefaultOptions. Or, if you want to customize this for a specific flush, give it as a parameter : $webPush->flush($batchSize).

Server errors

You can see what the browser vendor's server sends back in case it encountered an error (push subscription expiration, wrong parameters...).

PLEASE NOTE: You can only iterate once over the \Generator object.

Firefox errors are listed in the autopush documentation.

Payload length, security, and performance

Payloads are encrypted by the library. The maximum payload length is theoretically 4078 bytes (or ASCII characters). For compatibility reasons (archived) though, your payload should be less than 3052 bytes long.

The library pads the payload by default. This is more secure but it decreases performance for both your server and your user's device.

Why is it more secure?

When you encrypt a string of a certain length, the resulting string will always have the same length, no matter how many times you encrypt the initial string. This can make attackers guess the content of the payload. In order to circumvent this, this library adds some null padding to the initial payload, so that all the input of the encryption process will have the same length. This way, all the output of the encryption process will also have the same length and attackers won't be able to guess the content of your payload.

Why does it decrease performance?

Encrypting more bytes takes more runtime on your server, and also slows down the user's device with decryption. Moreover, sending and receiving the packet will take more time. It's also not very friendly with users who have limited data plans.

How can I disable or customize automatic padding?

You can customize automatic padding in order to better fit your needs.

Here are some ideas of settings:

Customizing the HTTP client

WebPush uses Guzzle. It will use the most appropriate client it finds, and most of the time it will be MultiCurl, which allows to send multiple notifications in parallel.

You can customize the default request options and timeout when instantiating WebPush:

Common questions (FAQ)

Is there any plugin/bundle/extension for my favorite PHP framework?

The following are available:

Feel free to add your own!

What about security?

Payload is encrypted according to the Message Encryption for Web Push standard, using the user public key and authentication secret that you can get by following the Web Push API specification.

Internally, WebPush uses the WebToken framework and OpenSSL to handle encryption keys generation and encryption.

How do I scale?

Here are some ideas:

  1. Make sure MultiCurl is available on your server
  2. Find the right balance for your needs between security and performance (see above)
  3. Find the right batch size (set it in defaultOptions or as parameter to flush())
  4. Use flushPooled() instead of flush(). The former uses concurrent requests, accelerating the process and often doubling the speed of the requests.

How to solve "SSL certificate problem: unable to get local issuer certificate"?

Your installation lacks some certificates.

  1. Download cacert.pem.
  2. Edit your php.ini: after [curl], type curl.cainfo = /path/to/cacert.pem.

You can also force using a client without peer verification.

How to solve "Class 'Minishlink\WebPush\WebPush' not found"

Make sure to require Composer's autoloader.

I get authentication errors when sending notifications

Make sure to have database fields that are large enough for the length of the data you are storing (#233). For the endpoint, users have reported that the URL length does not exceed 500 characters, but this can evolve so you can set it to the 2048 characters limit of most browsers.

I lost my VAPID keys!

See issue #58.

I'm using Google Cloud Messaging (GCM), how do I use this library?

This service does not exist anymore. It has been superseded by Google's Firebase Cloud Messaging (FCM) on May 29, 2019.

I'm using Firebase Cloud Messaging (FCM), how do I use this library?

This library does not support Firebase Cloud Messaging (FCM). Old Chrome subscriptions (prior 2018 and VAPID) do use Legacy HTTP protocol by Firebase Cloud Messaging (FCM) which is deprecated since 2023 and will stop working in June 2024. The support for this outdated subscription is removed.

Please do not be confused as Legacy HTTP protocol and Web Push with VAPID use the identical endpoint URL:

https://fcm.googleapis.com/fcm/send

Web Push with VAPID will remain available at this URL. No further action is currently required.

How to send data?

The browser vendors do not allow to send data using the Push API without creating a notification. Use some alternative APIs like WebSocket/WebTransport or Background Synchronization.

I need to send notifications to native apps. (eg. APNS for iOS)

WebPush is for web apps. You need something like RMSPushNotificationsBundle (Symfony).

This is PHP... I need Javascript!

This library was inspired by the Node.js web-push-libs/web-push library.

Reference

Examples, Notes and Overviews

Internet Engineering Task Force (IETF)

W3C

License

MIT

All versions of web-push with dependencies

PHP Build Version
Package Version
Requires php Version >=8.1
ext-curl Version *
ext-json Version *
ext-mbstring Version *
ext-openssl Version *
guzzlehttp/guzzle Version ^7.4.5
web-token/jwt-library Version ^3.3.0|^4.0.0
spomky-labs/base64url Version ^2.0.4
Composer command for our command line client (download client) This client runs in each environment. You don't need a specific PHP version etc. The first 20 API calls are free. Standard composer command

The package minishlink/web-push contains the following files

Loading the files please wait ....