Merge pull request #3 from plank/checkpoint-query-improvements

Checkpoint Query Improvements

.editorconfig

@@ -13,3 +13,6 @@ trim_trailing_whitespace = true
 
 [*.md]
 trim_trailing_whitespace = false
+
+[*.{yml,yaml}]
+indent_size = 2

.gitattributes

@@ -9,3 +9,7 @@
 /.scrutinizer.yml   export-ignore
 /tests              export-ignore
 /.editorconfig      export-ignore
+/.php_cs.dist       export-ignore
+/.github            export-ignore
+/psalm.xml          export-ignore
+/psalm.xml.dist     export-ignore

.github/workflows/tests.yml

@@ -0,0 +1,51 @@
+name: Tests
+
+on: [push, pull_request]
+
+jobs:
+  test:
+    runs-on: ${{ matrix.os }}
+    strategy:
+      fail-fast: true
+      matrix:
+        os: [ubuntu-latest]
+        php: [7.4]
+        laravel: [6.*, 7.*]
+        stability: [prefer-stable]
+        include:
+          - laravel: 7.*
+            testbench: 5.*
+          - laravel: 6.*
+            testbench: 4.*
+
+    name: P${{ matrix.php }} - L${{ matrix.laravel }} - ${{ matrix.stability }} - ${{ matrix.os }}
+
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v2
+
+      - name: Setup PHP
+        uses: shivammathur/setup-php@v2
+        with:
+          php-version: ${{ matrix.php }}
+          extensions: dom, curl, libxml, mbstring, zip, pcntl, pdo, sqlite, pdo_sqlite, bcmath, soap, intl, gd, exif, iconv, imagick
+          coverage: none
+
+      - name: Setup problem matchers
+        run: |
+          echo "::add-matcher::${{ runner.tool_cache }}/php.json"
+          echo "::add-matcher::${{ runner.tool_cache }}/phpunit.json"
+
+      - name: Cache dependencies
+        uses: actions/cache@v2
+        with:
+          path: ~/.composer/cache/files
+          key: dependencies-php-${{ matrix.php }}-laravel-${{ matrix.laravel }}-stability-${{ matrix.stability }}-composer-${{ hashFiles('composer.json') }}
+
+      - name: Install dependencies
+        run: |
+          composer require "laravel/framework:${{ matrix.laravel }}" "orchestra/testbench:${{ matrix.testbench }}" --no-interaction --no-update
+          composer update --${{ matrix.stability }} --prefer-dist --no-interaction
+
+      - name: Execute tests
+        run: vendor/bin/phpunit

.gitignore

@@ -1,9 +1,12 @@
-build
-composer.lock
+.idea
+.DS_Store
 docs
-vendor
+build
 coverage
-.idea
+vendor
+composer.lock
+.php_cs
 .php_cs.cache
-.DS_Store
-/.phpunit*
+.phpunit.result.cache
+phpunit.xml
+psalm.xml

README.md

