Merge pull request #30 from stackkit/3.x

3.x

Author: marickvantuil

.github/workflows/run-tests.yml

@@ -63,20 +63,11 @@ jobs:
     strategy:
       matrix:
         payload:
-          - { laravel: '10.*', php: '8.3', 'testbench': '8.*'}
-          - { laravel: '10.*', php: '8.2', 'testbench': '8.*'}
-          - { laravel: '10.*', php: '8.1', 'testbench': '8.*'}
-          - { laravel: '9.*', php: '8.3', 'testbench': '7.*'}
-          - { laravel: '9.*', php: '8.2', 'testbench': '7.*'}
-          - { laravel: '9.*', php: '8.1', 'testbench': '7.*'}
-          - { laravel: '9.*', php: '8.0', 'testbench': '7.*'}
-          - { laravel: '8.*', php: '8.1', 'testbench': '6.*'}
-          - { laravel: '8.*', php: '8.0', 'testbench': '6.*'}
-          - { laravel: '8.*', php: '7.4', 'testbench': '6.*'}
-          - { laravel: '7.*', php: '8.0', 'testbench': '5.*' }
-          - { laravel: '7.*', php: '7.4', 'testbench': '5.*' }
-          - { laravel: '6.*', php: '8.0', 'testbench': '4.*' }
-          - { laravel: '6.*', php: '7.4', 'testbench': '4.*' }
+          - { laravel: '11.*', php: '8.3', 'testbench': '9.*', collision: '8.*'}
+          - { laravel: '11.*', php: '8.2', 'testbench': '9.*', collision: '8.*'}
+          - { laravel: '10.*', php: '8.3', 'testbench': '8.*', collision: '7.*'}
+          - { laravel: '10.*', php: '8.2', 'testbench': '8.*', collision: '7.*'}
+          - { laravel: '10.*', php: '8.1', 'testbench': '8.*', collision: '7.*'}
 
     name: PHP ${{ matrix.payload.php }} - Laravel ${{ matrix.payload.laravel }}
 
@@ -95,7 +86,7 @@ jobs:
 
       - name: Install dependencies
         run: |
-          composer require "laravel/framework:${{ matrix.payload.laravel }}" "orchestra/testbench:${{ matrix.payload.testbench }}" --no-interaction --no-update
+          composer require "laravel/framework:${{ matrix.payload.laravel }}" "orchestra/testbench:${{ matrix.payload.testbench }}" "nunomaduro/collision:${{ matrix.payload.collision }}" --no-interaction --no-update
           composer update --prefer-stable --prefer-dist --no-interaction
       - name: Execute tests
         run: composer test

.gitignore

@@ -3,3 +3,4 @@ composer.lock
 .idea/
 .DS_Store
 .phpunit.result.cache
+.phpunit.cache/

README.md

@@ -11,70 +11,96 @@
 
 This package allows you to use Google Cloud Scheduler to schedule Laravel commands.
 
-It only supports Artisan commands at this time due to security concerns.
-
 # How it works
 
 Cloud Scheduler will make HTTP calls to your application. This package adds an endpoint to your application that accepts these HTTP calls with their payload (an Artisan command) and execute them.
 
-#### withoutOverlapping, before, after, onSuccess, thenPing, etc
+There are two ways to schedule commands using this package:
 
-All these features are supported. This package scans your console kernel (`app/Console/Kernel.php`) to see if the scheduled command in Cloud Scheduler is also scheduled in the console kernel, If it is, it will respect all configured events/hooks associated with the command. (such as withoutOverlapping) 
+<details>
+<summary>1. Schedule the `schedule:run` command</summary>
 
-# Requirements
+This is the easiest way to use this package. You can schedule the `schedule:run` command to run every minute.
+</details>
+
+<details>
+<summary>2. Schedule commands separately</summary>
+
+If your application does not have commands that should run every minute, you may choose to schedule them individually.
+
+If the command uses `withoutOverlapping`, `before`, `after`, `onSuccess`, `thenPing`, etc, this package will respect those settings, as long as the command is also scheduled in the console kernel.
+
+For example, let's say we have to generate a report every day at 3:00 AM. We can schedule the `reports:generate` command to run at 3:00 AM using Cloud Scheduler. After the report is generated, OhDear should be pinged.
 
-This package requires Laravel 6 or higher.
+Firstly, schedule the command in Cloud Tasks:
 
