From d20aa65269c0978209574358b4bd55fd48d33758 Mon Sep 17 00:00:00 2001 From: WINBIGFOX Date: Tue, 29 Apr 2025 19:52:39 +0200 Subject: [PATCH] Add new updater docs, config options, and app relaunch feature Expanded documentation for the auto-updater, including events, manual updates, and usage instructions. Introduced new configuration fields for app description and website. Added support for relaunching the application with the `App::relaunch()` method. --- .../1/getting-started/configuration.md | 10 ++ .../docs/desktop/1/publishing/updating.md | 94 +++++++++++++++++-- .../docs/desktop/1/the-basics/application.md | 7 ++ 3 files changed, 105 insertions(+), 6 deletions(-) diff --git a/resources/views/docs/desktop/1/getting-started/configuration.md b/resources/views/docs/desktop/1/getting-started/configuration.md index 4e6b09fa..98935738 100644 --- a/resources/views/docs/desktop/1/getting-started/configuration.md +++ b/resources/views/docs/desktop/1/getting-started/configuration.md @@ -45,6 +45,16 @@ return [ * The copyright notice for your application. */ 'copyright' => env('NATIVEPHP_APP_COPYRIGHT'), + + /** + * The description of your application. + */ + 'description' => env('NATIVEPHP_APP_DESCRIPTION', 'An awesome app built with NativePHP'), + + /** + * The Website of your application. + */ + 'website' => env('NATIVEPHP_APP_WEBSITE', 'https://nativephp.com'), /** * The default service provider for your application. This provider diff --git a/resources/views/docs/desktop/1/publishing/updating.md b/resources/views/docs/desktop/1/publishing/updating.md index 9923c558..3051fc88 100644 --- a/resources/views/docs/desktop/1/publishing/updating.md +++ b/resources/views/docs/desktop/1/publishing/updating.md @@ -2,7 +2,9 @@ title: Updating order: 300 --- + ## The Updater + NativePHP ships with a built-in auto-update tool, which allows your users to update your application without needing to manually download and install new releases. @@ -10,9 +12,10 @@ This leaves you to focus on building and releasing new versions of your applicat distributing those updates to your users. **macOS: Automatic updating is only supported for [signed](/docs/publishing/building#signing-and-notarizing) -applications.** +applications.** ## How it works + The updater works by checking a remote URL for a new version of your application. If a new version is found, the updater will download the new version and replace the existing application files with the new ones. @@ -27,9 +30,10 @@ The updater supports three providers: You can configure all settings for the updater in your `config/nativephp.php` file or via your `.env` file. -**The updater will only run when your app is running in production mode.** +**The updater will only run when your app is running in production mode.** ## Configuration + The default updater configuration looks like this: ```php @@ -73,12 +77,14 @@ The default updater configuration looks like this: ``` How to setup your storage and generate the relevant API credentials: + - [DigitalOcean](https://docs.digitalocean.com/products/spaces/how-to/manage-access/) -- Amazon S3 - See [this video](https://www.youtube.com/watch?v=FLIp6BLtwjk&ab_channel=CloudCasts) by Chris Fidao or - this [Step 2](https://www.twilio.com/docs/video/tutorials/storing-aws-s3#step-2) of this article by Twilio +- Amazon S3 - See [this video](https://www.youtube.com/watch?v=FLIp6BLtwjk&ab_channel=CloudCasts) by Chris Fidao or + this [Step 2](https://www.twilio.com/docs/video/tutorials/storing-aws-s3#step-2) of this article by Twilio - If you got the error message "The bucket does not allow ACLs" you can follow this guide from [Learn AWS](https://www.learnaws.org/2023/08/26/aws-s3-bucket-does-not-allow-acls) - on how to setup your bucket correctly. + If you got the error message "The bucket does not allow ACLs" you can follow this guide + from [Learn AWS](https://www.learnaws.org/2023/08/26/aws-s3-bucket-does-not-allow-acls) + on how to setup your bucket correctly. ## Disabling the updater @@ -88,3 +94,79 @@ If you don't want your application to check for updates, you can disable the upd ```dotenv NATIVEPHP_UPDATER_ENABLED=false ``` + +## Manually checking for updates + +You can manually check for updates by calling the `checkForUpdates` method on the `AutoUpdater` facade: + +```php +use Native\Laravel\Facades\AutoUpdater; + +AutoUpdater::checkForUpdates(); +``` + +**Note:** If an update is available, it will be downloaded automatically. Calling `AutoUpdater::checkForUpdates() twice +will download the update two times. + +## Quit and Install + +You can quit the application and install the update by calling the `quitAndInstall` method on the `AutoUpdater` facade: + +```php +use Native\Laravel\Facades\AutoUpdater; + +AutoUpdater::quitAndInstall(); +``` + +This will quit the application and install the update. The application will then relaunch automatically. + +**Note:** Calling this method is optional — any successfully downloaded update will be applied the next time the +application starts. + +## Events + +### `CheckingForUpdate` + +The `Native\Laravel\Events\AutoUpdater\CheckingForUpdate` event is dispatched when checking for an available update has +started. + +### `UpdateAvailable` + +The `Native\Laravel\Events\AutoUpdater\UpdateAvailable` event is dispatched when there is an available update. The +update is downloaded automatically. + +### `UpdateNotAvailable` + +The `Native\Laravel\Events\AutoUpdater\UpdateNotAvailable` event is dispatched when there is no available update. + +### `DownloadProgress` + +The `Native\Laravel\Events\AutoUpdater\DownloadProgress` event is dispatched when the update is being downloaded. + +The event contains the following properties: + +- `total`: The total size of the update in bytes. +- `delta`: The size of the update that has been downloaded since the last event. +- `transferred`: The total size of the update that has been downloaded. +- `percent`: The percentage of the update that has been downloaded (0-100). +- `bytesPerSecond`: The download speed in bytes per second. + +### `UpdateDownloaded` + +The `Native\Laravel\Events\AutoUpdater\UpdateDownloaded` event is dispatched when the update has been downloaded. + +The event contains the following properties: + +- `version`: The version of the update. +- `downloadedFile`: The local path to the downloaded update file. +- `releaseDate`: The release date of the update in ISO 8601 format. +- `releaseNotes`: The release notes of the update. +- `releaseName`: The name of the update. + +### `Error` + +The `Native\Laravel\Events\AutoUpdater\Error` event is dispatched when there is an error while updating. + +The event contains the following properties: + +- `error`: The error message. diff --git a/resources/views/docs/desktop/1/the-basics/application.md b/resources/views/docs/desktop/1/the-basics/application.md index c5c05df6..da0c88f5 100644 --- a/resources/views/docs/desktop/1/the-basics/application.md +++ b/resources/views/docs/desktop/1/the-basics/application.md @@ -23,6 +23,13 @@ To quit the app, use the `quit` method: App::quit(); ``` +### Relaunch the app +To relaunch the app, use the `relaunch` method. This will quit the app and relaunch it. + +```php +App::relaunch(); +``` + ### Focus the app To focus the app, use the `focus` method.