@@ -1,8 +1,7 @@
 # Laravel Checkpoint 
 
 [![Latest Version on Packagist](https://img.shields.io/packagist/v/plank/laravel-checkpoint.svg?style=flat-square)](https://packagist.org/packages/plank/versionable)
-[![Build Status](https://img.shields.io/travis/plank/laravel-checkpoint/master.svg?style=flat-square)](https://travis-ci.org/plank/versionable)
-[![Quality Score](https://img.shields.io/scrutinizer/g/plank/laravel-checkpoint.svg?style=flat-square)](https://scrutinizer-ci.com/g/plank/versionable)
+[![GitHub Tests Action Status](https://img.shields.io/github/workflow/status/plank/laravel-checkpoint/tests?label=tests)](https://github.com/plank/laravel-checkpoint/actions?query=workflow%3Atests+branch%3Amaster)
 [![Total Downloads](https://img.shields.io/packagist/dt/plank/laravel-checkpoint.svg?style=flat-square)](https://packagist.org/packages/plank/versionable)
 
 ## Table of Contents
@@ -27,10 +26,10 @@
     - [Should Revision](#should-revision)
     - [Excluded Columns](#excluded-columns)
     - [Excluded Relations](#excluded-relations)
-    - [Testing](#testing)
-    - [Changelog](#changelog)
+  - [Testing](#testing)
+  - [Changelog](#changelog)
   - [Contributing](#contributing)
-    - [Security](#security)
+  - [Security](#security)
   - [Credits](#credits)
   - [License](#license)
 
@@ -113,8 +112,7 @@ This query scope will limit the query to return the *Model* whose ```Revision```
 the ```Revision``` was created at or before the given moment. 
 
 The moment can either be an instance of a ```Checkpoint``` 
-using its ```checkpoint_date``` field, or a string representation of a date compatible with ```Carbon::parse```, or a 
-```Carbon``` instance.
+using its ```checkpoint_date``` field, a string representation of a date or a ```Carbon``` instance.
 
 #### since($moment)
 ```php
@@ -126,24 +124,24 @@ since($moment = null)
 This query scope will limit the query to return the *Model* whose ```Revision``` has the max primary key, where
 the ```Revision``` was created after the given moment. 
 
-The moment can either be an instance of a ```Checkpoint``` using its ```checkpoint_date``` field, or a string
-representation of a date compatible with ```Carbon::parse```, or a ```Carbon``` instance.
+The moment can either be an instance of a ```Checkpoint``` using its ```checkpoint_date``` field, a string
+representation of a date or a ```Carbon``` instance.
 
 #### temporal($upper, $lower)
 ```php
 /**
  * @param $upper Checkpoint|Carbon|string
  * @param $upper Checkpoint|Carbon|string
  */
-temporal($upper = null, $lower = null)
+temporal($until = null, $since = null)
 ```
 This query scope will limit the query to return the *Model* whose ```Revision``` has the max primary key created at 
-or before ```$upper```. This method can also limit the query to the *Model* whose revision has the max primary key
-created after ```$lower```. 
+or before ```$until```. This method can also limit the query to the *Model* whose revision has the max primary key
+created after ```$since```. 
 
-Each argument operates independently of each other and ```$upper``` and ```$lower``` can 
-either be an instance of a ```Checkpoint``` using its ```checkpoint_date``` field, or a string representation of a date
-compatible with ```Carbon::parse```, or a ```Carbon``` instance.
+Each argument operates independently of each other and ```$until``` and ```$since``` can 
+either be an instance of a ```Checkpoint``` using its ```checkpoint_date``` field, a string representation of a 
+date or a ```Carbon``` instance.
 
 #### withoutRevisions()
 ```php
@@ -186,21 +184,21 @@ cases you can add the names of the relations to the``` protected $excludedRelati
 revisioning. Excluding all relations to the ```Checkpoint```s and other related ```Revision```s are handled by the 
 package.  
 
-### Testing
+## Testing
 
 ``` bash
 composer test
 ```
 
-### Changelog
+## Changelog
 
 Please see [CHANGELOG](CHANGELOG.md) for more information what has changed recently.
 
 ## Contributing
 
-Please see [CONTRIBUTING](CONTRIBUTING.md) for details.
+Please see [CONTRIBUTING](.github/CONTRIBUTING.md) for details.
 
-### Security
+## Security
 
 If you discover any security related issues, please email massimo@plankdesign.com instead of using the issue tracker.
 

composer.json

@@ -30,8 +30,9 @@
         "illuminate/support": "5.8.*|^6.0|^7.0|^8.0"
     },
     "require-dev": {
-        "orchestra/testbench": "^4.0",
-        "phpunit/phpunit": "^8.0"
+        "orchestra/testbench": "^4.8 || ^5.2",
+        "phpunit/phpunit": "^9.3",
+        "vimeo/psalm": "^3.11"
     },
     "autoload": {
         "psr-4": {
@@ -44,9 +45,9 @@
         }
     },
     "scripts": {
-        "test": "vendor/bin/phpunit",
+        "psalm": "vendor/bin/psalm",
+        "test": "vendor/bin/phpunit --colors=always",
         "test-coverage": "vendor/bin/phpunit --coverage-html coverage"
-
     },
     "config": {
         "sort-packages": true
@@ -57,5 +58,7 @@
                 "Plank\\Checkpoint\\CheckpointServiceProvider"
             ]
         }
-    }
+    },
+    "minimum-stability": "dev",
+    "prefer-stable": true
 }

config/checkpoint.php

@@ -1,34 +1,44 @@
 <?php
 
-/*
- * You can place your custom package configuration in here.
- */
 return [
 
     /*
-    |
-    | The full namespace to your User model class.
-    |
-    | If your application doesn't have a user class, the value should be "NULL".
-    |
-    */
-    'user_model' => '\App\User',
+     * When true, checkpoint will automatically hook its observer to the
+     * revisionable model events in order to create revisions when needed
+     */
+    'enabled' => env('CHECKPOINT_ENABLED', true),
 
     /*
-    |
-    | Concrete implementation for the "version model".
-    | To extend or replace this functionality, change the value below with your full "version model" FQCN.
-    |
-    */
-    'checkpoint_model' => \Plank\Checkpoint\Models\Checkpoint::class,
+     * When true, checkpoint will automatically apply the global revision scope
+     * onto revisionables for filtering out relevant content based on time
+     *
+     * ***warning***
+     * disabling after using the package will result in query results containing
+     * duplicate items as they won't automatically be filtered by time
+     */
+    'apply_global_scope' => env('REVISIONS_GLOBAL_SCOPE', env('CHECKPOINT_ENABLED', true)),
 
     /*
-    |
-    | Concrete implementation for the "version model".
-    | To extend or replace this functionality, change the value below with your full "version model" FQCN.
-    |
-    */
-    'revision_model' => \Plank\Checkpoint\Models\Revision::class,
+     * Should checkpoint run its default migrations
+     */
+    'run_migrations' => env('RUN_CHECKPOINT_MIGRATIONS', true),
 
+    'models' => [
+
+        /*
+         * When using the "HasRevisions" trait from this package, we need to know which model
+         * should be used to retrieve your revisions. To extend or replace this functionality,
+         * change the value below with your full "revision model" class name.
+         */
+        'revision' => Plank\Checkpoint\Models\Revision::class,
+
+        /*
+         * When using the "HasRevisions" trait from this package, we need to know which model
+         * should be used to retrieve your checkpoints. To extend or replace this functionality,
+         * change the value below with your full "checkpoint model" class name.
+         */
+        'checkpoint' => Plank\Checkpoint\Models\Checkpoint::class,
+
+    ],
 
 ];

phpunit.xml.dist

@@ -8,7 +8,8 @@
          convertNoticesToExceptions="true"
          convertWarningsToExceptions="true"
          processIsolation="false"
-         stopOnFailure="false">
+         stopOnFailure="false"
+>
     <testsuites>
         <testsuite name="Unit">
             <directory suffix="Test.php">./tests/Unit</directory>
@@ -17,16 +18,17 @@
             <directory suffix="Test.php">./tests/Feature</directory>
         </testsuite>
     </testsuites>
-    <filter>
-        <whitelist processUncoveredFilesFromWhitelist="true">
-            <directory suffix=".php">src/</directory>
-        </whitelist>
-    </filter>
+    <coverage processUncoveredFiles="true">
+        <include>
+            <directory suffix=".php">./src</directory>
+        </include>
+        <report>
+            <clover outputFile="build/logs/clover.xml"/>
+            <html outputDirectory="build/coverage"/>
+            <text outputFile="build/coverage.txt"/>
+        </report>
+    </coverage>
     <logging>
-        <log type="tap" target="build/report.tap"/>
-        <log type="junit" target="build/report.junit.xml"/>
-        <log type="coverage-html" target="build/coverage"/>
-        <log type="coverage-text" target="build/coverage.txt"/>
-        <log type="coverage-clover" target="build/logs/clover.xml"/>
+        <junit outputFile="build/report.junit.xml"/>
     </logging>
 </phpunit>

psalm.xml.dist

@@ -0,0 +1,16 @@
+<?xml version="1.0"?>
+<psalm
+        errorLevel="4"
+        findUnusedVariablesAndParams="true"
+        resolveFromConfigFile="true"
+        xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+        xmlns="https://getpsalm.org/schema/config"
+        xsi:schemaLocation="https://getpsalm.org/schema/config vendor/vimeo/psalm/config.xsd"
+>
+    <projectFiles>
+        <directory name="src"/>
+        <ignoreFiles>
+            <directory name="vendor"/>
+        </ignoreFiles>
+    </projectFiles>
+</psalm>

src/CheckpointServiceProvider.php

@@ -23,15 +23,14 @@ public function boot()
             foreach (File::glob(__DIR__ . '/../database/migrations/*') as $migration) {
                 $basename = strstr($migration, 'create');
                 if (empty(File::glob(database_path('migrations/*' . $basename)))) {
-                    config()->set('checkpoint.runs_migrations', true);
                     $this->publishes([
                         $migration => database_path("migrations/". date('Y_m_d_His') . "_" . $basename)
                     ], 'migrations');
                 }
             }
 
             // Load default migrations if the runs_migrations toggle is true in the config (or if any of the expected files is missing)
-            if (config('checkpoint.runs_migrations', false)) {
+            if (config('checkpoint.run_migrations')) {
                 $this->loadMigrationsFrom(__DIR__ . '/../database/migrations');
             }
 

src/Commands/StartRevisioning.php

@@ -45,7 +45,7 @@ public function handle()
     {
         $checkpoint = null;
         if ($this->option('with-checkpoint')) {
-            $checkpointClass = config('checkpoint.checkpoint_model');
+            $checkpointClass = config('checkpoint.models.checkpoint');
             $checkpoint = $checkpointClass::first() ?? new $checkpointClass();
             $checkpoint->save();
             $checkpoint->refresh();
@@ -67,10 +67,8 @@ public function handle()
         foreach ($models as $class) {
             $records = $class::withoutGlobalScopes()->chunk(100, function ($results) use ($checkpoint, &$timeDelta) {
                foreach ($results as $item) {
-                   $item->updateOrCreateRevision();
+                   $item->startRevision();
                    $revision = $item->revision;
-                   // TODO: shouldn't be required for global query anymore.
-                   $revision->created_at = $item->freshRevisionCreatedAt();
                    $revision->checkpoint()->associate($checkpoint);
                    $revision->save();
                }