-Please check the table below for supported Laravel and PHP versions:
+<img src="/schedule-command-example.png">
+
+Then, schedule the command in the console kernel:
+
+```php
+public function schedule(Schedule $schedule)
+{
+    $schedule->command('report:generate')
+        ->thenPing('https://ohdear.app/ping');
+}
+```
 
-|Laravel Version| PHP Version |
-|---|---|
-| 6.x | 7.4 or 8.0
-| 7.x | 7.4 or 8.0
-| 8.x | 7.4 or 8.0
-| 9.x | 8.0 or 8.1 or 8.2 or 8.3
-| 10.x | 8.1 or 8.2 or 8.3
+The package will pick up on the scheduled settings and ping OhDear after the command has run.
+</details>
+
+# Requirements
+
+This package requires Laravel 10 or 11.
 
 # Installation
 
-(1) Require the package using Composer
+1 - Require the package using Composer
 
 ```bash
 composer require stackkit/laravel-google-cloud-scheduler
 ```
 
-(2) Define the `STACKKIT_CLOUD_SCHEDULER_APP_URL` environment variable. This should be the URL defined in the `URL` field of your Cloud Scheduler job.
+2 - Define environment variables
 
-```
-STACKKIT_CLOUD_SCHEDULER_APP_URL=https://yourdomainname.com/cloud-scheduler-job
+`CLOUD_SCHEDULER_APP_URL` - This should be the URL defined in the `URL` field of your Cloud Scheduler job.
+
+`CLOUD_SCHEDULER_SERVICE_ACCOUNT` - The e-mail address of the service account invocating the task.
+
+Optionally, you may publish the configuration file:
+
+```bash
+php artisan vendor:publish --tag-cloud-scheduler-config
 ```
 
-(3) Optional: whitelist route for maintenance mode
+3 - Ensure PHP executable is in open_basedir. This is required for the package to run Artisan commands.
 
-This step is optional, but highly recommended. To allow jobs to keep running if the application is down (`php artisan down`) you must modify the `PreventRequestsDuringMaintenance` middleware:
+How to find the executable:
 
-```diff
-<?php
+```php
+php artisan tinker --execute="(new Symfony\\Component\\Process\\PhpExecutableFinder())->find()"
+```
 
-namespace App\Http\Middleware;
+4 - Optional, but highly recommended: server configuration
 
-use Illuminate\Foundation\Http\Middleware\PreventRequestsDuringMaintenance as Middleware;
+Since Artisan commands are now invoked via an HTTP request, you might encounter issues with timeouts. Here's how to adjust them:
 
-class PreventRequestsDuringMaintenance extends Middleware
-{
-    /**
-     * The URIs that should be reachable while maintenance mode is enabled.
-     *
-     * @var array
-     */
-    protected $except = [
-+        '/cloud-scheduler-job',
-    ];
+```nginx
+server {
+    # other server configuration ...
+
+    location /cloud-scheduler-job {
+        proxy_connect_timeout 600s;
+        proxy_read_timeout 600s;
+        fastcgi_read_timeout 600s;
+    }
+
+    # other locations and server configuration ...
 }
 
 ```
 
-(4) Optional: set application `RUNNING_IN_CONSOLE` (highly recommended)
+5 - Optional, but highly recommended: set application `RUNNING_IN_CONSOLE`
 
 Some Laravel service providers only register their commands if the application is being accessed through the command line (Artisan). Because we are calling Laravel scheduler from a HTTP call, that means some commands may never register, such as the Laravel Scout command:
 
@@ -101,73 +127,117 @@ public function boot()
 }
 ```
 
-To circumvent this, please add the following to `public/index.php`
+To circumvent this, please add the following to `bootstrap/app.php`
 
-```diff
-/*
-|--------------------------------------------------------------------------
-| Check If Application Is Under Maintenance
-|--------------------------------------------------------------------------
-|
-| If the application is maintenance / demo mode via the "down" command we
-| will require this file so that any prerendered template can be shown
-| instead of starting the framework, which could cause an exception.
-|
-*/
+<details>
+<summary>Laravel 11</summary>
+    
+```php
+<?php
+
+use Illuminate\Foundation\Application;
+use Illuminate\Foundation\Configuration\Exceptions;
+use Illuminate\Foundation\Configuration\Middleware;
 
-if (file_exists(__DIR__.'/../storage/framework/maintenance.php')) {
-    require __DIR__.'/../storage/framework/maintenance.php';
-}
-+ 
-+ /*
-+ |--------------------------------------------------------------------------
-+ | Manually Set Running In Console for Google Cloud Scheduler
-+ |--------------------------------------------------------------------------
-+ |
-+ | Some service providers only register their commands if the application
-+ | is running from the console. Since we are calling Cloud Scheduler
-+ | from the browser we must manually trick the application into
-+ | thinking that it is being run from the command line.
-+ |
-+ */
-+ 
 + if (($_SERVER['REQUEST_URI'] ?? '') === '/cloud-scheduler-job') {
 +     $_ENV['APP_RUNNING_IN_CONSOLE'] = true;
 + }
-+ 
-/*
-|--------------------------------------------------------------------------
-| Register The Auto Loader
-|--------------------------------------------------------------------------
-|
-| Composer provides a convenient, automatically generated class loader for
-| this application. We just need to utilize it! We'll simply require it
-| into the script here so we don't need to manually load our classes.
-|
-*/
 
-require __DIR__.'/../vendor/autoload.php';
+return Application::configure(basePath: dirname(__DIR__))
+    ->withRouting(
+        web: __DIR__.'/../routes/web.php',
+        commands: __DIR__.'/../routes/console.php',
+        health: '/up',
+    )
+    ->withMiddleware(function (Middleware $middleware) {
+        //
+    })
+    ->withExceptions(function (Exceptions $exceptions) {
+        //
+    })->create();
+
 ```
+</details>
 
-Copy the code here:
+<details>
+<summary>Laravel 10</summary>
 
 ```php
+<?php
+
 /*
 |--------------------------------------------------------------------------
-| Manually Set Running In Console for Google Cloud Scheduler
+| Create The Application
 |--------------------------------------------------------------------------
 |
-| Some service providers only register their commands if the application
-| is running from the console. Since we are calling Cloud Scheduler
-| from the browser we must manually trick the application into
-| thinking that it is being run from the command line.
+| The first thing we will do is create a new Laravel application instance
+| which serves as the "glue" for all the components of Laravel, and is
+| the IoC container for the system binding all of the various parts.
 |
 */
 
-if (($_SERVER['REQUEST_URI'] ?? '') === '/cloud-scheduler-job') {
-    $_ENV['APP_RUNNING_IN_CONSOLE'] = true;
+$app = new Illuminate\Foundation\Application(
+    $_ENV['APP_BASE_PATH'] ?? dirname(__DIR__)
+);
+
++ if (($_SERVER['REQUEST_URI'] ?? '') === '/cloud-scheduler-job') {
++     $_ENV['APP_RUNNING_IN_CONSOLE'] = true;
++ }
+```
+</details>
+
+6 - Optional: whitelist route for maintenance mode
+
+If you want to allow jobs to keep running if the application is down (`php artisan down`), update the following:
+
+<details>
+<summary>Laravel 11</summary>
+
+```php
+return Application::configure(basePath: dirname(__DIR__))
+    ->withRouting(
+        web: __DIR__ . '/../routes/web.php',
+        commands: __DIR__ . '/../routes/console.php',
+        health: '/up',
+    )
+    ->withMiddleware(function (Middleware $middleware) {
+        $middleware->preventRequestsDuringMaintenance(
+            except: [
+                '/cloud-scheduler-job',
+            ],
+        );
+    })
+    ->withExceptions(function (Exceptions $exceptions) {
+        //
+    })->create();
+
+
+```
+</details>
+<details>
+<summary>Laravel 10</summary>
+
+```php
+<?php
+
+namespace App\Http\Middleware;
+
+use Illuminate\Foundation\Http\Middleware\PreventRequestsDuringMaintenance as Middleware;
+
+class PreventRequestsDuringMaintenance extends Middleware
+{
+    /**
+     * The URIs that should be reachable while maintenance mode is enabled.
+     *
+     * @var array
+     */
+    protected $except = [
++        '/cloud-scheduler-job',
+    ];
 }
+
 ```
+</details>
 
 # Cloud Scheduler Example
 

UPGRADING.md

@@ -0,0 +1,19 @@
+# From 2.x to 3.x
+
+Support for Laravel 6, 7, 8, and 9 has been dropped. The minimum supported version is now Laravel 10.
+
+## Environment changes (Impact: high)
+
+Publish the new configuration file:
+
+```bash
+php artisan vendor:publish --tag=cloud-scheduler-config
+```
+
+Change the environment variables names:
+
+- `STACKKIT_CLOUD_SCHEDULER_APP_URL` -> `CLOUD_SCHEDULER_APP_URL`
+
+Add the following environment variable:
+
+- `CLOUD_SCHEDULER_SERVICE_ACCOUNT` - The e-mail address of the service account invocating the task.